GitHub Actions 用 OIDC 连接云平台并移除长期密钥

把 GitHub Actions 连接云平台的方式从长期 Access Key 改成 OIDC，核心不是“换一个 Secret”，而是让每次工作流运行都向 GitHub 请求短期身份令牌，再由云平台按受限信任策略换发临时凭证。下面以 AWS 为完整示例：先创建身份提供商与 IAM 角色，再修改工作流，确认角色身份正确后才删除旧密钥。

GitHub 官方说明：https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws

AWS IAM 入口：https://console.aws.amazon.com/iam/

迁移前先保留一个可回退窗口

不要一开始就删除旧密钥。先记录当前工作流名称、部署分支、AWS 区域、目标账户和实际需要的服务权限，并为 OIDC 新建独立角色。迁移期间让旧 Secret 暂时保留，但新工作流不再引用它；只有 OIDC 连续验收成功后才执行清理。

本文示例使用组织 acme-lab、仓库 release-service、分支 main。请替换成自己的真实范围。AWS 中国区等非默认分区的 Audience 与 ARN 格式不同，不能照搬常规分区的 sts.amazonaws.com。

步骤一：在 AWS IAM 添加 GitHub OIDC 身份提供商

界面路径：AWS Console → IAM → Access management → Identity providers → Add provider。

1. Provider type 选择 OpenID Connect。
2. Provider URL 填写 https://token.actions.githubusercontent.com。
3. Audience 填写 sts.amazonaws.com。
4. 点击 Add provider。

可见成功状态：返回 Identity providers 列表后，能看到 token.actions.githubusercontent.com；进入详情页，Audience 包含 sts.amazonaws.com。这里不需要保存 GitHub Token，也不应创建新的 IAM 用户 Access Key。

步骤二：创建只信任目标仓库和分支的 IAM 角色

界面路径：IAM → Access management → Roles → Create role → Web identity。

1. Identity provider 选择刚创建的 token.actions.githubusercontent.com，Audience 选择 sts.amazonaws.com。
2. GitHub organization、repository 和 branch 分别填入自己的组织、仓库和部署分支。不要把仓库或分支留成无边界的通配范围。
3. 在 Add permissions 页面只选择部署真正需要的策略。生产环境更适合自定义最小权限策略，而不是直接附加管理员权限。
4. 角色命名为可识别用途，例如 release-service-deploy-main，创建后复制 Role ARN。

可见成功状态：角色详情的 Trust relationships 同时限制 aud 与 sub。常见分支范围形如 repo:组织/仓库:ref:refs/heads/main。新建仓库、改名后的仓库或已经启用不可变声明的仓库，sub 可能包含组织和仓库的数字 ID；如果工作流随后报 Not authorized to perform sts:AssumeRoleWithWebIdentity，应依据实际令牌声明修正信任条件，而不是放宽成任意仓库。

如果工作流使用 GitHub Environment，sub 会体现 Environment 名称。此时还应在仓库的 Settings → Environments → 目标环境 → Deployment branches and tags 中限制可部署分支，并配置必要审批。

步骤三：修改 GitHub Actions 工作流申请短期凭证

界面路径：GitHub 仓库 → Code → .github/workflows/deploy.yml → Edit，或者 Actions → 目标工作流 → View workflow file → Edit。

删除工作流中读取长期密钥的参数，加入 id-token: write。contents: read 只授予检出代码所需的最小仓库权限。示例使用当前官方 AWS 凭据 Action 的 v6 系列：

name: deploy

on:
  workflow_dispatch: # 先手动触发，便于控制迁移验收

permissions:
  id-token: write    # 允许工作流向 GitHub 申请 OIDC 令牌
  contents: read     # actions/checkout 读取仓库内容所需

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Configure short-lived AWS credentials
        uses: aws-actions/configure-aws-credentials@v6.3.0
        with:
          # 只传角色 ARN 与区域，不再传长期 Access Key。
          role-to-assume: arn:aws:iam::123456789012:role/release-service-deploy-main
          aws-region: ap-southeast-1

      - name: Verify assumed identity
        run: |
          # 验收账户与角色是否符合预期，不打印任何凭证。
          aws sts get-caller-identity

把示例账户号、角色名和区域替换成自己的值。为了降低第三方 Action 被篡改的供应链风险，正式环境可进一步把 uses 固定到经过审核的完整提交 SHA，并用依赖更新工具维护版本。

可见成功状态：工作流文件中存在 id-token: write，凭据步骤只有 role-to-assume 和 aws-region，不再出现 secrets.AWS_ACCESS_KEY_ID 或 secrets.AWS_SECRET_ACCESS_KEY。

步骤四：运行验收后删除长期密钥

运行路径：仓库 → Actions → 选择 deploy 工作流 → Run workflow → 选择 main → Run workflow。

打开本次运行，先看 Configure short-lived AWS credentials 是否成功，再展开 Verify assumed identity。结果中的 Account 应是目标账户，Arn 应指向刚创建的角色会话，而不是旧 IAM 用户。不要把临时凭证、OIDC 令牌或完整敏感声明复制到日志。

确认部署任务也成功后，再按以下顺序清理：

1. GitHub 路径：Settings → Secrets and variables → Actions → Repository secrets，删除 AWS_ACCESS_KEY_ID 与 AWS_SECRET_ACCESS_KEY。如果旧密钥放在 Environment secrets，也要进入 Settings → Environments → 目标环境 → Environment secrets 删除。
2. AWS 路径：IAM → Users → 旧部署用户 → Security credentials → Access keys。先 Deactivate，完成一次无密钥复跑后再 Delete。
3. 再次手动运行同一工作流，确认凭据配置、身份核对和部署步骤仍全部成功。

可见成功状态：Actions 运行页面显示 OIDC 登录、身份核对和部署成功；Repository secrets 与 Environment secrets 中不再存在旧 AWS 长期密钥；对应 IAM 用户 Access Key 已删除或 IAM 用户已退役。

常见异常怎么修正

归档一份可审计的迁移记录

把角色 ARN、信任范围、权限策略名称、工作流文件路径、验收运行编号、旧密钥停用与删除时间记录到团队变更单中，但不要保存任何密钥值或令牌。最终证据应说明“谁可以承担哪个角色、允许从哪个仓库和分支进入、得到哪些最小权限、哪次工作流完成了无长期密钥验收”。

相关问题

id-token: write 会让工作流直接写入云资源吗？

不会。它只允许工作流请求 OIDC 令牌；能否承担角色以及承担后能操作哪些资源，仍由 AWS 角色信任策略和权限策略共同决定。

可以给整个组织的所有仓库通配一个角色吗？

技术上可以配置较宽的 sub，但不适合作为默认方案。部署角色应尽量限制到明确仓库、分支或 Environment，避免其他工作流获得同一权限。

为什么要先停用旧 Access Key，再删除？

短暂的停用窗口便于发现遗漏的旧工作流或外部脚本；确认 OIDC 复跑和相关自动化都正常后再删除，可兼顾可回退性与最终清理。