Setup Cross-Repository Documentation Triggers¶

Purpose¶

This guide explains how to set up automated documentation rebuilds when documentation changes in any of the three repositories that make up the unified documentation site at https://docs.syrf.org.uk.

Architecture Overview¶

The SyRF documentation is aggregated from 3 repositories:

syrf/docs/                      → Application architecture, development guides
cluster-gitops/docs/            → Deployment operations, GitOps workflows
camarades-infrastructure/docs/  → Infrastructure operations, Terraform guides

All three are combined into a single MkDocs site published at https://docs.syrf.org.uk.

How Cross-Repo Triggering Works¶

┌─────────────────────────────────────────────────────────────────────┐
│                     Documentation Change Flow                        │
└─────────────────────────────────────────────────────────────────────┘

1. Developer pushes changes to cluster-gitops/docs/
   ↓
2. cluster-gitops/.github/workflows/docs-trigger.yml runs
   ↓
3. Sends repository_dispatch event to syrf repository
   ↓
4. syrf/.github/workflows/docs-rebuild.yml receives event
   ↓
5. Checks out all 3 repos' docs directories
   ↓
6. Builds unified MkDocs site → Docker image
   ↓
7. Pushes to GHCR → ghcr.io/camaradesuk/syrf-docs:latest
   ↓
8. ArgoCD deploys to https://docs.syrf.org.uk

Prerequisites¶

GitHub App configured with access to all 3 repositories
APP_ID and APP_PRIVATE_KEY secrets in all 3 repositories
See setup-gitops-github-app.md for GitHub App setup

Setup Instructions¶

Step 1: Enable Cross-Repo Triggers in syrf Repository¶

The docs-rebuild.yml workflow is already configured in this repository.

Location: .github/workflows/docs-rebuild.yml

What it does:

Listens for repository_dispatch events with type docs-update
Checks out docs from all 3 repositories
Builds unified Docker image
Publishes to GHCR
Creates GitHub Release

Verify it exists:

ls -la .github/workflows/docs-rebuild.yml

✅ If it exists, this step is complete!

Step 2: Add Trigger Workflow to cluster-gitops¶

Copy the workflow file to cluster-gitops:

# On your local machine
cd /path/to/syrf/

# Copy the template workflow
cp docs/how-to/cluster-gitops-docs-trigger.yml \
   cluster-gitops/.github/workflows/docs-trigger.yml

# Commit and push
cd cluster-gitops
git add .github/workflows/docs-trigger.yml
git commit -m "feat(docs): add cross-repo documentation rebuild trigger"
git push

Verify the branch name:

The workflow assumes main branch. If cluster-gitops uses master, update the workflow:

on:
  push:
    branches:
      - master  # Change from 'main' if needed

Step 3: Add Trigger Workflow to camarades-infrastructure¶

Copy the workflow file to camarades-infrastructure:

# On your local machine
cd /path/to/your/workspace/syrf/

# Create .github/workflows directory if it doesn't exist
mkdir -p camarades-infrastructure/.github/workflows

# Copy the template workflow
cp docs/how-to/camarades-infrastructure-docs-trigger.yml \
   camarades-infrastructure/.github/workflows/docs-trigger.yml
# Commit and push
cd camarades-infrastructure
git add .github/workflows/docs-trigger.yml
git commit -m "feat(docs): add cross-repo documentation rebuild trigger"
git push

Step 4: Configure GitHub App Permissions¶

The GitHub App must have access to all three repositories:

Go to GitHub App settings: https://github.com/organizations/{org}/settings/apps
Click on your GitHub App (e.g., "SyRF GitOps Automation")
Click Install App → Configure
Under Repository access, select:
✅ syrf
✅ cluster-gitops
✅ camarades-infrastructure
Click Save

Required Permissions:

Contents: Read and write (for all 3 repos)
Pull requests: Read and write (for syrf repo - tagging)

Step 5: Add Secrets to All Repositories¶

Each repository needs the GitHub App secrets:

For cluster-gitops:

# Go to: https://github.com/camaradesuk/cluster-gitops/settings/secrets/actions
# Add secrets:
#   APP_ID = <your-github-app-id>
#   APP_PRIVATE_KEY = <your-github-app-private-key>

For camarades-infrastructure:

