Bitbucket 密钥管理：完整指南

Bitbucket Secrets 管理：完整指南

在软件系统中，secrets 是指只能由授权人员访问的敏感信息。Token、登录凭据、SSH key 和 API key 都属于 secrets。开发者在协作时，通常会使用代码仓库平台。虽然很多人选择 GitHub，但另一个流行的替代方案是 Bitbucket。

Bitbucket 原生支持 secrets management，并且还提供更高级的能力，例如用于无 key 身份验证的 OpenID Connect（OIDC）以及原生的第三方 secret provider 集成。请注意，本指南聚焦于 Bitbucket Cloud。如果你的团队使用的是 Bitbucket Data Center（自托管版本），那么 secrets 管理流程可能会因服务器配置而有所不同。

在 Bitbucket 中，secrets 可以在三个不同层级进行管理：

• Repository-level，用于特定于单个 repository 的 secrets
• Workspace-level，用于跨多个 repository 共享的 secrets
• Environment/Deployment-level，用于为 production 或 staging 等特定环境配置的 secrets

虽然 Bitbucket 为在 CI/CD pipeline 中存储和使用 secrets 提供了良好的基础，但对于有更高级需求的团队来说，集成专门的 secrets management platform（如 Infisical）通常会更有帮助。这些平台可以直接与 Bitbucket 集成，更方便地在各类服务之间统一管理 secrets，并提供 secret rotation、版本管理、审计日志以及跨平台访问等功能。

对于小型项目，Bitbucket 的原生选项可能已经足够。随着基础设施不断扩展、访问控制变得越来越难管理，内置工具与专用平台之间的差异也会变得越来越难以忽视。

添加 Secrets

在深入了解如何在 Bitbucket 中管理 secrets 之前，有一些背景事项值得注意：

• 要添加 secrets，你需要 repository 的管理员权限（用于 repository variables）或 workspace 的管理员权限（用于 workspace variables）。
• 如果你将某个变量标记为 secured，Bitbucket 会将其存储为加密变量。一旦保存，该值就会被隐藏，并且无法再在 UI 中查看。你只能通过输入新值来更新它，或者将其删除。
• 对于 repository variables，必须启用 Pipelines（位于 Repository Settings → Pipelines → Settings）。
• 你的组织或 workspace 可能要求启用两步验证才能访问相关内容（例如管理员强制开启时）。如果已强制启用，你需要先开启它，才能使用受保护内容和 Pipelines。
• repository 中必须存在 bitbucket-pipelines.yml 文件。

在 Repository 级别向 Bitbucket 添加 Secret

首先，进入目标 repository，并在左侧选择 Repository settings。

接下来，在 Pipelines 下进入 Repository variables。

在表单中输入变量名和值，然后点击锁头图标将其标记为 Secured。这样可以确保 secret 在静态存储时被加密，并在 UI 和 build logs 中被隐藏，防止被其他用户查看。然后，点击 Add。

在 Workspace 级别向 Bitbucket 添加 Secret

进入你的 Bitbucket workspace。点击个人头像旁右上角的设置齿轮图标，然后选择 Workspace settings。

在左侧菜单中找到 Pipelines 部分，并点击 Workspace variables。

和之前一样，添加 secret 的名称和值，并确保点击锁头图标启用 Secured。然后，点击 Add 提交该 secret。

在 Environment 级别向 Bitbucket 添加 Secret

进入你的 repository，并选择 Repository settings。然后，找到 Pipelines 部分并点击 Deployments。

首先，选择环境（staging、production 等）。然后，再次添加 secret 的名称和值，并确保启用 Secured。接着，点击 Add 提交该 secret。

如何使用 Secrets

在 Bitbucket Pipelines 中使用 secrets 时，请记住以下原则：

• 不要 echo secrets。 Bitbucket Pipelines 会在 build logs 中遮蔽 secured variable 的值，但你仍然应避免打印 secrets，因为泄露可能通过日志、artifact 或处理不当的 workflow 输出发生。Mandiant 在 2024 年发布的研究表明，即使日志中值显示为已遮蔽，若 pipeline 脚本处理不当，secured variables 仍可能被导出到 artifacts 中。
• 不要将 secrets 以明文形式提交到 repository。 Git history 是永久的，即使之后在 tree 中修复了该 commit，该 secret 仍然会被视为已暴露。
• 要意识到，任何对 repository 有写权限的人都可以读取 secured variables。 拥有写权限的用户可以修改 pipeline YAML，将变量值发送到外部 endpoint。请将 deployment variables 与 deployment permissions 结合使用，以限制对最敏感 secrets 的访问。

