GitLab CI: git push 403 错误解密, 为 CI/CD Job 佩戴正确的“身份徽章”

引言

大家好！在我们的自动化之旅中，没有什么比一个权限错误更能打击我们的热情了。当我们精心编写的 CI 脚本在执行 git push 时，被 GitLab 无情地以 403 Forbidden 拒绝，我们可能会感到困惑：这个 Job 不就是我触发的吗？它为什么没有我的权限？

这个问题触及了 CI/CD 安全模型的核心。GitLab CI 的 Job 确实会继承一个身份凭证，但出于安全考虑，这个默认凭证的权限被严格限制。它就像一张"实习生通行卡"，可以进入大楼、读取资料，但绝对无权修改公司的核心蓝图（代码仓库）。今天，我们就来学习如何为我们的 CI Job 升级成一张拥有"写入权限"的正式员工卡。

核心问题：CI Job 的默认身份 `CI_JOB_TOKEN`

当我们触发一个流水线时，GitLab 会为每个 Job 动态生成一个唯一的、短期的认证令牌，并将其放入预定义变量 $CI_JOB_TOKEN 中。这个令牌是 CI Job 与 GitLab API 和其他项目交互时的"身份证"。

CI_JOB_TOKEN 的默认权限被设计为"最小权限原则"：

可以：从本项目和其他我们授权的项目中 git clone 或 git pull 代码。
可以：读写本项目的包注册表（Package Registry）、容器注册表（Container Registry）。
可以：下载本流水线或其他流水线的产物（Artifacts）。
不可以 ：默认情况下，绝对不能 git push 代码到本项目或任何其他项目的代码仓库。

这是一个至关重要的安全特性！它防止了一个有漏洞的构建脚本（比如被恶意依赖注入攻击）擅自修改我们的源代码。

所以，我们的 Job 失败的根本原因，就是它使用的默认凭证（CI_JOB_TOKEN）没有 git push 的权限。

解决方案：创建并使用"项目访问令牌 (Project Access Token)"

这是目前业界公认的最干净、最安全、最推荐的解决方案。项目访问令牌就像是为我们的自动化任务创建的一个"机器人账户"，我们可以精确地授予它所需的权限。

操作步骤如下：

创建项目访问令牌
- 进入 GitLab 项目（在这里是 xlink/xlink-k8s-gitops）。
- 在左侧导航栏，进入 Settings -> Access Tokens。
- 点击 Add new token。
- Token name : 给它一个有意义的名字，比如 GITLAB_CI_PUSHER。
- Expiration date: 设置一个过期时间，增加安全性。
- Select a role : 选择 Developer 或 Maintainer 角色（Developer 角色通常就足够 git push 到非保护分支）。
- Select scopes : 这是最关键的一步！只勾选我们需要的最小权限 。对于这个场景，我们只需要勾选 write_repository。
- 点击 Create project access token。
安全地存储令牌
- 立即复制生成的令牌！ 这个令牌只会显示一次，离开页面后就再也找不到了。
- 回到我们的上游项目（触发这个 Job 的项目）。
- 进入 Settings -> CI/CD -> Variables。
- 点击 Add variable。
- Key : GITLAB_PUSHER_TOKEN (或者任何我们喜欢的名字)。
- Value: 粘贴我们刚刚复制的令牌。
- 重要：勾选 Protect variable (如果这个 Job 只在保护分支/标签上运行) 和 Mask variable (防止令牌在 Job 日志中被意外打印出来)。
- 点击 Add variable 保存。
在 CI 脚本中使用新令牌

现在，我们需要修改 git push 命令，让它使用我们新创建的令牌进行认证。方法是修改远程仓库的 URL，将令牌注入其中。

修正后的 deploy Job:

yaml 复制代码

deploy:
  stage: deploy
  extends: .unstable_branch_job
  script:
    - echo "Deploying to $TARGET_ENV with $APP_IMAGE for $APP_NAME"
    - |
      # 配置 Git 使用我们的新令牌
      # CI_SERVER_HOST 是预定义变量，例如 gitlab.example.com
      git remote set-url origin "https://gitlab-ci-token:${GITLAB_PUSHER_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
      
      # 下面的逻辑保持不变
      cd manifests/overlays/$TARGET_ENV/ && kustomize edit set image $APP_NAME=$APP_IMAGE
      git config --local user.name "GitLab Runner"
      git config --local user.email "runner@example.com"
      git commit -am "[auto ci] Update $APP_NAME image to $APP_IMAGE"
      git push origin "HEAD:$CI_COMMIT_REF_NAME"
  environment:
    name: $TARGET_ENV

代码解析：
git remote set-url origin "..." 这行命令是魔法发生的地方。它临时修改了 origin 这个远程仓库的地址，格式化成 https://<username>:<password>@<hostname>/<path>.git 的形式。

<username>: 我们使用 gitlab-ci-token，这是 GitLab 推荐的用于令牌认证的固定用户名。
<password>: 我们使用刚刚创建并存储在 CI/CD 变量中的 $GITLAB_PUSHER_TOKEN。

流程可视化：两种身份的对比

这个序列图清晰地展示了默认身份的失败和新身份的成功路径。

结论

总而言之，CI Job 不能直接继承触发者的 git push 权限 ，这是为了安全。正确的做法是为我们的自动化任务显式地创建一个具有最小必要权限的身份。

最佳实践总结：

使用 项目访问令牌 (Project Access Token) 作为 CI Job 的写入凭证。
遵循最小权限原则 ，只授予 write_repository 范围。
将令牌存储为受保护 (Protected) 和被遮盖 (Masked) 的 CI/CD 变量。
在 script 中，通过 git remote set-url 命令来使用该令牌进行认证。

通过这种方式，我们的 GitOps 自动化流程不仅能成功运行，而且变得安全、可控、可追溯。

GitLab CI: git push 403 错误解密, 为 CI/CD Job 佩戴正确的“身份徽章”

引言

核心问题：CI Job 的默认身份 CI_JOB_TOKEN

解决方案：创建并使用"项目访问令牌 (Project Access Token)"

流程可视化：两种身份的对比

结论

核心问题：CI Job 的默认身份 `CI_JOB_TOKEN`