Configuration Reference

The central configuration file drives all enforcement, sync, and dispatch behavior. It lives at .github/config/repo-settings.json in docs-control and is fetched by downstream repositories at workflow runtime.

{
  "_comment": "Central repo-settings config — enforced by enforce-repo-settings.yml",
  "repository": {
    "private": false,
    "has_issues": true,
    "has_projects": false,
    "has_wiki": false,
    "is_template": false,
    "allow_squash_merge": true,
    "allow_merge_commit": true,
    "allow_rebase_merge": true,
    "allow_auto_merge": false,
    "delete_branch_on_merge": true,
    "web_commit_signoff_required": false,
    "squash_merge_commit_title": "COMMIT_OR_PR_TITLE",
    "squash_merge_commit_message": "COMMIT_MESSAGES",
    "merge_commit_title": "MERGE_MESSAGE",
    "merge_commit_message": "PR_TITLE",
    "allow_update_branch": true,
    "homepage": ""
  },
  "actions_permissions": {
    "default_workflow_permissions": "write",
    "can_approve_pull_request_reviews": true
  },
  "branch_protection": [
    {
      "branch": "main",
      "enforce_admins": true,
      "required_status_checks": {
        "strict": true,
        "contexts": [
          "Check linked issues",
          "lint / Lint Code Base",
          "lint / Shell Unit Tests"
        ],
        "self_contexts": ["Check linked issues", "Lint Code Base", "Shell Unit Tests"]
      },
      "required_pull_request_reviews": {
        "dismiss_stale_reviews": false,
        "require_code_owner_reviews": false,
        "required_approving_review_count": 0,
        "require_last_push_approval": false,
        "dismissal_restrictions": {
          "users": [],
          "teams": []
        },
        "bypass_pull_request_allowances": {
          "users": [],
          "teams": [],
          "apps": []
        }
      },
      "restrictions": null,
      "required_linear_history": false,
      "allow_force_pushes": false,
      "allow_deletions": false,
      "block_creations": false,
      "required_conversation_resolution": false,
      "lock_branch": false,
      "allow_fork_syncing": false
    }
  ],
  "topics": [],
  "pages": {
    "enabled": true,
    "build_type": "workflow"
  },
  "managed_files": {
    "source_repo": "f5-sales-demo/docs-control",
    "files": [
      {"src": "workflows/github-pages-deploy.yml", "dest": ".github/workflows/github-pages-deploy.yml"},
      {"src": "workflows/enforce-repo-settings.yml", "dest": ".github/workflows/enforce-repo-settings.yml"},
      {"src": "workflows/require-linked-issue.yml", "dest": ".github/workflows/require-linked-issue.yml"},
      {"src": "workflows/antigravity-review.yml", "dest": ".github/workflows/antigravity-review.yml"},
      {"src": "workflows/antigravity-translate.yml", "dest": ".github/workflows/antigravity-translate.yml"},
      {"src": ".github/PULL_REQUEST_TEMPLATE.md", "dest": ".github/PULL_REQUEST_TEMPLATE.md"},
      {"src": ".github/ISSUE_TEMPLATE/bug_report.md", "dest": ".github/ISSUE_TEMPLATE/bug_report.md"},
      {"src": ".github/ISSUE_TEMPLATE/feature_request.md", "dest": ".github/ISSUE_TEMPLATE/feature_request.md"},
      {"src": ".github/ISSUE_TEMPLATE/documentation.md", "dest": ".github/ISSUE_TEMPLATE/documentation.md"},
      {"src": ".github/ISSUE_TEMPLATE/config.yml", "dest": ".github/ISSUE_TEMPLATE/config.yml"},

      {"src": "CONTRIBUTING.md", "dest": "CONTRIBUTING.md"},
      {"src": "CLAUDE.md", "dest": "CLAUDE.md"},
      {"src": "AGENTS.md", "dest": "AGENTS.md"},
      {"src": ".agents/skills/demo-components/SKILL.md", "dest": ".agents/skills/demo-components/SKILL.md"},
      {"src": ".agents/skills/i18n-translate/SKILL.md", "dest": ".agents/skills/i18n-translate/SKILL.md"},
      {"src": ".editorconfig", "dest": ".editorconfig"},
      {"src": ".gitignore", "dest": ".gitignore"},
      {"src": "LICENSE", "dest": "LICENSE"},
      {"src": ".pre-commit-config.yaml", "dest": ".pre-commit-config.yaml"}
    ]
  }
}

Field reference

`repository`

Standard GitHub repository settings applied via PATCH /repos/{owner}/{repo}. Each key maps directly to the GitHub API field. The enforcement workflow compares each key against the repository’s current value and only patches keys that have drifted.

