配置参考

中央配置文件驱动所有强制执行、同步和调度行为。它位于 docs-control 中的 .github/config/repo-settings.json，并在工作流运行时由下游仓库获取。

{
  "_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"}
    ]
  }
}

字段参考

`repository`

通过 PATCH /repos/{owner}/{repo} 应用的标准 GitHub 仓库设置。每个键直接映射到 GitHub API 字段。强制执行工作流会将每个键与仓库的当前值进行比较，并仅对已漂移的键进行补丁。

值得注意的设置：

delete_branch_on_merge: true — 自动清理已合并的 PR 分支
allow_update_branch: true — 启用 PR 上的“Update branch”按钮
homepage: "" — 在运行时自动计算为 https://f5-sales-demo.github.io/{repo}/

`actions_permissions`

控制仓库的 GitHub Actions 工作流权限：

default_workflow_permissions: "write" — 工作流默认获得对仓库的读/写权限
can_approve_pull_request_reviews: true — 允许工作流批准 PR

Antigravity 自动化控制

Configure Antigravity Controls 工作流可更改控制 Antigravity 审查员和翻译员的组织变量。每个阶段都可以安全地重新运行：

disabled 将两个变量均设置为 false，并具有 all 可见性。
pilot 将两个变量均设置为 true，并将 selected 可见性限制为 docs-control。
all 仅在验证了所选试点精确 HEAD 的审查收据和 12 个语言区域的翻译发布之后，才将两个变量均设置为 true 并具有 all 可见性。

该工作流使用现有的治理个人访问令牌、受限的 GitHub API 重试和结构化的进度心跳。它不需要 GitHub App 或 GitHub Enterprise 功能。

`branch_protection`

分支保护规则数组。每个条目指定一个 branch 名称和所需的保护设置。目前仅保护 main。

关键字段：

enforce_admins: true — 保护规则也适用于仓库管理员
required_status_checks.strict: true — 合并前分支必须是最新的
required_status_checks.contexts — 下游仓库必须通过的检查名称（例如 Check linked issues 和 lint / Shell Unit Tests）
required_status_checks.self_contexts — docs-control 本身必须通过的检查名称（例如 Check linked issues 和 Shell Unit Tests）
required_pull_request_reviews — 要求所有更改都必须通过 Pull Request 提交，同时 required_approving_review_count: 0 保持人工批准为可选；驳回和绕过列表保持为空
restrictions: null — 除分支保护外没有推送限制

`contexts` 与 `self_contexts`

下游仓库中的可重用工作流检查使用 <caller_job_key> / <reusable_job_name>，而 docs-control 报告其原始作业名称。关联 issue 关卡是一个例外：其定时工作流直接在每个仓库中发布提交状态 Check linked issues，因此 contexts 和 self_contexts 都必须使用该精确名称。

self_contexts 字段存储适用于 docs-control 本身的检查名称。在强制执行期间，工作流会检测它是否在源仓库上运行，并在应用分支保护之前将 self_contexts 替换到 contexts 中。在将有效载荷发送到 GitHub API 之前，始终会删除 self_contexts 字段。

Shell Unit Tests 是统一的仓库测试关卡。可重用工作流始终会报告它：消费仓库会运行每个 tests/test-*.sh 文件，而没有匹配测试的仓库则会报告成功并附带明确的无测试消息。这使得仓库 Shell 测试默认成为必需项，而不是依赖于每个仓库的选择性加入列表。

消费者 Shell 测试配置

默认设置假设每个根目录级别的 tests/test-*.sh 脚本在未经配置的 GitHub 托管运行器上都是密封（hermetic）的。在该匹配模式下同时存储容器或服务集成测试的仓库需要在 repo-settings.json 中添加 consumer_shell_tests.profiles 条目。

每个配置对完整的匹配清单进行分类：

unit 条目包含测试 path 和 args 数组。运行器字面传递每个参数，不进行 Shell 评估。
environment 条目包含测试 path 和非空的 reason，解释为什么纯运行器单元关卡无法执行它。

可重用工作流从相同的 docs-control main 版本获取选择器和配置，记录该版本，并在运行任何内容之前验证清单。缺少配置、不安全的路径或参数、重复的路径以及未分类或缺失的测试将导致必需的上下文失败。这使配置成为经审计的分类契约，而不是忽略列表。没有配置的仓库保持广泛的默认设置。

xcsh 覆盖排除了两个 Super-Linter 上下文，因为该仓库不调用可重用的 Super-Linter 工作流；其原生的 check、pii-guard 和 test 上下文仍然是必需的。在添加排除项之前，实时验证必须证明排除是必要的。

不要要求具有 paths 或 paths-ignore 过滤器的工作流中的上下文。当工作流未启动时，GitHub 会保持该上下文处于挂起状态。广泛的安全工具必须在未过滤的拉取请求工作流或定时的全树审计中运行；托管的工作流安全审计对 zizmor 使用后一种模式。作业级别的条件是安全的，因为被跳过的作业仍会报告成功的检查。

`topics`

要应用到仓库的 GitHub 主题数组。目前为空 — 不强制执行主题。

`pages`

GitHub Pages 配置：

enabled: true — 确保在每个注册的仓库上都启用了 Pages
build_type: "workflow" — 使用 GitHub Actions 进行 Pages 构建（而不是传统的基于分支的构建）

`managed_files`

定义文件同步清单：

source_repo — 保存托管文件规范版本的仓库 (f5-sales-demo/docs-control)
files — {src, dest} 对象的数组，将 docs-control 中的源路径映射到下游仓库中的目标路径

文件同步工作流会迭代此数组以检测并纠正漂移。此处未列出的文件（如 dependabot.yml 和 README.md）是动态生成的，而不是从静态源同步的。

配置参考

字段参考

repository

actions_permissions

Antigravity 自动化控制

branch_protection

contexts 与 self_contexts