Docs

Deploy to GitHub Pages with pushd

GitHub Pages has hosted millions of sites since 2008 and keeps every version of your site automatically. Normally it’s the most technical option - but thats not a problem with pushd.

What you need

• A free GitHub account
• A classic personal access token with repo scope (below)

Create the token

1. In pushd, select GitHub Pages and click Get token ↗ - it opens GitHub’s new token page with the name and repo scope already pre-filled.
2. Select an expiry duration, but note if you lose the token or it expires you’ll need to create a new one, and while it remains expired your deploys will fail.
3. Scroll down and click Generate token. The settings are done for you.
4. Copy the token (GitHub shows it once).

Connect it

Paste the token into pushd’s token field. If successful, you’ll see a “Connected as” message, meaning you’re all set.

Your token is stored only in your browser’s local extension storage and sent only to GitHub’s servers over HTTPS. pushd doesn’t store or track it remotely.

The repo scope lets pushd create and update the repositories your sites live in. If you keep other code on this GitHub account, note the scope covers all your repos - pushd only ever touches repos it created (there’s an explicit guard, below), but you can also use a fresh GitHub account for sites.

How it works (and where your site lives)

Each site gets its own free public repository named after your site. pushd creates it, uploads your files to it, switches GitHub Pages on, and waits until the site is serving - first deploys can take a minute or two while GitHub builds.

Your URL: https://your-username.github.io/your-site-name/.

Two things follow from the public repo:

• Your site’s source files are browsable on github.com. For a web page that’s usually fine - the page is public anyway.
• Every deploy is a commit, so GitHub keeps the full version history of your site forever, free. No other provider here does that.

Updating

Same site name = a new commit to the same repository = same URL. Updates typically appear within a minute (GitHub rebuilds the site). New name = new repository and URL.

The repo guard: if a repository with your chosen name already exists but pushd didn’t create it, pushd refuses rather than touching it: “You already have a GitHub repository called “{name}” that pushd didn’t create - pick a different site name so we don’t touch it.“ If you do want to deploy into it, tick “Overwrite if this name already exists”.

Clean deploys: by default pushd adds/updates files but leaves anything else in the repo alone. While this stops things being deleted it can accumulate stale images, pages etc. To battle this, turn on “Clean deploys on GitHub Pages” in Dashboard Preferences and each deploy makes the repo contain exactly the files you pushed. This functions as a delete mechanism, but as Github tracks every commit, files are still recoverable if you change your mind.

Limits worth knowing

1GB per site, 100GB traffic/month (soft limit), 100MB per file. Sites are plain static hosting - no server code.

Errors you might see

• “Token looks wrong - double-check it on github.com.” Invalid or expired token - generate a fresh one from pushd’s pre-filled link.
• “GitHub rate limit hit - wait a few minutes and try again.” Self-explanatory; it resets.
• “GitHub Pages could not build the site.” Rare for plain HTML. Re-push; if it persists, check the repository’s Actions tab on github.com for the build error.
• The repo-collision message quoted above - rename the site or tick overwrite.

More fixes: Troubleshooting.