Notable settings:

delete_branch_on_merge: true — automatically cleans up merged PR branches
allow_update_branch: true — enables the “Update branch” button on PRs
homepage: "" — auto-computed at runtime as https://f5-sales-demo.github.io/{repo}/

`actions_permissions`

Controls GitHub Actions workflow permissions for the repository:

default_workflow_permissions: "write" — workflows get read/write access to the repository by default
can_approve_pull_request_reviews: true — allows workflows to approve PRs

Antigravity automation controls

The Configure Antigravity Controls workflow changes the organization variables that gate the Antigravity reviewer and translator. Each phase is safe to rerun:

disabled sets both variables to false with all visibility.
pilot sets both variables to true with selected visibility restricted to docs-control.
all sets both variables to true with all visibility only after it validates the selected pilot’s exact-head review receipt and 12-locale translation publication.

The workflow uses the existing governance personal access token, bounded GitHub API retries, and structured progress heartbeats. It does not require a GitHub App or GitHub Enterprise features.

`branch_protection`

An array of branch protection rules. Each entry specifies a branch name and the desired protection settings. Currently only main is protected.

Key fields:

enforce_admins: true — protection rules apply to repository administrators too
required_status_checks.strict: true — branches must be up-to-date before merging
required_status_checks.contexts — the check names downstream repositories must pass (for example, Check linked issues and lint / Shell Unit Tests)
required_status_checks.self_contexts — the check names docs-control itself must pass (for example, Check linked issues and Shell Unit Tests)
required_pull_request_reviews — requires all changes to enter through a pull request while required_approving_review_count: 0 keeps human approval optional; dismissal and bypass lists remain empty
restrictions: null — no push restrictions beyond branch protection

`contexts` vs `self_contexts`

Reusable workflow checks in downstream repositories use <caller_job_key> / <reusable_job_name>, while docs-control reports their bare job names. The linked-issue gate is an exception: its scheduled workflow publishes the commit status Check linked issues directly in every repository, so both contexts and self_contexts must use that exact name.

The self_contexts field stores the check names that apply to docs-control itself. During enforcement, the workflow detects whether it’s running on the source repository and swaps self_contexts into contexts before applying branch protection. The self_contexts field is always stripped before sending the payload to the GitHub API.

Shell Unit Tests is the uniform repository-test gate. The reusable workflow always reports it: consumer repositories run every tests/test-*.sh file, while a repository with no matching tests reports success with an explicit no-tests message. This makes repository shell tests required by default instead of relying on per-repository opt-in lists.

Consumer shell-test profiles

The default assumes every root-level tests/test-*.sh script is hermetic on an unprovisioned GitHub-hosted runner. A repository that also stores container or service integration tests under that glob needs a consumer_shell_tests.profiles entry in repo-settings.json.

Each profile classifies the complete matching inventory:

unit entries contain a test path and an args array. The runner passes each argument literally, without shell evaluation.
environment entries contain a test path and a non-empty reason explaining why the bare-runner unit gate cannot execute it.

The reusable workflow fetches the selector and configuration from the same docs-control main revision, logs that revision, and validates the inventory before running anything. Missing configuration, unsafe paths or arguments, duplicate paths, and unclassified or missing tests fail the required context. This makes a profile an audited classification contract rather than an ignore list. Repositories without a profile keep the broad default.

The xcsh override excludes both Super-Linter contexts because that repository does not call the reusable Super-Linter workflow; its native check, pii-guard, and test contexts remain required. Live verification must prove an exclusion is necessary before it is added.

Do not require a context from a workflow with paths or paths-ignore filters. GitHub leaves that context pending when the workflow does not start. Broad security tools must run in an unfiltered pull-request workflow or in a scheduled full-tree audit; the managed workflow-security audit uses the latter model for zizmor. A job-level condition is safe because a skipped job still reports a successful check.

`topics`

An array of GitHub topics to apply to the repository. Currently empty — topics are not enforced.

`pages`

GitHub Pages configuration:

enabled: true — ensures Pages is enabled on every enrolled repository
build_type: "workflow" — uses GitHub Actions for the Pages build (not legacy branch-based builds)

`managed_files`

Defines the file synchronization manifest:

source_repo — the repository that holds canonical versions of managed files (f5-sales-demo/docs-control)
files — an array of {src, dest} objects mapping source paths in docs-control to destination paths in downstream repositories

The file sync workflow iterates this array to detect and correct drift. Files not listed here (like dependabot.yml and README.md) are generated dynamically rather than synced from static sources.

Configuration Reference

Field reference

repository

actions_permissions

Antigravity automation controls

branch_protection

contexts vs self_contexts