Handbook Notifications¶

This guide explains how to set up automatic doc syncing from a package repo to this handbook. When docs change in your package, the handbook automatically fetches and republishes them.

How it works¶

sequenceDiagram
    participant P as Package repo
    participant W as workflows repo
    participant H as eng-handbook
    participant C as Cloudflare Pages

    P->>W: Push to docs/ triggers notify-handbook.yml
    W->>H: repository_dispatch (package-updated)
    H->>P: fetch-remote.yml clones docs/ via PAT
    H->>H: Commits docs/packages/<name>/
    H->>C: deploy.yml builds & deploys

Prerequisites¶

• Your package repo is under subscribed-aps
• Your package has a docs/ folder with an index.md entry point
• The HANDBOOK_DISPATCH_TOKEN organisation secret is available to your repo (it is by default for all subscribed-aps repos)

Setting up a new package¶

1. Add a docs entry point¶

Your docs/ folder must have an index.md. It can be as simple as:

# My Package

Brief description of what this package does.

- [Getting Started](getting-started.md)
- [API Reference](api-reference.md)

2. Add the notify workflow¶

Create .github/workflows/notify-handbook.yml in your package repo:

name: Notify Engineering Handbook

on:
  push:
    branches:
      - main  # or master — use your default branch
    paths:
      - "docs/**"

jobs:
  notify:
    uses: subscribed-aps/workflows/.github/workflows/notify-handbook.yml@main
    with:
      package: "my-package"        # Short name — becomes the folder name in handbook
      repo: "subscribed-aps/wp-pkg-my-package"
      branch: "main"
      docs_dir: "docs"
    secrets:
      HANDBOOK_DISPATCH_TOKEN: ${{ secrets.HANDBOOK_DISPATCH_TOKEN }}

3. Register the package in eng-handbook¶

Add a nav entry in eng-handbook/mkdocs.yml under the Packages section:

  - Packages:
      - packages/index.md
      - OTP: packages/otp/index.md
      - My Package: packages/my-package/index.md  # Add this line

4. Trigger the first sync manually¶

Go to eng-handbook → Actions → "Fetch Remote Package Docs" → Run workflow and fill in:

After this first manual sync, all subsequent updates happen automatically on push.

Setting up an existing package¶

Same steps as above — the only difference is that your package may already have a docs/ folder. Just verify it has an index.md and follow steps 2–4.

Troubleshooting¶

The notify workflow runs but nothing happens in eng-handbook

Check that the HANDBOOK_DISPATCH_TOKEN org secret has been granted to your repo under Organisation Settings → Secrets → HANDBOOK_DISPATCH_TOKEN → Repository access.

fetch-remote.yml fails with "Remote branch not found"

The branch input doesn't match the actual default branch. Check whether your repo uses main or master.

Docs appear but are incomplete

Make sure all linked .md files exist in docs/ — relative links in index.md that point to missing files will cause build warnings.