EtherPK Blog

Publish Your Site Straight To GitHub

EtherPK can now publish a site straight to a branch of a GitHub repository. Each publish is one commit, and the host that watches the branch deploys it. GitHub Pages, Cloudflare and Netlify all deploy a push this way. You need no folder, no git and no terminal on your device, so you can publish from any browser, a phone included.

I publish this blog and docs.etherpk.com with EtherPK. Before this change, each update took four steps: publish into a folder, commit, push, and wait for the host. The first three needed a desktop browser that can write to a folder, and a git checkout of the site on the same computer. Publishing to GitHub replaces those three steps with one button.

Make a GitHub token

EtherPK commits with your own GitHub token. Give the token access to the site's repository only, with permission to change its contents and nothing else.

  1. On GitHub, open Settings > Developer settings > Fine-grained tokens > Generate new token.
  2. Enter a name and an expiry date. When the token expires, make a new one and replace the old one in EtherPK.
  3. For Resource owner, select the account or organisation that owns the site's repository. If an organisation owns it, an owner of that organisation might have to approve the token before it works.
  4. For Repository access, select Only select repositories, and then select the site's repository.
  5. Under Permissions, on the Repositories tab, select Add permissions. Search for Contents and select it.
  6. In the permissions list, set the access for Contents to Read and write. GitHub adds Metadata, with read-only access, by itself.
  7. Select Generate token and copy the token.

Connect the publication to the repository

  1. In EtherPK, open the graph that holds the site, and open Settings > Publish. The shortcut is Alt+P.
  2. On the publication's card, under Publish to, select A GitHub repository. A GitHub section appears at the top of the tab.
  3. In the GitHub section, paste the token into GitHub token and select Save token. EtherPK does not show the token again.
  4. On the card, enter the repository as owner/name, or paste its address on GitHub. Enter the branch, or keep main.
  5. Select Save and check. EtherPK checks that the token can read the branch and write to the repository.

When the check succeeds, the card shows "Ready. The token can write to owner/name on main." If the branch does not exist, the card says so and shows Create branch. A publish never creates a branch by itself. A typing error in the branch name would otherwise send the site to a branch that no host watches. Create branch makes a branch that holds only a README and shares no history with the other branches. If the repository has no commits, Create branch makes its first commit.

If the check fails, the card says why and what to do. The fields keep what you typed. The most frequent causes are:

  • The token expired.
  • The token does not include the repository.
  • The token can read the repository but cannot write to it.

EtherPK keeps the token with your settings, not with the graph. If your settings sync to your account, the token goes with them to your other devices. EtherPK keeps the repository and branch on each device, for each publication, the same as a publish folder.

Publish

Select Publish to GitHub, or press Alt+Shift+P. The progress notice shows each step: Reading the graph, Rendering, Reading the branch, Uploading and Committing. When the publish is complete, the report on the card links to the commit on GitHub.

EtherPK compares each file with the file on the branch before it sends anything. It sends only the files that changed, and it removes old files that are not part of the site. If nothing changed, EtherPK makes no commit.

Text files go in the commit itself. EtherPK uploads each new or changed image or font separately, one each second, because GitHub limits how fast a token can write. The first publish of a site with many images takes longer than the publishes after it. If GitHub asks EtherPK to wait, the progress notice shows the time when the publish continues.

EtherPK changes only the files that it writes. It does not change CNAME, robots.txt or other files that you add to the branch. On the first publish it also adds a README, a .gitignore, a wrangler.jsonc, an .assetsignore and an AGENTS.md if the branch does not have them. It does not add the GitHub Actions workflow that a folder publish adds, because a token needs one more permission to add a workflow file.

If the branch already holds other files, and its AGENTS.md does not name this publication, the first publish stops before it changes anything. The card shows the number of files that the publish would replace or remove, and the first file names. To continue, select Publish and replace, which shows the number of files. To stop, select Cancel. EtherPK refuses a branch that holds an EtherPK graph, because a publish would remove the graph's files.

Deploy the branch

The site files need no build step. Configure your host to deploy the branch:

  • GitHub Pages: in the repository's Settings > Pages, set Source to Deploy from a branch, and select the branch and / (root).
  • Cloudflare: in the dashboard, select Workers & Pages > Create > Import a repository. Select the repository, and keep the build command empty. In the wrangler.jsonc that EtherPK adds, the Worker's name is the publication id.
  • Netlify: import the repository, keep the build command empty, and use the repository root as the publish directory.

Hosting a published site has the steps for each host, and for a custom domain.

Keep the token safe

Give the token access to the site's repositories only, with Contents only. EtherPK community extensions are reviewed before they are listed, but they run in EtherPK's browser tab and have the potential to read data from it. An agent that signs in to your account through the Headless Client cannot read the token.

What you publish stays in the repository's history. If the repository is public, anyone can read that history. Each commit message contains only the publication id and two counts, for example Publish etherpk-blog: 3 written, 1 removed. The publish report lists the documents that the site leaves out, and it never goes into a commit.

If a branch protection rule requires a pull request or a signed commit, GitHub refuses the commit. Publish to a branch that has no such rule, for example gh-pages, and deploy that branch.

Publish from the command line

The Headless Client publishes to the same kind of branch from a terminal or a scheduled job. Put the token in ETHERPK_GITHUB_TOKEN, and give the repository with --github:

ETHERPK_GITHUB_TOKEN=<your_token> npx @appsoftwareltd/etherpk-mcp publish --folder ~/notes/blog --publication blog --github you/blog-site

The Headless Client remembers the repository, so the next publish needs only the token, the folder and the publication id. Add #branch after the repository name for a branch other than main. If the branch holds other files, the first publish lists them and stops. Run the command again with --replace to continue.

An AI agent connected through the Headless Client can check a publication with a dry run, but its publish tool never commits to a repository. A commit can put the site live, so only you start that step.