Skip to content

How to Set Up DOCS_TRIGGER_TOKEN

This guide explains how to set up the DOCS_TRIGGER_TOKEN secret required for the multi-repository documentation build system.

Overview

The unified documentation site (docs.syrf.org.uk) aggregates documentation from three repositories:

  • syrf (main repo with MkDocs configuration)
  • cluster-gitops (GitOps operations documentation)
  • camarades-infrastructure (Infrastructure documentation)

When documentation changes in cluster-gitops or camarades-infrastructure, a repository dispatch event is triggered to rebuild the docs in the syrf repository.

Why a Personal Access Token is Needed

The default GITHUB_TOKEN in GitHub Actions has limited permissions and cannot trigger workflows in other repositories. A Personal Access Token (PAT) with repo scope is required to send repository dispatch events across repositories.

Setup Steps

1. Create a Personal Access Token

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)

  2. Or visit: https://github.com/settings/tokens

  3. Click "Generate new token" → "Generate new token (classic)"

  4. Configure the token:

  5. Note: SyRF Docs Repository Dispatch
  6. Expiration: Choose an expiration (90 days recommended, or "No expiration" for production)

  7. Scopes: Select repo (Full control of private repositories)

    • This grants access to trigger workflows via repository dispatch

  8. Click "Generate token"

  9. IMPORTANT: Copy the token immediately - you won't be able to see it again!

2. Add Secret to cluster-gitops Repository

  1. Go to https://github.com/camaradesuk/cluster-gitops/settings/secrets/actions

  2. Click "New repository secret"

  3. Configure the secret:

  4. Name: DOCS_TRIGGER_TOKEN

  5. Value: Paste the PAT you created in step 1

  6. Click "Add secret"

3. Add Secret to camarades-infrastructure Repository

  1. Go to https://github.com/camaradesuk/camarades-infrastructure/settings/secrets/actions

  2. Click "New repository secret"

  3. Configure the secret:

  4. Name: DOCS_TRIGGER_TOKEN

  5. Value: Paste the same PAT you created in step 1

  6. Click "Add secret"

Verification

To verify the setup works:

  1. Make a change to documentation in cluster-gitops or camarades-infrastructure

  2. Edit any file in docs/ or change mkdocs.yml

  3. Commit and push to the master branch

  4. Check the Actions tab in the respective repository:

  5. You should see the "Trigger Docs Rebuild" workflow running

  6. Check the Actions tab in the syrf repository:

  7. You should see the "Docs Rebuild (Repository Dispatch)" workflow running
  8. This workflow will build and push a new docs image

Troubleshooting

Workflow doesn't trigger in syrf repository

Possible causes:

  1. DOCS_TRIGGER_TOKEN secret not set or incorrect
  2. PAT doesn't have repo scope
  3. PAT has expired

Solution: Regenerate the PAT and update the secrets in both repositories.

Permission denied errors

Cause: The PAT doesn't have sufficient permissions.

Solution: Ensure the PAT has the repo scope selected.

Workflow triggers but fails

Cause: The syrf repository workflow may have issues.

Solution: Check the workflow logs in the syrf repository for specific error messages.

Security Best Practices

  1. Use a dedicated bot account: Consider creating a GitHub bot account specifically for automation tasks
  2. Set expiration dates: Use token expiration dates (e.g., 90 days) and set calendar reminders to rotate tokens
  3. Limit scope: Only grant the repo scope - don't add unnecessary permissions
  4. Monitor usage: Regularly review the token's usage in GitHub Settings
  5. Rotate tokens: Regenerate tokens periodically (every 3-6 months)

Token Rotation Process

When the token expires or needs rotation:

  1. Generate a new PAT following step 1 above
  2. Update the secret in cluster-gitops following step 2
  3. Update the secret in camarades-infrastructure following step 3
  4. Test by making a documentation change
  5. Delete the old PAT from GitHub Settings

References