Onboarding

This page covers the procedure to enroll a new repository in the docs-control governance system and configure documentation pipelines and Antigravity AI automation.

Prerequisites

• Org membership in f5-sales-demo
• REPO_SETTINGS_TOKEN and REPO_SYNC_TOKEN secrets configured as organization-level secrets (or added to the new repository individually). REPO_SETTINGS_TOKEN must be authorized for every enrolled repository and retain Administration R/W, Pages R/W, Contents Read, Metadata Read, and repository Secrets: write permission (or use an equivalent classic repo-scoped credential).
• ANTIGRAVITY_TOKEN and GCP_PROJECT_ID secrets configured for automated Antigravity AI code review and language translation
• Access to the ghcr.io/f5-sales-demo/docs-builder container image

Enrollment steps

1. Add to downstream-repos.json

Add the repository’s bare name — not owner/repo — to .github/config/downstream-repos.json in docs-control. The owner is prepended at dispatch time from GITHUB_REPOSITORY_OWNER. This registers it for dispatch and enforcement.

Then assign it a class in repo_classes.repos in .claude/governance.json. This is required: shell unit tests fail if a repository is registered for dispatch without a class assignment.

2. Optionally add to docs-sites.json

If the repository will publish documentation, add an entry to .github/config/docs-sites.json with:

• label — human-readable site name
• url — URL to the site’s llms-full.txt endpoint
• description — short description used in the generated README

If no entry is added, the README generator falls back to a capitalized repository name and the GitHub API description.

3. Consolidate .gitignore

The enforcement workflow overwrites the downstream .gitignore entirely. Before onboarding, merge any repository-specific entries into the template .gitignore in docs-control so they are not lost.

4. Install caller workflows

Copy the caller workflow templates from workflows/ in docs-control into the new repository’s .github/workflows/ directory:

• enforce-repo-settings.yml — triggers enforcement and file sync
• github-pages-deploy.yml — triggers docs build and deploy
• require-linked-issue.yml — enforces PR-to-issue linking
• antigravity-review.yml — triggers Antigravity AI PR code review
• antigravity-translate.yml — triggers Antigravity AI language translation
• super-linter.yml — runs the super-linter suite on PRs

Dependency automation requires no repository-local caller: the organization-owned Renovate App selects governed repositories centrally.

These files are also synced automatically by the file sync workflow, but installing them manually bootstraps the process.

Pages caller content receipt

Every Pages caller must pass its own exact commit to the reusable deployment workflow:

with:
  content-ref: ${{ github.sha }}

content-ref must be a full 40-character commit SHA. The reusable workflow checks that checkout resolves to that SHA, then proves it is the current protected main commit before it builds or publishes. It records the requested content SHA, checked-out commit, and resolved builder image in the published revision marker, so the deployed artifact has a deterministic identity.

There is no mutable fallback: callers cannot omit content-ref, use a branch name, or publish an older or unmerged commit. In docs-control, docs-site-deploy.yml is the direct push/manual caller; github-pages-deploy.yml is reusable-only.

5. Trigger enforcement

Run the enforcement workflow manually in the new repository:

source_sha=$(gh api repos/f5-sales-demo/docs-control/commits/main --jq '.sha')
gh workflow run enforce-repo-settings.yml \
  --repo f5-sales-demo/<repo-name> \
  -f source_sha="$source_sha"

This applies all repository settings, creates any missing governance files, and opens a sync PR if needed.

6. Verify settings

Confirm that enforcement succeeded:

gh run list --repo f5-sales-demo/<repo-name> --workflow enforce-repo-settings.yml --limit 1

Check that branch protection, Actions permissions, and Pages are configured correctly:

gh api repos/f5-sales-demo/<repo-name>/branches/main/protection \
  --jq '.required_status_checks.contexts'

7. Verify docs site

If the repository has a docs/ directory, confirm the docs site is accessible after the first successful deploy:

curl -sf "https://f5-sales-demo.github.io/<repo-name>/" \
  && echo "OK" || echo "FAIL"

Fork-fidelity: opting out of managed files

Most governed repositories take every managed file as-is, but active forks can opt out of sync on specific paths using skip_files in repo-settings.json under managed_files and .claude/governance.json.