GitHub Actions 部署 AWS：用 OIDC 取代长期密钥并限定仓库分支

让 GitHub Actions 部署到 AWS 的顺序是：在 IAM 注册 GitHub 的 OIDC 身份提供商，创建仅信任指定工作流上下文的角色，再由部署作业向 AWS STS 换取短期凭证。AWS 的角色接入方案采用这一路径，使部署无需在 GitHub Secrets 中保存 IAM 用户长期访问密钥。

关键限制写在角色信任策略中：aud 要匹配 AWS STS，sub 要匹配获准的仓库、分支或环境。工作流获得 id-token: write 后可以请求 OIDC 令牌，但能否承担 AWS 角色，仍由 IAM 对令牌声明的核验决定；仅把工作流触发条件设为 main 分支，不能替代这道云端授权检查。

迁移前划清旧密钥的使用范围

先找出哪些部署作业仍使用 IAM 用户访问密钥，并确认密钥来自仓库、组织或环境级 Secrets，还是由其他步骤注入。逐项记录目标 AWS 账户、部署需要调用的服务和资源，以及实际获准发布的仓库、分支与环境。若同一把密钥还供别的自动化使用，把那些调用方列出来；否则停用密钥时，受影响的范围可能超出本次迁移的工作流。

把“谁能承担角色”和“角色能做什么”分别设计。前者由信任策略限制，后者由附加在角色上的权限策略限制。生产与测试发布若使用不同的授权边界，可以分配不同角色；生产角色只授予部署所需的操作和资源。短期凭证会到期，但如果角色本身拥有过宽权限，凭证有效期间仍可使用那些权限。

在 IAM 创建提供商和部署角色

在目标 AWS 账户的 IAM“身份提供商”中添加 OpenID Connect 提供商，提供商 URL 填写 https://token.actions.githubusercontent.com。使用 aws-actions/configure-aws-credentials 的常规 AWS 接入方式时，受众填写 sts.amazonaws.com。随后创建以 Web identity 为受信任实体的 IAM 角色，选择该提供商，保存角色 ARN，供部署工作流填写 role-to-assume。

检查角色信任策略的 Federated 主体是否指向该账户中的 GitHub OIDC 提供商 ARN，允许的操作是否为 sts:AssumeRoleWithWebIdentity。再检查角色权限策略：身份校验成功只意味着作业可以承担角色，实际能否上传构件或更新部署目标，还取决于角色对相应 AWS 操作和资源的授权。用控制台创建角色后，应重新打开生成的信任策略，确认仓库和分支范围符合预期。

用 aud 与 sub 限定可承担角色的作业

对于使用名称式主体格式、只允许 ORG 组织中 REPO 仓库的 main 分支部署的假设情形，可在信任策略的 StringEquals 中精确匹配以下条件。ORG 和 REPO 是占位名称，填写前应以目标仓库实际使用的 OIDC 主体格式为准。

token.actions.githubusercontent.com:aud 为 sts.amazonaws.com，表示令牌面向配置中的 AWS STS 受众。
token.actions.githubusercontent.com:sub 为 repo:ORG/REPO:ref:refs/heads/main，将该角色限定给指定仓库的 main 分支上下文。

AWS IAM 的 GitHub 角色说明要求信任策略包含 sub，且其值不能仅是通配符或空值；控制台未填写仓库或分支时，相应字段却可能默认使用通配符。因此，策略能保存成功不代表授权范围已经足够窄。若用 StringLike 将 sub 写成 repo:ORG/REPO:*，同一仓库的其他分支、拉取请求或环境上下文也可能匹配；若扩大为 repo:ORG/*，范围还会延伸到组织内其他仓库。

还要区分工作流触发条件与令牌主体。on.push.branches 可以控制何时启动作业，但它不是 IAM 信任条件；拉取请求触发的作业也不能仅凭目标分支名就被视为来自该分支的发布作业。对于生产角色，精确的 sub 匹配应与受保护分支及工作流文件的变更控制配合使用。

环境作业与新仓库要核对主体格式

同一个仓库的部署作业一旦声明 GitHub Environment，就不能照搬分支式 sub。GitHub 的 AWS OIDC 配置说明列出环境式主体 repo:ORG/REPO:environment:ENVIRONMENT-NAME，并指出 2026 年 7 月 15 日之后创建或已启用不可变主体声明的仓库，其 sub 还包含组织所有者与仓库的不可变 ID。

环境式 sub 绑定的是环境名称，不能单靠这一字符串把发布来源缩到 main 分支。若生产部署通过环境运行，应在 GitHub Environment 的部署分支与标签规则中限制可进入该环境的引用，并按需要设置审批；IAM 中仍要匹配正确的环境主体。配置前核对实际仓库采用名称式还是包含 ID 的主体，仓库迁移或更名后也应复查：沿用旧字符串可能导致合法部署无法承担角色。

修改工作流并核验新凭证

在承担部署角色的作业上设置 permissions 中的 id-token: write，让该作业可以请求 OIDC 令牌。若作业还要运行 actions/checkout，再按需给予 contents: read。将令牌权限放在部署作业级别，便于避免无关作业也取得请求令牌的能力；id-token: write 本身并不授予 AWS 资源写入权限。

在部署命令之前运行 aws-actions/configure-aws-credentials，填写新角色 ARN 对应的 role-to-assume 和部署区域 aws-region。迁移后的作业应移除旧的 aws-access-key-id、aws-secret-access-key 等静态密钥输入，确保凭证步骤使用 OIDC 承担角色。随后先执行 aws sts get-caller-identity，核对返回的账户和角色，再放行实际部署命令；若身份不符，先检查角色 ARN、受众、sub 格式及环境设置。

验证还应覆盖拒绝场景：从获准的分支或环境运行身份检查，再从不应取得生产权限的分支或环境尝试承担同一角色。前者应返回预期身份，后者应在凭证交换阶段被拒绝。可在 CloudTrail 中核对 AssumeRoleWithWebIdentity 事件及后续角色活动，确认部署确实走了新角色路径，而非仍由某个旧密钥完成。

停用旧密钥并保留可控回退

在获准路径与拒绝路径均符合预期后，检查所有相关工作流及组织设置，确认没有残留对 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 等旧密钥的引用。先停用旧 IAM 用户访问密钥，再观察预定的部署和其他已盘点的自动化；这一步能暴露遗漏的调用方，同时保留短暂恢复旧路径的可能。

若停用后出现遗漏，应先定位依赖该密钥的作业，修正其 OIDC 配置或另行安排权限，再重复身份与部署验证。确认旧密钥已无调用方后，从 GitHub Secrets 和 IAM 中删除它；已经删除的密钥不能作为现成的回退凭证。