3、代码仓库管理：GitLab/GitHub 的权限、分支保护与 Webhook 配置

好，咱们进入第三课。代码仓库管理，说白了就是管好你的代码、管好你的人、管好你的自动化流程。

我见过太多团队，代码仓库乱成一锅粥。有人直接往 master 推代码，有人把密钥硬编码在仓库里，还有人手动触发构建... 嗯，这些坑我都踩过。今天咱们就把 GitLab 和 GitHub 上最核心的三件事讲透：权限怎么设、分支怎么保护、Webhook 怎么配。

3.1 权限模型：谁可以做什么

先说说权限。你想想看，一个几十人的开发团队，如果每个人都能删分支、改设置，那不乱套了？

我个人习惯，权限管理遵循「最小权限原则」—— 只给每个人完成工作所需的最小权限。

GitLab 权限层级

GitLab 的权限分五个级别，从低到高：

权限级别 角色 典型操作
Guest 访客 查看 issue、查看 wiki
Reporter 报告者 查看代码、下载项目、创建 issue
Developer 开发者 推送代码、创建分支、创建 MR
Maintainer 维护者 合并 MR、管理 CI/CD、管理仓库设置
Owner 所有者 删除项目、转移项目、管理所有设置

我在项目中遇到过，有人把整个团队都设成 Maintainer，结果新人误操作删了 CI 配置。所以我的建议是：开发者给 Developer 就够了，Maintainer 只给核心成员。

GitHub 权限层级

GitHub 的权限模型类似，但叫法不同：

权限级别 角色 典型操作
Read 读取者 查看代码、查看 issue
Triage 分类者 管理 issue、管理 PR 标签
Write 写入者 推送代码、创建分支、创建 PR
Maintain 维护者 合并 PR、管理仓库设置（不含敏感操作）
Admin 管理员 完全控制，包括删除仓库
我的小技巧： 在 GitHub 上，我习惯把自动化机器人（比如 Dependabot）的权限设为 Write，这样它能自动创建 PR，但不会合并。安全又高效。

3.2 分支保护：守住你的主分支

分支保护，说白了就是给主分支加把锁。我曾经见过一个团队，master 分支没有任何保护，结果有人直接 push 了一个未编译通过的代码，整个 CI 全红了... 那叫一个惨。

GitLab 分支保护配置

在 GitLab 中，进入 Settings → Repository → Protected Branches。我通常这样配：

  • 允许合并的角色： Maintainer + Developer（但建议只给 Maintainer）
  • 允许推送的角色： 没人（所有变更必须通过 MR）
  • 代码所有者审批： 开启，要求特定文件（如 CI 配置）必须由指定人审批

举个例子，假设你要保护 main 分支：

# 通过 GitLab API 设置分支保护
curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --data "name=main&push_access_level=0&merge_access_level=40" \
  "https://gitlab.example.com/api/v4/projects/<project_id>/protected_branches"

这里 push_access_level=0 表示不允许任何人直接推送，merge_access_level=40 表示只有 Maintainer（权限值 40）可以合并。

GitHub 分支保护规则

GitHub 的配置在 Settings → Branches → Add rule。我常用的规则：

  • Require pull request reviews before merging： 至少 1 个审批
  • Dismiss stale pull request approvals： 当有新提交时，自动清除旧审批
  • Require status checks to pass before merging： 必须通过 CI 检查
  • Include administrators： 管理员也要遵守这些规则（这个很重要！）
注意： 我曾经犯过一个错误 —— 没勾选「Include administrators」。结果管理员可以直接绕过保护规则推送代码。后来我强制要求所有成员，包括我自己，都必须走 PR 流程。规矩就是规矩，没人能例外。

3.3 Webhook 配置：让仓库主动通知

Webhook 是什么？说白了就是一个「回调」。当仓库里发生某些事件（比如 push、PR、issue）时，GitLab/GitHub 会自动向你的服务器发送一个 HTTP POST 请求。

我习惯用 Webhook 做两件事：

  1. 触发 CI/CD 流水线： 代码一推送，自动开始构建
  2. 通知协作工具： 比如发消息到钉钉、Slack 或飞书

