GitHub

What it does

• Pull in CI: a GitHub Actions workflow runs stoaken export --check on pull requests, so a build fails when committed token files are behind the live release.
• Push on publish: a Stoaken webhook sent as a GitHub repository dispatch starts the same workflow when a release is published. It runs stoaken export and opens a pull request on the stoaken/tokens branch.

Before you start

• A Stoaken API key (Settings > API keys) and a stoaken.config.json with an exports list (see /docs/cli).
• Brand Admin on the Brand (webhooks are part of the Team plan).
• A fine-grained GitHub personal access token for this one repository with Contents: read and write. GitHub's dispatch endpoint needs that permission (docs).
• In the repository's Settings > Actions > General, allow GitHub Actions to create pull requests.

Setup

1. Add the secret STOAKEN_TOKEN (your API key) under Settings > Secrets and variables > Actions.
2. Commit .github/workflows/stoaken-tokens.yml (the template below).
3. In Stoaken, go to Settings > Webhooks and choose Add a webhook:
   • Send as: GitHub repository dispatch
   • Address: https://api.github.com/repos/OWNER/REPO/dispatches
   • Access token: the fine-grained token. It's stored encrypted and never shown again.
   • Events: Release published only.

name: Stoaken tokens
on:
  pull_request:
  workflow_dispatch:
  repository_dispatch:
    types: [stoaken-release-published]
permissions:
  contents: write
  pull-requests: write
jobs:
  check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npx --yes stoaken@latest export --check
        env:
          STOAKEN_TOKEN: ${{ secrets.STOAKEN_TOKEN }}
  update:
    if: github.event_name != 'pull_request'
    # … export, commit to stoaken/tokens, `gh pr create` (full file: src/lib/integrations/pipelines.ts)

For your own workflows, the composite action in integrations/github-action/ wraps the same command: uses: ./integrations/github-action with token: ${{ secrets.STOAKEN_TOKEN }} and, optionally, check: 'true'.

Configuration

• The dispatch's event_type is stoaken-release-published (and stoaken-ping for Send test, which the workflow ignores).
• The client_payload has type, delivery_id, release_id, theme_id, brand_id, version, is_breaking, changes and test. GitHub allows at most 10 top-level keys. Read them as github.event.client_payload.version.
• Requests send Authorization: Bearer <token>, Accept: application/vnd.github+json and X-GitHub-Api-Version: 2022-11-28. Stoaken only sends the token to https://api.github.com/repos/…/dispatches, and the database refuses any other address for this format.

Try it

1. On the webhook, choose Send test. GitHub should answer 204, and no workflow runs, because stoaken-ping isn't listed.
2. In the webhook lab, choose Send a sample with Release published. A workflow run appears under Actions and opens a pull request if the export changed anything.
3. Open any pull request and look for the check job.

Troubleshooting

• 401/403: the token has expired, doesn't cover this repository, or lacks Contents: write.
• 404: the owner or repository in the address is wrong, or the token can't see a private repository.
• 422: GitHub refused the body. Check the format is GitHub repository dispatch, not Stoaken event.
• The check doesn't run on the bot's pull request: GitHub doesn't start workflows from pushes made with GITHUB_TOKEN. Re-run it by hand, or push with a separate token.
• stoaken export errors are explained in /docs/cli.

Limits

• No GitHub App or OAuth: you manage the token, and it can expire.
• One repository per webhook. A Brand has at most 10 webhooks.
• Failed deliveries retry for about a day (/docs/webhooks).