# Go to: https://github.com/camaradesuk/camarades-infrastructure/settings/secrets/actions
# Add secrets:
#   APP_ID = <your-github-app-id>
#   APP_PRIVATE_KEY = <your-github-app-private-key>

For syrf (should already exist):

# Verify: https://github.com/camaradesuk/syrf/settings/secrets/actions
# Should have:
#   APP_ID
#   APP_PRIVATE_KEY

Testing the Setup¶

Test 1: Trigger from cluster-gitops¶

# On your local machine
cd /path/to/your/cluster-gitops

# Make a documentation change
echo "## Test Update" >> docs/README.md

# Commit and push
git add docs/README.md
git commit -m "docs: test cross-repo trigger"
git push

Expected behavior:

cluster-gitops/.github/workflows/docs-trigger.yml runs
Sends repository_dispatch to syrf
syrf/.github/workflows/docs-rebuild.yml runs
Builds new Docker image
Creates docs-v* tag
Publishes to GHCR

Check workflow:

cluster-gitops: https://github.com/camaradesuk/cluster-gitops/actions
syrf (triggered): https://github.com/camaradesuk/syrf/actions/workflows/docs-rebuild.yml

Test 2: Trigger from camarades-infrastructure¶

# On your local machine
cd <path-to-your-clone>/camarades-infrastructure

# Make a documentation change
echo "## Test Update" >> docs/README.md

# Commit and push
git add docs/README.md
git commit -m "docs: test cross-repo trigger"
git push

Expected behavior: Same as Test 1, but triggered by camarades-infrastructure

Test 3: Trigger from syrf (Direct Build)¶

# On your local machine
cd /path/to/syrf

# Make a documentation change
echo "## Test Update" >> docs/README.md

# Commit and push
git add docs/README.md
git commit -m "docs: test direct build"
git push

Expected behavior:

syrf/.github/workflows/ci-cd.yml detects docs change
Builds docs image as part of normal CI/CD
Creates docs-v* tag
Publishes to GHCR

Note: This uses ci-cd.yml, NOT docs-rebuild.yml

How It Works: Technical Details¶

Workflow Files¶

Repository	Workflow File	Trigger	Action
syrf	`ci-cd.yml`	Push to `main` with `docs/**` changes	Direct build
syrf	`docs-rebuild.yml`	`repository_dispatch` (docs-update)	Cross-repo build
cluster-gitops	`docs-trigger.yml`	Push to `main` with `docs/**` changes	Send dispatch to syrf
camarades-infrastructure	`docs-trigger.yml`	Push to `main` with `docs/**` changes	Send dispatch to syrf

Authentication Flow¶

cluster-gitops workflow
  ↓
Generates GitHub App token (scoped to syrf repo only)
  ↓
Uses peter-evans/repository-dispatch@v3
  ↓
Sends event to syrf repository
  ↓
syrf workflow receives event
  ↓
Generates GitHub App token (scoped to cluster-gitops + infrastructure)
  ↓
Checks out docs from all 3 repos
  ↓
Builds unified Docker image

Why GitHub App?

✅ Can trigger workflows in other repositories (GITHUB_TOKEN cannot)
✅ Repository-scoped permissions (only access needed repos)
✅ Organization-level identity (not tied to user account)

Build Context¶

The docs-rebuild.yml workflow checks out all repos in this structure:

/workspace/
├── syrf/                        (root checkout)
│   ├── docs/
│   └── docs/Dockerfile.ci       ← Dockerfile location
├── cluster-gitops/
│   └── docs/
└── camarades-infrastructure/
    └── docs/

The Dockerfile.ci uses MkDocs monorepo plugin to aggregate all three docs/ directories.

Troubleshooting¶

Trigger Workflow Runs But Rebuild Doesn't Start¶

Cause: repository_dispatch not being received by syrf

Check:

Verify workflow file exists: syrf/.github/workflows/docs-rebuild.yml
Check workflow is enabled (not disabled in GitHub UI)
Verify event type matches: docs-update in both trigger and listener

Debug:

# Check if syrf workflow ran
gh run list --workflow=docs-rebuild.yml --limit 10

Permission Denied When Checking Out cluster-gitops¶

Cause: GitHub App not installed on cluster-gitops or lacks permissions