Repository 和 Workspace Variables

Bitbucket 中的变量会作为环境变量提供给 Pipelines。如果你在多个地方定义了相同的变量名，Bitbucket 会按以下优先级解析其值：

Pipeline run-level variables > Deployment > Repository > Workspace > Default

在脚本中，你可以使用标准的环境变量语法引用变量（例如，$TOPSECRET）。Repository variables 会覆盖同名的 workspace variables，而 deployment variables 会覆盖两者。

有了这些背景，secrets 可以很容易地注入到 pipeline 文件中。例如，要将 TOPSECRET 注入 bitbucket-pipelines.yml 文件，你可以使用：

pipelines:
  default:
    - step:
        name: "通过 API 进行身份验证"
        image: alpine
        script:
          - echo "Calling API"
          - curl -u "user:$TOPSECRET" https://random.api.com/data

Environment/Deployment Variables

要使用 deployment variable，请使用 deployment 参数指定目标环境：

pipelines:
  default:
    - step:
        name: "使用 Deployment Variable 进行 API 身份验证"
        image: alpine
        deployment: production
        script:
          - echo "Calling API"
          - curl -u "user:$TOPSECRET" https://random.api.com/data

现在，TOPSECRET 的值将从 production deployment environment 中解析得到。Deployment variables 仅在 deployment 步骤中生效，而且每个 deployment environment 都是独立的，因此你可以对每个环境使用相同的变量名，但赋予不同的值。

使用 OpenID Connect（OIDC）的无 Key 身份验证

减少需要管理的 secrets 数量，最有效的方法之一就是彻底消除它们。Bitbucket Pipelines 支持 OpenID Connect（OIDC），它允许你的 pipeline 与 AWS、GCP 和 Azure 等云提供商进行身份验证，而无需在 Bitbucket 中存储任何长期凭据。

借助 OIDC，Bitbucket Pipelines 会为每个 pipeline step 生成一个短期身份 token。你的云提供商会验证该 token，并发放具有范围权限的临时凭据。这种方法免去了手动轮换 access key 的需求，并在 pipeline 配置遭到破坏时降低了影响范围。

它是如何工作的

1. 你在云账户中将 Bitbucket Pipelines 注册为 OpenID Connect identity provider（例如，在 AWS IAM 中）。
2. 你在云提供商中创建一个 role，该 role 信任 Bitbucket OIDC provider，并具备 pipeline 所需的权限。
3. 在 bitbucket-pipelines.yml 中，你在任何需要云访问的 step 上设置 oidc: true。Bitbucket 会生成一个唯一的 OIDC token，并将其暴露为 $BITBUCKET_STEP_OIDC_TOKEN 环境变量。
4. 你的 pipeline 使用该 token 来 assume role 并获取临时凭据。

使用 AWS 配置 OIDC

首先，从 Bitbucket 获取你的 OIDC 配置。在你的 repository 中，进入 Repository settings > Pipelines > OpenID Connect。复制 Identity provider URL 和 Audience 的值。

然后，在 AWS IAM console 中：

1. 导航到 Identity providers > Add provider。
2. 选择 OpenID Connect，粘贴来自 Bitbucket 的 Identity provider URL 和 Audience，然后点击 Get thumbprint 进行验证。
3. 点击 Add provider。
4. 创建一个新的 IAM role，并将 Web identity 作为 trusted entity。选择你刚创建的 Bitbucket provider 和 audience，并附加 pipeline 所需的 permission policies。
5. 可选地，编辑该 role 的 trust policy，使用 sub claim 限制对特定 repository 或 deployment environment 的访问。

最后，更新你的 pipeline 以使用 OIDC：

image: amazon/aws-cli

pipelines:
  default:
    - step:
        name: "使用 OIDC 部署到 AWS"
        oidc: true
        script:
          - export AWS_REGION=us-east-1
          - export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/bitbucket-deploy-role
          - export AWS_WEB_IDENTITY_TOKEN_FILE=$(pwd)/web-identity-token
          - echo $BITBUCKET_STEP_OIDC_TOKEN > $(pwd)/web-identity-token
          - aws s3 ls

Bitbucket 还提供了预构建的 AWS Pipes，原生支持 OIDC。使用 Pipe 时，你需要传递 AWS_OIDC_ROLE_ARN 变量，而不是 access keys：

