GitLab Secrets Manager 正式可用后密钥怎样继承项目权限

GitLab Secrets Manager 在 GitLab 19.5 正式可用后，最容易被误解的一点是“组里创建的密钥，会不会自动给项目所有人读”。更准确的答案是：组级密钥可以沿着所属命名空间进入下级项目的可用范围，但真正的读值权限仍受项目成员身份、显式权限、分支和环境条件共同约束，不能把“继承可见范围”当成“自动拥有读权限”。

官方文档：https://docs.gitlab.com/ci/secrets/secrets_manager/

这项能力适用于 GitLab.com 和 GitLab Self-Managed 的 Premium、Ultimate 方案，底层由 OpenBao 提供存储能力。下面按“密钥来源—权限范围—作业读取—审计回收”的数据生命周期拆开说明。

正式可用后，先看清密钥的两种来源

项目级密钥只属于创建它的项目，适合部署凭据、测试证书等单项目数据；组级密钥则定义在组或子组，可以被该组下的项目或子组层级引用。GitLab 官方文档同时强调，组级密钥的来源必须是项目所属组或其父级组，来自无关组或 fork 所在组的密钥不能直接跨边界读取。

因此，所谓“继承项目权限”主要包含两层含义：第一，命名空间决定项目是否有资格看到这个密钥来源；第二，具体用户或角色的 Secrets Manager 权限决定谁能管理或读取密钥。GitLab 19.5 的文档还特别列出了项目与组的权限配置入口，项目 Owner 可以为用户或默认角色授予 read metadata、read value、create、update、delete 等权限。

组级密钥怎样进入项目权限边界

可以把判断过程写成一条固定链路：先确认项目属于哪个组层级，再确认密钥是在项目还是上级组定义，接着检查管理者是否给用户或默认角色授予了所需权限，最后再看 CI/CD 作业声明的分支和环境是否匹配。

特别要注意，组级定义解决的是复用和治理问题，不是权限绕过手段。把数据库密码放到顶级组，只代表多个下级项目可以在同一命名空间内引用；生产项目仍应通过受保护分支、生产环境和最小读权限缩小读取面。

CI/CD 作业必须显式声明，满足范围才会读取

Secrets Manager 不像传统 CI/CD 变量那样默认对作业开放。作业需要在 .gitlab-ci.yml 中使用 secrets 与 gitlab_secrets_manager 声明需要的密钥；组级密钥还要写明 source，并使用项目所属组或父级组的完整路径。

deploy_production:
  secrets:
    DEPLOY_TOKEN:
      gitlab_secrets_manager:
        # 组级密钥的来源必须是当前项目所属组或父级组
        name: deploy_token
        source: group/platform/production
      # 默认以临时文件路径形式注入，减少明文进入环境变量
      file: true
  rules:
    # 只允许生产分支触发这个读取密钥的作业
    - if: '$CI_COMMIT_BRANCH == "main"'
  environment:
    # 密钥的环境范围需要与作业目标保持一致
    name: production
  script:
    # 让工具从临时文件读取凭据，避免把内容直接写进命令参数
    - deploy-cli --token-file "$DEPLOY_TOKEN"

这里的关键不是 YAML 写得多复杂，而是把边界放在作业声明处：分支、环境以及受保护分支规则共同决定此次作业是否匹配。默认情况下，密钥值以临时文件路径暴露给作业，作业结束后不应继续依赖这个文件；只有确实需要环境变量形态时，才使用 file: false，并同步评估日志、子进程和崩溃转储的暴露面。

正式落地时，权限继承要和回收动作一起设计

正式可用的价值不只是把密钥集中存储，而是把权限和代码组织放到同一条治理链上。建议先把跨项目复用、但读取范围明确的凭据放到组级；把只服务于单一项目的证书留在项目级；然后为生产密钥绑定受保护分支和明确环境，不要只依赖“项目在某个组里”这一条条件。

当成员、机器人账号或服务账号离开项目时，项目成员关系变化应成为回收入口。官方说明会记录密钥的创建、读取、更新和删除事件，而且每次 CI/CD 读取都关联流水线和作业标识；这让排查“哪个作业拿过这个密钥”比在多个外部系统之间拼日志更直接。

迁移旧 CI/CD 变量时，不要一次把所有变量搬到顶级组。先按项目、环境和分支建立小批量清单，迁移一个密钥就同步改作业声明，再观察审计事件和失败作业。GitLab 官方还提示，CI/CD 变量迁移工作流仍在开发中，因此当前更适合采用可回滚的分阶段迁移。

几个容易混淆的问题

组级密钥是不是所有子项目都能直接读？

不是。项目必须处于该组或父级组的命名空间范围，作业还要显式声明密钥并满足分支、环境等条件；用户或角色权限不足时，仍然不能读取值。

把密钥放进组里，能不能替代受保护分支？

不能。组级来源解决复用和集中治理，受保护分支与环境条件解决“哪类作业可以读”。生产凭据通常需要两者同时配置。

项目转移后，组级密钥会跟着一起走吗？

不要默认会。官方文档说明，项目或组转移时原有 Secrets Manager 会被禁用，相关密钥不会转移到新命名空间并可能被永久删除；迁移前必须按文档安排重建和轮换。

小结

GitLab Secrets Manager 正式可用后，密钥“继承项目权限”的正确理解是：命名空间决定密钥能否进入项目的可用范围，成员和角色权限决定谁能管理或读值，作业的分支与环境声明决定一次运行能否读取，审计事件则负责追溯和回收。把这四层分开配置，才能在复用密钥的同时避免把生产凭据扩散给所有流水线。