Contributing

CI/CD Setup for Source Repos

How to configure automatic documentation rebuilds when source repositories change.

Overview

The documentation portal aggregates content from multiple GitHub repositories. When documentation changes in a source repository, the portal needs to rebuild to reflect those changes.

This is achieved through webhooks: source repositories trigger an AWS Amplify rebuild via a GitHub Action.

┌─────────────────────────────────────────────────────────────────┐
│                     docs.dev (this repo)                        │
│                     Amplify watches: master                     │
└─────────────────────────────────────────────────────────────────┘
        ▲                    ▲                    ▲
        │                    │                    │
   Webhook POST         Webhook POST         Webhook POST
        │                    │                    │
┌───────┴───────┐  ┌─────────┴────────┐  ┌───────┴───────┐
│ engineering-  │  │     schemas      │  │  audit-utils  │
│   handbook    │  │   doc/**/*.md    │  │  doc/**/*.md  │
└───────────────┘  └──────────────────┘  └───────────────┘

Two Types of Rebuilds

TriggerWhat Happens
Commit to docs.dev masterAmplify auto-rebuilds (watching this repo)
Commit to source repoSource repo workflow POSTs to webhook → Amplify rebuilds

Setup Instructions

Step 1: Get the Webhook URL

  1. Go to the AWS Amplify Console
  2. Select the docs.dev application
  3. Navigate to App Settings → Build settings → Webhooks
  4. Click Create webhook
  5. Copy the generated webhook URL
Keep this URL secure. Anyone with the URL can trigger builds.

Step 2: Add the Secret to Your Source Repository

  1. Go to your source repository on GitHub (e.g., ontopix/engineering-handbook)
  2. Navigate to Settings → Secrets and variables → Actions
  3. Click New repository secret
  4. Name: DOCSDEV_AMPLIFY_WEBHOOK_URL
  5. Value: Paste the webhook URL from Step 1
  6. Click Add secret

Step 3: Create the GitHub Action Workflow

Create a workflow file in your source repository:

# .github/workflows/trigger-docs-rebuild.yml
name: Trigger Docs Rebuild

on:
  push:
    branches:
      - main
      - master
    paths:
      - 'doc/**/*.md'  # Adjust this to match your docs location

jobs:
  trigger-rebuild:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Amplify rebuild
        run: |
          curl -X POST "${{ secrets.DOCSDEV_AMPLIFY_WEBHOOK_URL }}" \
            -H "Content-Type: application/json" \
            --fail --silent --show-error

Step 4: Configure the Path Filter

Adjust the paths filter to match where documentation lives in your repository:

RepositoryDocumentation Pathpaths Filter
engineering-handbookRoot directory'**/*.md'
schemasdoc/ directory'doc/**/*.md'
audit-utilsdoc/ directory'doc/**/*.md'
stylebookpackages/content/'packages/content/**/*.md'

Complete Workflow Examples

For repositories with docs at root level

# .github/workflows/trigger-docs-rebuild.yml
name: Trigger Docs Rebuild

on:
  push:
    branches: [main, master]
    paths:
      - '**/*.md'
      - '!README.md'  # Optionally exclude README

jobs:
  trigger-rebuild:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Amplify rebuild
        run: |
          curl -X POST "${{ secrets.DOCSDEV_AMPLIFY_WEBHOOK_URL }}" \
            -H "Content-Type: application/json" \
            --fail --silent --show-error

For repositories with docs in a subdirectory

# .github/workflows/trigger-docs-rebuild.yml
name: Trigger Docs Rebuild

on:
  push:
    branches: [main, master]
    paths:
      - 'doc/**/*.md'

jobs:
  trigger-rebuild:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Amplify rebuild
        run: |
          curl -X POST "${{ secrets.DOCSDEV_AMPLIFY_WEBHOOK_URL }}" \
            -H "Content-Type: application/json" \
            --fail --silent --show-error

With scheduled weekly rebuild

# .github/workflows/trigger-docs-rebuild.yml
name: Trigger Docs Rebuild

on:
  push:
    branches: [main, master]
    paths:
      - 'doc/**/*.md'
  schedule:
    # Every Sunday at midnight UTC
    - cron: '0 0 * * 0'

jobs:
  trigger-rebuild:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Amplify rebuild
        run: |
          curl -X POST "${{ secrets.DOCSDEV_AMPLIFY_WEBHOOK_URL }}" \
            -H "Content-Type: application/json" \
            --fail --silent --show-error

Verifying the Setup

After setting up the workflow:

  1. Make a small change to a documentation file in your source repo
  2. Commit and push to the main branch
  3. Check the Actions tab in your repository — you should see the workflow running
  4. Check the Amplify Console — a new build should be triggered
  5. After the build completes, verify your changes appear on docs.ontopix.dev

Troubleshooting

Workflow runs but Amplify doesn't rebuild

  • Verify the DOCSDEV_AMPLIFY_WEBHOOK_URL secret is correctly set
  • Check that the webhook URL is valid and hasn't been rotated
  • Look at the workflow logs for any curl errors

Changes don't appear after rebuild

  • Ensure the include pattern in content.config.ts matches your file paths
  • Verify the GITHUB_TOKEN has read access to your repository
  • Check Amplify build logs for content fetching errors

Workflow doesn't trigger on push

  • Verify the paths filter matches your actual file locations
  • Ensure you're pushing to the correct branch (main or master)
  • Check that the workflow file is valid YAML

Security Considerations

  • The webhook URL is a secret — don't commit it to repositories
  • Use GitHub repository secrets, not workflow-level secrets
  • Consider restricting who can modify the workflow file
  • The webhook only triggers builds; it cannot access your code or secrets

Local Editing Workflow

How to preview and edit documentation locally with hot module reload before publishing.

Writing Markdown

Markdown syntax and MDC components available in this portal.