pipelines:
  default:
    - step:
        name: "使用 OIDC 部署到 S3"
        oidc: true
        script:
          - pipe: atlassian/aws-s3-deploy:1.1.0
            variables:
              AWS_DEFAULT_REGION: "us-east-1"
              AWS_OIDC_ROLE_ARN: "arn:aws:iam::123456789012:role/bitbucket-deploy-role"
              S3_BUCKET: "my-bucket"
              LOCAL_PATH: "build"

OIDC 也支持 GCP、Azure 和 HashiCorp Vault。请参考 Atlassian 的文档获取针对各 provider 的配置说明。

对于任何部署到云提供商的 pipeline，OIDC 都应该是默认方案。 只有在目标服务不支持 OIDC 时，才退回到使用存储的 secrets。

第三方 Secret Providers

在 2024 年末，Atlassian 在 Bitbucket Pipelines 中引入了对第三方 secret providers 的原生支持。此功能允许 secrets 从外部 vault（如 HashiCorp Vault 或 AWS Secrets Manager）直接注入到 pipeline step 的执行环境中，而不会被存储在 Bitbucket 中。

与用户定义的 workspace 和 repository variables 不同，第三方 secrets 只有在正确配置的 pipeline step 运行时才会从你的 vault 中获取。日志会自动隐藏这些变量，并且在自托管 runner 上，secrets 会始终限制在你自己的网络内。

它是如何工作的

该集成遵循以下流程：

1. 当一个带有 oidc: true 的 pipeline step 被调度时，Bitbucket 会生成一个 OIDC JWT token。
2. runner 会向你的 secret provider endpoint 发送一个 GET 请求，并在 Authorization header 中包含 OIDC token。
3. 你的 secret provider middleware 使用 Bitbucket 的 JWKS endpoint 验证 OIDC token。
4. 验证成功后，provider 会将请求的 secrets 返回给 runner。
5. 这些 secrets 会作为环境变量注入到 step 的执行上下文中。

配置

此功能要求你构建一个小型 middleware service，用于连接你的 secret store 和 Bitbucket runner。Atlassian 提供了一个示例 Java application 作为参考实现。

对于自托管 runner，在启动 runner 时设置 SECRET_PROVIDER_URI：

docker container run \
  -e SECRET_PROVIDER_URI="http://secret.provider/endpoint" \
  # ... 其他 runner 配置

对于 cloud runners，在 workspace settings 中添加 secret provider endpoint：

1. 导航到 Workspace settings > Pipelines > Workspace variables。
2. 在提供的字段中添加你的 secret provider endpoint，然后点击 Add。

在你的 pipeline 中，为需要第三方 secrets 的 step 启用 OIDC。如果某个 pipeline variable 与 provider 中的 secret 同名，provider 的值会在运行时将其替换：

pipelines:
  default:
    - step:
        name: "使用第三方 secrets 构建"
        oidc: true
        script:
          - echo "Building with secrets from external vault"
          - ./build.sh

对于已经使用中心化 vault，并且希望避免将 secrets 复制到 Bitbucket 变量存储中的组织来说，这种方式尤其有效。

Bitbucket 的 Pipelines 方法的局限性

虽然 Bitbucket 的 secrets 能力已经大幅增强，但仍然有一些实际局限需要注意：

• 没有自动 secret rotation。 Bitbucket 不提供针对以 pipeline variables 形式存储的 secrets 的自动轮换内置工具。你可以通过第三方 secret provider 集成或 OIDC 将轮换委托给外部 vault，但如果你直接将 secrets 存储在 Bitbucket 中，则仍需要手动更新。
• 可见性限制。 一旦 secured variable 保存，其值就无法再次查看。这在安全上是有益的，但如果之后需要验证该值，可能会不太方便。你只能用新值覆盖它，或者将其删除。
• 对 pipeline variables 的审计有限。 Bitbucket 通过 Atlassian Guard（原 Atlassian Access）提供 workspace-level 审计日志，可跟踪某些管理事件。然而，Bitbucket Pipelines variables 本身并不提供详细的变更历史，无法准确显示是谁在何时修改了某个特定变量。Bitbucket Data Center 有自己的审计日志，提供更细粒度的跟踪。
• 可扩展性挑战。 随着 repository 和 secrets 数量增长，如果没有中心化系统，在多个 repository 和 environment 之间管理变量会变得繁琐。Bitbucket 没有内置方式可一次性在许多 repository 之间同步或传播变量变更。
• 外传风险。 尽管 Bitbucket 会在 build logs 中自动隐藏 secured variables，任何拥有 repository 写权限的用户都可以修改 pipeline YAML，将变量值发送到外部 endpoint。请将 deployment variables 与 deployment permissions 结合使用，以限制谁能访问敏感凭据。
• secret scanning 因平台而异。 Bitbucket Data Center 默认启用了内置 secret scanning，并支持可自定义的 regex patterns 和审计日志告警。对于 Bitbucket Cloud，secret scanning 能力取决于你的套餐以及你是否使用 Atlassian Guard。更高级的检测和防护可能需要第三方工具，如 GitGuardian 或 Soteri。