GitLab Webhook 配置

路径：Settings → Webhooks。关键字段：

  • URL： 接收 Webhook 的服务器地址（比如 Jenkins 的 Generic Webhook Trigger）
  • Secret Token： 一个自定义密钥，用于验证请求来源（强烈建议设置！）
  • Trigger： 选择触发事件，我通常勾选「Push events」和「Merge request events」

举个例子，配置 Jenkins 的 Webhook：

# Jenkins 的 Generic Webhook Trigger 插件配置
URL: http://jenkins.example.com/generic-webhook-trigger/invoke
Token: my-secret-token-123

# GitLab 端配置
URL: http://jenkins.example.com/generic-webhook-trigger/invoke
Secret Token: my-secret-token-123
Trigger: Push events, Merge request events

这里要注意，URL 和 Token 必须完全匹配。我见过有人把 Token 写错了，结果 Webhook 一直触发失败，排查了半天才发现是大小写问题。

GitHub Webhook 配置

路径：Settings → Webhooks → Add webhook。配置项类似：

  • Payload URL： 接收地址
  • Content type： 建议用 application/json
  • Secret： 同样建议设置
  • Which events： 我通常选「Just the push event」或「Send me everything」
避坑指南： 我曾经配置了一个 Webhook，结果每次 push 都触发两次构建。后来发现是因为 GitLab 和 GitHub 的 Webhook 默认会发送「ping」事件。解决办法是在接收端过滤掉 X-GitHub-Event: ping 或 X-Gitlab-Event: Push Hook 之外的请求。

3.4 实战：一个完整的权限+保护+Webhook 配置示例

好，咱们来一个完整的例子。假设你有一个 Java 项目，团队有 5 个人，你希望：

  1. 只有你（管理员）能合并到 main 分支
  2. 所有合并必须通过 CI 检查
  3. 代码推送后自动触发 Jenkins 构建

第一步：设置权限

在 GitLab 中，把 4 个开发人员设为 Developer，你自己设为 Maintainer。

第二步：保护 main 分支

# 通过 GitLab UI 设置
Settings → Repository → Protected Branches
Branch: main
Allowed to merge: Maintainers
Allowed to push: No one
Code owner approval: Required

第三步：配置 Webhook

Settings → Webhooks
URL: http://jenkins.example.com/generic-webhook-trigger/invoke
Secret Token: my-jenkins-token
Trigger: Push events, Merge request events
SSL verification: Enable (如果 Jenkins 有 HTTPS)

第四步：在 Jenkins 中配置

# Jenkins Pipeline 示例
pipeline {
    agent any
    triggers {
        GenericTrigger(
            genericVariables: [
                [key: 'BRANCH', value: '$.ref']
            ],
            token: 'my-jenkins-token',
            causeString: 'Triggered by GitLab Webhook'
        )
    }
    stages {
        stage('Build') {
            steps {
                echo "Building branch: ${BRANCH}"
                sh 'mvn clean package'
            }
        }
    }
}
我的经验： 配置完成后，一定要先测试一下。GitLab 和 GitHub 都提供了「Test」按钮，可以手动触发一次 Webhook。我每次配完都会先发一个测试请求，确认 Jenkins 能正常收到并开始构建。

3.5 常见问题与排查

最后，分享几个我踩过的坑：

  • Webhook 没触发？ 先检查网络连通性。我遇到过公司内网防火墙把 Webhook 请求拦截了的情况。
  • 权限设置不生效？ 检查一下是不是有「继承权限」。GitLab 的 Group 权限会覆盖 Project 权限。
  • 分支保护规则冲突？ 如果你同时设置了多个规则，GitHub 会取「最严格」的那个。GitLab 则是按顺序匹配。

嗯，今天就讲到这里。代码仓库管理看似简单，但细节很多。你想想看，一个配置不当的 Webhook 可能导致构建失败，一个权限漏洞可能导致代码泄露。所以，花点时间把基础打牢，绝对值得。

下一章，咱们聊聊 CI/CD 流水线的核心 —— 构建与测试。到时候见。

← 上一章 📖 返回目录 下一章 →