Skip to content

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.

Publish /trips/lofoten-kayak repository_dispatch cms-orbit-publish npm ci, npm run build Deploy the new files Editor CMS Orbit GitHub Actions northwilds.com
An editor publishes a trip and the website is built again

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.

  1. On GitHub, open Settings › Developer settings › Personal access tokens › Fine-grained tokens and select Generate new token.
  2. In Resource owner, choose the account or organisation that owns the repository, such as northwilds.
  3. Set an Expiration. When it runs out, builds stop starting, so put a reminder in the calendar.
  4. Under Repository access, choose Only select repositories and pick the website's repository, such as northwilds/northwilds.com.
  5. Under Permissions › Repository permissions, set Contents to Read and write. That is what repository_dispatch needs. Metadata: Read-only is added for you. Leave everything else as No access.
  6. 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.

  1. Open Configuration › Webhooks and find GitHub under the list of webhooks.
  2. Select Connect a repository.
  3. In Repository, enter owner/name, such as northwilds/northwilds.com. A pasted address such as https://github.com/northwilds/northwilds.com works too.
  4. In Access token, paste the token.
  5. Leave Event type as cms-orbit-publish unless your workflow listens for another name.
  6. In Environment, choose the environment the website reads, usually Production. Connect a second time for a staging website.
  7. 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.
  8. 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:

YAML
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:

JSON
{  "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"}
event
Holds
The webhook event, such as content.published or release.published
space
Holds
The space's id and name
environment
Holds
The environment's key, such as production or staging
region, locale
Holds
The region key and language code of the page, or null when the event isn't about one page
content
Holds
For page events: the page's id, url, name and type, and previousUrl when it moved
data
Holds
For other events, such as a release or a menu: what the webhook would carry in data
sentAt
Holds
When it was sent, in UTC
test
Holds
true 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.

.github/workflows/deploy.ymlYAML
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@v4
  • concurrency cancels 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_KEY is 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.
  • out is where Next.js writes a static export. Astro, Nuxt, SvelteKit and others use dist, .output/public or build; 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 answers 204 when 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

"GitHub refused the token" (401 or 403)
Likely cause and fix
The token has expired or was revoked, lacks Contents: Read and write, or an organisation owner hasn't approved it yet. Create a new token as above, select Edit and paste it.
"Repository not found, or the token can't see it" (404)
Likely cause and fix
The name is wrong, or the token's Repository access doesn't include this repository. Check owner/name and the token's repositories. GitHub answers 404 rather than 403 for a repository the token can't see.
422
Likely cause and fix
GitHub refused the event itself, for example an event type longer than 100 characters. The message after the code says why.
GitHub answered 204, but no run appears
Likely cause and fix
The workflow file isn't on the default branch, or its types: doesn't match the Event type exactly. Check both, and check that Actions are allowed under the repository's Settings › Actions.
A run starts, but the page is unchanged
Likely cause and fix
The build read another environment, or the host still serves its cache. Check CMS_PUBLIC_KEY comes from the environment the connection listens to, and look at the run's build log.
Nothing in Deliveries
Likely cause and fix
The connection is off, its Environment doesn't include where the change was made, or the event isn't ticked.
Many runs for one release
Likely cause and fix
A release sends one event per page and one for the release. Keep concurrency with cancel-in-progress: true so only the last build deploys.

Was this page helpful?

Read next