对于需求更复杂的团队，一个专门的 secrets manager，例如 Infisical，可以提供集中管理、自动轮换、更详细的审计轨迹，以及在 repository 和 environment 之间更易扩展的能力。

在 Infisical 和 Bitbucket 中使用

Infisical 是一个开源 secrets management platform，它以两种方式与 Bitbucket 集成：一种是将 secrets 自动推送到 Bitbucket variables（Secret Syncs），另一种是使用 Infisical CLI 在运行时将 secrets 拉取到 pipeline 中。

选项 1：Secret Syncs（Push-Based）

借助 Infisical 的 Bitbucket Secret Sync，存储在 Infisical 中的 secrets 会自动推送到 Bitbucket，作为 repository-level 或 deployment environment-level variables。当你在 Infisical 中更新某个 secret 时，该变更会自动同步到 Bitbucket。

要设置 Secret Sync：

1. 在 Infisical 中进入你的项目 Integrations 选项卡，然后点击 Add Sync。
2. 选择 Bitbucket 瓷贴，并授权 Infisical 访问你的 Bitbucket account。
3. 选择 Infisical project environment、secret path，以及你希望同步 secrets 到的目标 Bitbucket workspace、repository，以及可选的 deployment environment。
4. 点击 Create Integration。

创建完成后，你的 secrets 将开始自动同步。你的 pipeline YAML 不需要任何 Infisical 特定配置；它会像使用其他 Bitbucket variable 一样，使用标准 $VARIABLE_NAME 语法引用这些变量。

选项 2：CLI Injection（Pull-Based）

为了更好地控制 secrets 的获取时间和方式，你可以在 pipeline 中直接使用 Infisical CLI。这种方式会在运行时获取 secrets，并将它们注入到进程环境中，而完全不将其存储在 Bitbucket 中。

通过将 Infisical 的 OIDC Auth 方法与 Bitbucket Pipelines 内置的 OIDC 支持结合使用，你可以在不存储任何长期凭据的情况下向 Infisical 进行身份验证。Bitbucket 会为每个 pipeline step 生成一个短期 OIDC token，而 Infisical 会直接验证该 token。因此，不需要在 Bitbucket 中存储 Client ID 或 Client Secret。

步骤 1：配置 Machine Identity

在 Infisical 中，导航到 Organization Settings > Access Control > Identities，然后点击 Create identity。给它一个描述性名称（例如 “bitbucket-pipeline”），并为其分配一个 organization-level role。

步骤 2：在 identity 上配置 OIDC Auth

identity 创建完成后，你将被重定向到一个可以管理它的页面。由于该 identity 默认配置的是 Universal Auth，因此你需要将其重新配置为使用 OIDC Auth。点击 Authentication 部分中的 Edit，移除现有的 Universal Auth 配置，并添加新的 OIDC Auth 配置。

使用来自 Bitbucket repository 的 OpenID Connect settings 页面中的值配置以下字段（位于 Repository settings > Pipelines > OpenID Connect）：

• OIDC Discovery URL: https://api.bitbucket.org/2.0/workspaces/YOUR_WORKSPACE/pipelines-config/identity/oidc
• Issuer: https://api.bitbucket.org/2.0/workspaces/YOUR_WORKSPACE/pipelines-config/identity/oidc
• Subject: subject（sub）claim 通常包含 repository 和 step 标识符（例如：{REPO_UUID}:{ENVIRONMENT_UUID}:{STEP_UUID}）。请通过检查 pipeline 中真实的 OIDC token 来验证其确切值。你可以使用通配符模式来允许多个 repository 或 step，或者将其留空以跳过 subject 验证。
• Audiences: Bitbucket OpenID Connect settings 页面上显示的 audience 值（格式为 ari:cloud:bitbucket::workspace/YOUR_WORKSPACE_UUID）。

步骤 3：将 identity 添加到你的项目

导航到包含你要访问的 secrets 的 Infisical project。进入 Access Control > Machine Identities，点击 Add identity，选择你创建的 identity，并为其分配一个具有 secrets 读取权限的 project-level role。

