GitHub Pages is one of the best deals on the web: free hosting for a website, with HTTPS, on your own domain if you have one. It has a reputation for being a developer’s tool, and the usual instructions don’t help. They start with installing git and end with a build pipeline.
Underneath, Pages is much simpler than that. It serves the files in a repository. If you can get a folder of HTML into a repository, you have a website, and there are ways to do that which involve no git and no terminal at all.
What GitHub Pages actually does
You tell Pages where to look, and it serves what it finds there. There are two choices, under Settings → Pages in the repository.
- Deploy from a branch. Pages serves the files on a branch you name, either from the top of the branch or from a folder called
docs. Those are the only two places it will look. - GitHub Actions. A workflow builds your site and hands the result to Pages. This is the developer route.
For a blog that is already a folder of finished HTML, the first is all you need.
Two small files matter more than their size suggests.
| File | What it does |
|---|---|
.nojekyll | By default GitHub runs your files through Jekyll, its built-in site generator, before serving them. An empty file with this name tells it not to. If your site is already built, you want this. |
CNAME | When you set a custom domain in the repository’s settings, GitHub records it in this file on the branch. If the file disappears, so does your domain setting. |
That second one catches people out. Any tool that replaces the branch with a fresh copy of your site has to carry the CNAME file over, or your domain is reset on every publish.
What it costs, and its limits
Pages is free for public repositories. GitHub’s own figures are worth knowing before you build on it.
| Limit | Figure |
|---|---|
| Size of the published site | 1 GB |
| Recommended size of the repository | 1 GB |
| Bandwidth | A soft limit of 100 GB a month |
| Builds | A soft limit of 10 an hour, when GitHub builds the site for you |
For a blog made of words and reasonably sized photos, that is a great deal of room. A site heavy with video is a poor fit.
One thing surprises people: a site published from a private repository is still public. On GitHub’s free plan, Pages only works with public repositories at all. Pages from a private repository needs a paid plan, and even then the website itself can be read by anyone. Private means the repository, not the site.
Ways to publish without git
Upload in the browser. GitHub’s website lets you add files to a repository by dragging them in. It works, and it is free. It also gets old quickly: you rebuild your site somewhere, then drag the changed files in by hand, every time you write a post.
Use an app that talks to GitHub for you. GitHub has an API, and an app can use it to make a commit on your behalf, with no git involved at your end. You write, press publish, and a commit appears in the repository. This is the comfortable way to do it.
For an app to do that, it needs permission, and GitHub offers a careful way to give it.
Giving an app access, safely
A fine-grained personal access token is a password for one job. When you create one you choose Only select repositories and pick the single repository your site lives in, then grant one permission: Contents, with write access. That token can change the files in that repository and nothing else in your account.
You can give a token an expiry date. If you do, set a reminder, because publishing stops on that day until you make a new one.
Some apps offer to sign in with GitHub instead, where you approve the app on GitHub’s own site and choose which repositories it may reach. The effect is the same, without a token to copy.
Either way, look for the same two properties: access limited to the repository you chose, and no more permission than the job needs.
Your own domain
A github.io address is fine to start with. To use your own domain you add a few DNS records, enter the domain under Settings → Pages, and tick Enforce HTTPS once GitHub has issued the certificate, which it does for you. The records themselves are in Custom domain DNS for GitHub Pages, Netlify and Cloudflare Pages.
A free version history, by accident
Because every publish is a commit, the repository keeps every version of your site. You can see what changed on any day, and get an old version back. Most hosting charges for backups. Here it is a side effect.
Where Selfish fits
Selfish is a native app for iPhone, iPad and Mac. You write in it, it builds a static site, and it publishes that site to GitHub Pages, among other places.
- No git. Each publish is one commit, made through GitHub’s API.
- Sign in with GitHub, or use a fine-grained token limited to one repository. Selfish opens GitHub’s token page with the right permission already chosen.
- It turns Pages on when you first publish, if you are signed in.
- Your custom domain survives. The
CNAMEfile is carried over on every publish, and a.nojekyllfile is written for you. - Only changed files are uploaded, so a photo-heavy blog republishes quickly.
- When you are signed in, its connection test tells you if Pages is switched off, or is serving a different branch from the one you publish to.
It is on the App Store as a one-time purchase, at a £3.99 introductory price, rising to £9.99 in December. The GitHub Pages docs walk through the setup, and Selfish vs Hugo and Jekyll is for anyone wondering whether to use a generator instead.