# 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.

Source: https://docs.bifrostorbit.com/cms/developers/github-actions/

## 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`](https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event) event to the repository. The workflow builds the website with the new content and deploys it.

```mermaid title="An editor publishes a trip and the website is built again"
sequenceDiagram
  participant E as Editor
  participant C as CMS Orbit
  participant G as GitHub Actions
  participant H as northwilds.com
  E->>C: Publish /trips/lofoten-kayak
  C->>G: repository_dispatch cms-orbit-publish
  G->>G: npm ci, npm run build
  G->>H: Deploy the new files
```

A build takes a few minutes, so changes reach the website more slowly than with a [webhook](https://docs.bifrostorbit.com/cms/developers/webhooks/) 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"
}
```

| Field | Holds |
| --- | --- |
| `event` | The [webhook event](https://docs.bifrostorbit.com/cms/developers/webhooks/), such as `content.published` or `release.published` |
| `space` | The space's id and name |
| `environment` | The environment's key, such as `production` or `staging` |
| `region`, `locale` | The region key and language code of the page, or `null` when the event isn't about one page |
| `content` | For page events: the page's `id`, `url`, `name` and `type`, and `previousUrl` when it moved |
| `data` | For other events, such as a release or a menu: what the webhook would carry in `data` |
| `sentAt` | When it was sent, in UTC |
| `test` | `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.

```yaml
# .github/workflows/deploy.yml
name: Build and deploy northwilds.com

on:
  push:
    branches: [main]
  workflow_dispatch:
  repository_dispatch:
    types: [cms-orbit-publish]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  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](https://docs.bifrostorbit.com/cms/developers/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

| What you see | Likely cause and fix |
| --- | --- |
| "GitHub refused the token" (`401` or `403`) | 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`) | 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` | 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 | 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 | 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** | 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 | 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. |