Fix:

Go to GitHub App settings → Install App
Verify cluster-gitops is in the installation list
Check permissions: Contents (Read and write)

Workflow Shows "Resource not accessible by integration"¶

Cause: Using GITHUB_TOKEN instead of GitHub App token

Fix: Ensure docs-trigger.yml uses:

- name: Generate GitHub App Token
  id: app-token
  uses: actions/create-github-app-token@v1
  with:
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

- name: Trigger syrf docs rebuild
  uses: peter-evans/repository-dispatch@v3
  with:
    token: ${{ steps.app-token.outputs.token }}  # ← App token, not GITHUB_TOKEN

Docker Build Fails: "sparse-checkout: path not in sparse-checkout"¶

Cause: Trying to check out files not listed in sparse-checkout

Fix: Only check out docs/ directory (not mkdocs.yml from external repos):

sparse-checkout: |
  docs
# NOT: mkdocs.yml (doesn't exist in cluster-gitops/camarades-infrastructure)

Multiple Rebuilds Triggered at Once¶

Expected behavior: If you push to multiple repos' docs simultaneously, each will trigger a rebuild.

Impact: Multiple builds will run in parallel (GitHub Actions concurrency)

Optimization (optional): Add concurrency group to docs-rebuild.yml:

concurrency:
  group: docs-rebuild
  cancel-in-progress: true

This ensures only one docs build runs at a time, canceling older builds.

Monitoring and Maintenance¶

Regular Checks¶

Monthly:

✅ Verify all 3 workflows still exist and enabled
✅ Check GitHub App installation includes all 3 repos
✅ Rotate GitHub App private key (quarterly)

After Each Docs Change:

✅ Verify workflow triggered successfully
✅ Check docs.syrf.org.uk shows updated content
✅ Review GitHub Actions logs if issues

Workflow Run URLs¶

cluster-gitops triggers: https://github.com/camaradesuk/cluster-gitops/actions/workflows/docs-trigger.yml
camarades-infrastructure triggers: https://github.com/camaradesuk/camarades-infrastructure/actions/workflows/docs-trigger.yml
syrf rebuilds: https://github.com/camaradesuk/syrf/actions/workflows/docs-rebuild.yml
syrf direct builds: https://github.com/camaradesuk/syrf/actions/workflows/ci-cd.yml

Logs to Check¶

When debugging:

Source repo (cluster-gitops or camarades-infrastructure):
Verify docs-trigger.yml ran
Check for errors in "Trigger syrf docs rebuild" step
Target repo (syrf):
Verify docs-rebuild.yml started
Check "Log dispatch event" step shows correct source
Review Docker build logs

Migration from PAT to GitHub App¶

If you previously used DOCS_TRIGGER_TOKEN (PAT):

cluster-gitops/.github/workflows/docs-trigger.yml (old):

# OLD - Don't use
token: ${{ secrets.DOCS_TRIGGER_TOKEN }}

Updated (current):

# NEW - Use GitHub App
- name: Generate GitHub App Token
  id: app-token
  uses: actions/create-github-app-token@v1
  with:
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

- uses: peter-evans/repository-dispatch@v3
  with:
    token: ${{ steps.app-token.outputs.token }}

After migration:

Delete DOCS_TRIGGER_TOKEN secret from cluster-gitops and camarades-infrastructure
Revoke the PAT from GitHub settings

Setup GitOps GitHub App - GitHub App configuration
Multi-Repository Documentation Architecture - Design decisions
Unified Docs Structure - Documentation organization

Summary¶

This setup enables:

✅ Automatic docs rebuild when any of the 3 repos' docs change
✅ Unified documentation site aggregating all repos
✅ Secure cross-repo authentication via GitHub App
✅ Clear audit trail (which repo triggered rebuild)
✅ Deployed to https://docs.syrf.org.uk via ArgoCD

Workflow Files to Deploy:

✅ syrf/.github/workflows/docs-rebuild.yml (already exists)
⏳ cluster-gitops/.github/workflows/docs-trigger.yml (copy from template)
⏳ camarades-infrastructure/.github/workflows/docs-trigger.yml (copy from template)

Once all workflows are in place, documentation updates from any repository will automatically rebuild the unified docs site! 📚