Rebuild a static website with GitHub Actions
Connect a GitHub repository so publishing starts a GitHub Actions build of a static website on GitHub Pages, Cloudflare Pages or Amazon S3, with the token, the workflow trigger, what each event carries and what to do when GitHub says no.
How-to guide7 min read
What it does
A static website is built once into plain HTML files and served from a host such as GitHub Pages, Cloudflare Pages or Amazon S3. Nothing on the host can refresh a page when content changes, so the website has to be built again.
A GitHub connection does that for you. When an editor publishes, CMS Orbit asks GitHub to start your website's workflow, by sending a repository_dispatch event to the repository. The workflow builds the website with the new content and deploys it.
A build takes a few minutes, so changes reach the website more slowly than with a webhook on a website with a server. Use a webhook when the website can refresh a page by itself.
Create the token
CMS Orbit needs a token that may start workflows in the repository. Use a fine-grained personal access token that can see only that repository.
- On GitHub, open Settings › Developer settings › Personal access tokens › Fine-grained tokens and select Generate new token.
- In Resource owner, choose the account or organisation that owns the repository, such as
northwilds. - Set an Expiration. When it runs out, builds stop starting, so put a reminder in the calendar.
- Under Repository access, choose Only select repositories and pick the website's repository, such as
northwilds/northwilds.com. - Under Permissions › Repository permissions, set Contents to Read and write. That is what
repository_dispatchneeds. Metadata: Read-only is added for you. Leave everything else as No access. - Select Generate token and copy it. It starts with
github_pat_.
If the repository belongs to an organisation, an owner of that organisation may need to approve the token first.
A token from a GitHub App installation with the same permission works too, but it runs out after an hour, so it only suits a short test.
Connect the repository
You need the Developer, Administrator or Owner role, the same as for webhooks. Others don't see the GitHub section.
- Open Configuration › Webhooks and find GitHub under the list of webhooks.
- Select Connect a repository.
- In Repository, enter
owner/name, such asnorthwilds/northwilds.com. A pasted address such ashttps://github.com/northwilds/northwilds.comworks too. - In Access token, paste the token.
- Leave Event type as
cms-orbit-publishunless your workflow listens for another name. - In Environment, choose the environment the website reads, usually Production. Connect a second time for a staging website.
- Under Events, Page published, Page unpublished and Release published are ticked for you. Tick Page deleted and Menu changed too if the website shows menus.
- Select Save, then open the ⋯ menu on the new row and select Send a test.
The token is stored encrypted. It is never shown again, in CMS Orbit or through the API: the screen only shows its last four characters. To change it, select Edit, paste the new token and save. Leave the field empty to keep the one you have.
Saving, editing, testing and removing a connection are recorded in the organisation's audit trail, without the token.
Add the trigger to your workflow
Add repository_dispatch to the workflow's on: section, with the same event type:
on: repository_dispatch: types: [cms-orbit-publish]GitHub only runs repository_dispatch workflows that are on the repository's default branch, usually main.
What the event carries
GitHub passes what CMS Orbit sends to the workflow as github.event.client_payload:
{ "event": "content.published", "space": { "id": "6650f1c2a9e4b3d2c1f0e901", "name": "Northwilds website" }, "environment": "production", "region": "uk", "locale": "en-GB", "content": { "id": "6650f1c2a9e4b3d2c1f0ea07", "url": "/trips/lofoten-kayak", "name": "Lofoten kayak trip", "type": "tripPage" }, "sentAt": "2026-11-10T09:30:00.412Z"}eventspaceenvironmentproduction or stagingregion, localenull when the event isn't about one pagecontentid, url, name and type, and previousUrl when it moveddatadatasentAttesttrue for Send a test, and missing otherwise. A test has event: "github.test"Read it in a step with ${{ github.event.client_payload.content.url }}. Most static websites ignore it and build everything.
A complete workflow
This workflow builds a website with Node 24 and deploys it to GitHub Pages. It also runs on a push to main and from the Actions tab.
name: Build and deploy northwilds.comon: push: branches: [main] workflow_dispatch: repository_dispatch: types: [cms-orbit-publish]permissions: contents: read pages: write id-token: writeconcurrency: group: pages cancel-in-progress: truejobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 24 cache: npm - run: npm ci - name: Build run: npm run build env: CMS_API_URL: https://api.bifrostorbit.com/cms CMS_PUBLIC_KEY: ${{ secrets.CMS_PUBLIC_KEY }} CMS_DEFAULT_REGION: uk - if: github.event_name == 'repository_dispatch' run: echo "Built for ${{ github.event.client_payload.event }} ${{ github.event.client_payload.content.url }}" - uses: actions/upload-pages-artifact@v3 with: path: out deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment uses: actions/deploy-pages@v4concurrencycancels a build that is still running when a newer one starts. Publishing ten pages in a row then ends in one deploy with all ten, not ten deploys.CMS_PUBLIC_KEYis a public key from the environment the website reads. Store it under the repository's Settings › Secrets and variables › Actions. It is not the GitHub token.outis where Next.js writes a static export. Astro, Nuxt, SvelteKit and others usedist,.output/publicorbuild; use your framework's folder.
For Cloudflare Pages, replace the upload-pages-artifact step and the deploy job with cloudflare/wrangler-action@v3 and the command pages deploy out --project-name=northwilds. For Amazon S3, sign in with aws-actions/configure-aws-credentials@v4 and run aws s3 sync out s3://northwilds-website --delete. Deploy your website explains how to build every page of a static website.
Test it and read the delivery log
In the ⋯ menu of the connection's row:
- Send a test sends the event type straight away with
test: true, whatever the connection's environment and even when it is off. A message then shows GitHub's answer. GitHub answers204when it accepts the event; the run then appears in the repository's Actions tab within a few seconds. - Deliveries shows the latest 50 events sent to this repository, with GitHub's answer. Failures are shown in red. Point at one to see why it failed.
Each event is sent once, at the moment of the change, the same as a webhook. A failure is recorded but not sent again. After 20 failures in a row the connection switches itself off. Fix the cause, send a test, then turn the On switch back on, which also sets the failure count to zero. Changes made while it was off were not sent, so start the workflow by hand from the Actions tab.
Troubleshooting
401 or 403)404)owner/name and the token's repositories. GitHub answers 404 rather than 403 for a repository the token can't see.422204, but no run appearstypes: doesn't match the Event type exactly. Check both, and check that Actions are allowed under the repository's Settings › Actions.CMS_PUBLIC_KEY comes from the environment the connection listens to, and look at the run's build log.concurrency with cancel-in-progress: true so only the last build deploys.Was this page helpful?