如何在GitHub中以代码形式配置分支保护规则及其他设置？

云原生阿岚

2026-8-26

代码化管理GitHub分支保护及平台设置的可行方案

完全可以通过代码方式实现分支保护规则配置、全量GitHub设置项的管理，目前成熟可落地的方案主要有以下几类，你可以根据自己的使用场景选择：

Terraform GitHub Provider（推荐大规模/组织级使用）
这是GitHub官方维护的基础设施即代码（IaC）集成，覆盖了从仓库级分支保护、PR规则、Actions密钥、Webhook，到组织级成员权限、团队配置、安全策略等几乎所有GitHub后台可配置的能力。你只需要用HCL语法声明你要的目标状态，执行部署命令后工具会自动调用GitHub接口完成配置同步，所有配置可以存入Git做版本管理、变更审计。
以下是一个基础的main分支保护配置示例：
```
resource "github_branch_protection" "main_protection" {
  repository_id  = github_repo.target_repo.repo_id
  pattern        = "main"
  enforce_admins = true # 对仓库管理员同样生效保护规则
  required_pull_request_reviews {
    required_approving_review_count = 2 # 合并前需要2个审批
    dismiss_stale_reviews           = true # 新提交自动驳回旧审批
  }
  required_status_checks {
    strict   = true # 代码落后目标分支时必须先更新
    contexts = ["ci/unit-test", "ci/lint-check"] # 必须通过的CI检查项
  }
}
```
写好配置后执行terraform init、terraform apply即可完成规则下发。

GitHub 原生API（适合自定义集成场景）
GitHub开放了全量REST与GraphQL接口，所有网页端能操作的设置都有对应的API端点，你可以用任意熟悉的编程语言（Shell/Python/Go等）调用接口完成配置。比如用curl快速配置分支保护的示例：

curl -X PUT \
  -H "Authorization: token <你的有仓库管理权限的GitHub Token>" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/<仓库所属组织/用户名>/<仓库名>/branches/main/protection \
  -d '{
    "required_status_checks": {"strict": true, "contexts": ["ci/unit-test"]},
    "enforce_admins": true,
    "required_pull_request_reviews": {"required_approving_review_count": 1},
    "restrictions": null
  }'

这类方案灵活度最高，你可以根据自己的内部流程定制配置管理逻辑。

GitHub CLI（适合轻量脚本/批量操作场景）
GitHub官方推出的命令行工具gh封装了大部分常用配置操作，不需要手动拼接API请求，写简单的Shell脚本就能批量完成多仓库的分支保护、设置调整操作，比如读取本地JSON配置文件下发分支保护规则的命令：
```
gh api -X PUT repos/:owner/:repo/branches/main/protection --input ./branch-protection-rules.json
```
仓库内声明式配置同步工具（适合单仓库/小团队轻量使用）
有不少轻量工具支持直接在仓库的.github目录下存放YAML格式的配置文件，定义好分支保护、Issue标签、协作者权限等规则后，工具会自动监听变更、同步配置到GitHub侧，配置和业务代码存在同一个仓库里，维护门槛很低。

注意：所有上述方案都需要提前准备有对应操作权限的鉴权凭证，可以用Personal Access Token，也可以用GitHub App的身份凭证做更细粒度的权限控制，配置生效逻辑和网页端手动操作完全一致。

内容的提问来源于stack exchange，提问作者zara