记下该 identity 的 ID，你将在 pipeline 配置中用到它。

步骤 4：更新你的 pipeline

编辑你的 bitbucket-pipelines.yml，以启用 OIDC 并使用带有 OIDC Auth 的 Infisical CLI。与其他身份验证方法的关键区别在于，你需要在 pipeline step 上设置 oidc: true，并将 Bitbucket 生成的 OIDC token（$BITBUCKET_STEP_OIDC_TOKEN）直接传递给 Infisical CLI：

image: atlassian/default-image:3

pipelines:
  default:
    - step:
        name: 使用 Infisical 中的 secrets 构建应用
        oidc: true
        script:
          - apt-get update && apt-get install -y curl
          - curl -1sLf 'https://artifacts-cli.infisical.com/setup.deb.sh' | bash
          - apt-get update && apt-get install -y infisical
          - export INFISICAL_TOKEN=$(infisical login --method=oidc-auth --machine-identity-id=YOUR_IDENTITY_ID --oidc-jwt=$BITBUCKET_STEP_OIDC_TOKEN --silent --plain)
          - infisical run --projectId=YOUR_PROJECT_ID --env=dev -- npm run build

将 YOUR_IDENTITY_ID 替换为来自 Infisical 的 machine identity ID，并将 YOUR_PROJECT_ID 替换为你的 Infisical project ID。--env 标志指定从哪个 Infisical environment 拉取 secrets（例如 dev、staging 或 prod）。infisical run 命令会从指定的 project 和 environment 中获取所有 secrets，然后将它们作为环境变量注入到 -- 分隔符后面的命令中。

使用此配置后，Bitbucket 中完全不会存储任何 Infisical 凭据。身份验证完全基于 Bitbucket 为每个 pipeline step 生成的短期 OIDC token，而 Infisical 会使用 Bitbucket 的公开 JWKS endpoint 进行验证。

Infisical 返回的每个 identity access token 都具有可配置的存活时间（TTL），默认值为 7200 秒。你可以在 machine identity 的 OIDC Auth 配置中进行调整。

你可以参考 Infisical 端到端的 OIDC Auth 文档 了解更多配置选项，包括如何按 subject、audience 和自定义 claim 限制访问。

重要：App Password 弃用

Atlassian 正在将 Bitbucket Cloud 从 app password 迁移到 API token。此次变更遵循分阶段时间线：

• 阶段 1（2025 年 6 月）：宣布弃用。现有 app password 继续可用。团队可以开始迁移到 API token。
• 阶段 2（2025 年 9 月 9 日）：停止创建新的 app password。所有新集成都必须使用 API token。
• 阶段 3（2026 年 6 月 9 日）：所有剩余的 app password 将被永久禁用。Bitbucket Cloud 身份验证将仅支持 API token。

API token 通过过期控制、范围权限以及更好的管理员可见性提供了更强的安全性。如果你的团队在脚本、CI/CD 工具或连接到 Bitbucket 的第三方集成中使用 app password，请立即开始迁移到 API token。

要创建 API token：进入 Settings > Atlassian account settings > Security，然后选择 Create and manage API tokens > Create API token with scopes。分配必要的 Bitbucket 权限并设置合适的过期日期。该 token 只显示一次，因此请妥善保存。

在 Bitbucket 中保护敏感数据

有效管理 secrets 对于维护整个开发基础设施的安全至关重要。无论你使用的是 Bitbucket 的内置 variables、OIDC 无 key 身份验证、第三方 secret providers，还是像 Infisical 这样的专用平台，核心目标始终一致：限制访问并防止泄露。

在使用 Bitbucket 时，请记住：

• 优先使用 OIDC 而不是存储凭据 来进行云提供商身份验证。这消除了存储和轮换长期 access key 的需要。
• 为每个 secret 选择正确的 scope。对生产凭据使用带有 deployment permissions 的 deployment variables；对 repository 专属配置使用 repository variables；仅在确实共享的值上使用 workspace variables。
• 限制写权限 到包含敏感 secrets pipeline 的 repository，因为任何拥有写权限的人都可能外传 secured variables。
• 在 2026 年 6 月 9 日截止日期前，从 app password 迁移到 API token。
• 如果你的组织已经使用中心化 vault，则评估第三方 secret provider 集成，以避免将 secrets 复制到 Bitbucket 中。

遵循这些实践将有助于确保敏感信息得到保护，同时仍可供授权的团队成员和自动化 workflow 访问。

• 原文链接： infisical.com/blog/bitbu...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～