GitHub Actions OIDC immutable subject claims：IAM 信任政策怎麼遷移？

先看舊格式與 immutable 格式#

以 octo-org/octo-repo 的 main branch 為例，GitHub 官方文件列出的差異如下：

如果 job 使用 environment，sub 的 context 會改成 environment 形式，例如：

1
repo:octo-org@123456/octo-repo@456789:environment:Production

這些數字只是官方格式示例，不是你的 repository ID。不要把文章、別人的 IAM 設定或 repository URL 中的數字直接貼進生產政策；應從你自己的實際 token、GitHub API 或 repository 設定取得值。

為什麼名稱不夠安全？#

舊的預設 sub 主要使用 organization 和 repository name。如果 repository 被刪除，名稱在之後被另一個 owner 重新建立，雲端 trust policy 看到的字串可能一樣，卻已經不是原來的 repository。Immutable 格式把 owner ID 和 repository ID 放進 repo segment，讓名稱變更或 namespace 重新建立時更容易維持唯一性。

目前需要特別盤點三種事件：

• 2026 年 7 月 15 日之後新建 repository：預設直接使用 immutable 格式。
• 2026 年 7 月 15 日之前的既有 repository：預設保留舊格式，除非 opt in。
• 2026 年 7 月 15 日之後的 repository rename 或 transfer：GitHub 文件指出會移到 immutable 格式。

如果同一個組織同時有新舊 repository，不能把一條以 repo:ORG/REPO:* 為基礎的政策當成所有 repository 都會通過；每個 trust relationship 都要核對它實際收到的 sub。

OIDC workflow 先只做 claims 檢查#

GitHub 官方提供 github/actions-oidc-debugger action，可以在接雲端 provider 前查看 workflow 會收到的 claims。最小的檢查 workflow 可以長這樣：

1
name: Inspect Actions OIDC claims
2

3
on:
4
  workflow_dispatch:
5

6
permissions:
7
  id-token: write
8

9
jobs:
10
  inspect:
11
    runs-on: ubuntu-latest
12
    steps:
13
      - name: Print OIDC claims
14
        uses: github/actions-oidc-debugger@main

id-token: write 的意思是允許 workflow 向 GitHub OIDC provider 取得 JWT，不是讓 job 對其他資源取得 write access。這個 debug workflow 不需要 checkout；如果你的實際工作還要讀取原始碼，才另外加入 contents: read。

在共用 repository 或生產環境使用 action 時，應依組織供應鏈政策把 action pin 到受信任的 commit SHA；上面的 @main 只是為了對照官方 debugger 的最小概念範例。Debug log 可能包含不應公開的 claims，請限制 workflow 的觸發者和 log 存取權，不要把完整 JWT 複製到 issue 或聊天頻道。

檢查結果至少記錄：

雲端信任政策的遷移順序#

不要先在 GitHub 啟用新格式，再回頭猜雲端應該改成什麼。較安全的順序是：

1. 列出所有使用 GitHub OIDC 的 AWS、Azure、Google Cloud、Vault 或其他 provider trust relationship。
2. 對每個 repository 和觸發條件執行受限制的 debug workflow，保存 iss、aud、sub 和非敏感識別資訊。
3. 先在 cloud provider 建立能匹配新格式的條件；如果 provider 支援短暫並存，舊格式條件應設定清楚的移除期限，不要用無限制 wildcard 代替遷移。
4. 依 GitHub OIDC 設定 UI 或 REST API 為既有 repository opt in，或套用組織的 subject customization；不要把 opt-in 和雲端 login action 的 audience 設定混為一談。
5. 執行實際部署 workflow，確認雲端收到的新 sub、aud 和 job_workflow_ref 都符合預期。
6. 確認所有舊版 workflow 都已切換後，再刪除舊 trust condition，並保留回滾紀錄。

GitHub 文件特別提醒，如果要自訂 sub template，應先在雲端建立匹配條件，再透過 API 套用 GitHub 設定，避免 token 已改格式但 provider 尚未同步。自訂 subject 會改變整個 sub 的格式；對 immutable repository 而言，owner ID 與 repository ID 仍會保留在 repo segment，不能靠 include_claim_keys 移除。

Provider 條件只換字串，不要放寬邊界#

不同雲端 provider 寫 trust condition 的語法不同，但核心都是讓 sub 精確對應 GitHub token：

不要因為遷移麻煩就把條件改成只驗 repository_owner、只驗 aud，或對整個 organization 使用寬鬆 wildcard。若部署需要限制 branch、environment 或 reusable workflow，就把它們一併納入明確的 claims 設計。真正需要的最小權限，應在 cloud role 的 permission policy 另外維持。

什麼時候用 subject customization？#

Immutable default 解決 repository identity 的唯一性；subject customization 則處理更細的信任條件。例如組織想要求所有部署都經過固定 reusable workflow，可以使用 job_workflow_ref 作為 sub 的一部分。這是另一個設定層級，不能因為看到 include_claim_keys 就以為等同於 immutable default。

目前文件列出的幾個選擇方向是：

• 只限制某個 repository：使用 repo 條件。
• 限制 environment 或 branch：使用預設 context 的對應格式。
• 統一組織部署入口：把 job_workflow_ref 納入條件。
• 依 repository metadata 做 ABAC：使用 repo_property_* claims，但要先由組織或 enterprise 管理員啟用。

每次改 template 後，都要重新取得一個新 job 的 token 驗證；舊 job 的 JWT 不會因設定修改而變成新格式。

排錯清單#

常見問題#