CI pipeline 的可靠性驗證在測試階段結束後，還需要兩道控制面才算完整。第一道是 deploy approval gate — 決定誰可以核准 production deploy、在什麼條件下放行。第二道是 credential 安全 — deploy 需要 cloud credential，但 long-lived secret 存在 CI 環境中會擴大洩漏面。

GitHub Actions 用 environment protection rules 處理第一道，用 OIDC federation 處理第二道。兩者搭配讓 deploy 流程同時滿足 6.8 release gate 的放行控制與 07 資安 的 credential 最小暴露原則。

Environment Protection Rules

Environment 是 GitHub Actions 的 deploy 分層單位。每個 environment（staging / canary / production）可以獨立設定 protection rules，讓不同風險等級的 deploy 走不同的放行流程。

Protection rule 類型

Required reviewers 是 deploy 層的 release gate。當 workflow job 標記 environment: production，GitHub 會暫停 job 直到指定 reviewer 核准。reviewer 的選擇應對齊服務 ownership — 由該服務的 on-call lead 或 tech lead 核准，避免核准權過於集中或分散。

Wait timer 提供一個緩衝窗口。deploy 前等待 N 分鐘讓團隊有時間檢查 staging 結果、確認沒有進行中的事故、或在發現問題時取消 deploy。timer 長度跟服務風險等級對齊 — 低風險服務可以 0 分鐘，交易路徑可以 15-30 分鐘。

Deployment branch policy 限制哪些 branch 可以觸發特定 environment 的 deploy。這防止 feature branch 意外 deploy 到 production。production 通常只接受 main 或 release branch。

分層建議

staging 用自動 deploy — push 到 staging branch 直接觸發 workflow，無需 approval，回饋速度最大化。production 用 required reviewer + wait timer — 確保每次 production deploy 都經過人工確認與緩衝。canary 介於兩者之間 — 可以自動 deploy 但加 wait timer，讓觀測指標有時間反映。

OIDC Cloud Auth

Long-lived credential 的風險

CI deploy 需要 cloud credential（AWS access key / GCP service account key / Azure service principal）。傳統做法是把這些 credential 存在 GitHub repository secret 或 environment secret 中。long-lived credential 的風險在於：洩漏後攻擊者可以長期使用、rotation 需要手動更新 CI 設定、credential scope 常設得比實際需求更大。

OIDC federation 的運作方式

GitHub Actions 支援作為 OIDC identity provider。workflow 在執行時可以向 GitHub 請求一個 short-lived OIDC token，cloud provider 信任這個 token 後發出 short-lived cloud credential。整個流程不需要在 CI 環境中存放任何 long-lived secret。

流程：workflow 啟動 → 向 GitHub OIDC provider 請求 token → token 帶有 repo / branch / environment 等 claim → cloud provider 的 trust policy 驗證 claim → 發出 short-lived credential（通常 1 小時有效期）。

Cloud provider 配置

AWS：在 IAM 設定 OIDC identity provider（issuer: token.actions.githubusercontent.com）、建立 IAM role 並設定 trust policy 限制 repo + branch + environment。workflow 中用 aws-actions/configure-aws-credentials action 取得 session credential。

GCP：設定 Workload Identity Federation pool + provider、建立 service account 並綁定 pool。workflow 中用 google-github-actions/auth action 取得 short-lived token。

Azure：在 Azure AD 設定 federated credential 給 app registration、限制 repo + branch + environment。workflow 中用 azure/login action。

Trust policy 的安全邊界

OIDC trust policy 必須限制到特定 repo、branch 與 environment。trust policy 寫成 wildcard（信任整個 GitHub org 的所有 repo）等於讓 org 內任何 repo 的 workflow 都能取得 cloud credential。最小權限原則：production environment 的 trust policy 只信任 repo:org/service:environment:production，不信任其他 environment 或 branch。

實作範例

 1# .github/workflows/deploy.yml
 2name: Deploy
 3on:
 4  push:
 5    branches: [main]
 6
 7permissions:
 8  id-token: write
 9  contents: read
10
11jobs:
12  deploy-staging:
13    runs-on: ubuntu-latest
14    environment: staging
15    steps:
16      - uses: actions/checkout@v4
17      - uses: aws-actions/configure-aws-credentials@v4
18        with:
19          role-to-assume: arn:aws:iam::123456789012:role/staging-deploy
20          aws-region: ap-northeast-1
21      - run: ./scripts/deploy.sh staging
22
23  deploy-production:
24    needs: deploy-staging
25    runs-on: ubuntu-latest
26    environment: production
27    steps:
28      - uses: actions/checkout@v4
29      - uses: aws-actions/configure-aws-credentials@v4
30        with:
31          role-to-assume: arn:aws:iam::123456789012:role/production-deploy
32          aws-region: ap-northeast-1
33      - run: ./scripts/deploy.sh production

staging job 自動觸發。production job 等 staging 完成後暫停，等待 environment protection rules 中設定的 reviewer 核准。兩個 job 各自用不同的 IAM role，scope 分離。

Environment secret 與 repository secret 的差異：environment secret 只在該 environment 的 job 中可用。把 production-only 的設定（如 database connection string）存在 production environment secret 而非 repository secret，避免 staging workflow 意外存取 production 資源。

邊界與陷阱

Environment protection rules 在 private repo 上需要 GitHub Team 或 Enterprise 方案。Free 方案的 private repo 無法使用 required reviewers 與 wait timer，只有 public repo 或付費方案可用。

OIDC trust policy 的常見錯誤是 subject claim 設定太寬。sub claim 的格式是 repo:{owner}/{repo}:environment:{name}（使用 environment 時）或 repo:{owner}/{repo}:ref:refs/heads/{branch}（不使用 environment 時）。用 wildcard match 或省略 environment 限制會讓非預期的 workflow 取得 credential。

Wait timer 設定要跟服務風險等級對齊。所有服務統一用 30 分鐘 wait timer 會拖慢低風險服務的 deploy velocity。對齊方式：低風險服務 0 分鐘、中風險 5-10 分鐘、高風險（交易路徑）15-30 分鐘。

Required reviewer 數量跟團隊大小對齊。只有 1 個 reviewer 等於沒有四眼原則；需要 5 個 reviewer 會造成 approval 排隊。2-3 個 reviewer 是多數團隊的平衡點。

整合路由

• 上游：6.1 CI pipeline（CI gate 通過後才進入 deploy 階段）
• 下游：6.8 release gate（environment protection 是 deploy 層的 release gate）
• 下游：6.23 verification evidence handoff（deploy 結果作為 release evidence）
• 平行：CircleCI contexts + approval jobs（同類功能的不同實作）
• 案例回寫：Microsoft 變更分層（變更風險分層對應 environment 分層）、Google Error Budget（error budget 消耗時提高 gate 門檻 → 可動態調整 required reviewer 數量）

本文是跨 vendor migration playbook、cross-link Jenkins 跟 GitHub Actions。跑 migration-playbook-methodology 6 維 audit 後對映 Schema = High（Groovy DSL ↔ YAML workflow）→ Type A phased translation。

Pipeline 5 段 lifecycle 的對位 + 翻譯

本文按 pipeline lifecycle 5 段 組織內容（variant E）— 不是「為什麼遷」driver 開頭，是 Jenkins vs GHA 對 5 段各自的處理：

跑 6 維 diff dimension audit：

Schema = High（其他 Medium-Low）→ Type A phased translation 為主、加 paradigm + operational 獨立段。

為什麼遷：cost / vendor / cloud-native 三條 driver

• Cost：Jenkins self-hosted 是「免費 software + 高 ops cost」、GHA 按 minute 計費對中小團隊更便宜
• Vendor consolidation：repository 已在 GitHub、整合進 GHA 省一個外部系統
• Cloud-native：GHA matrix build + reusable workflow 對 cloud-native deploy（K8s / serverless）有 first-class action

Phase 0：Audit + classify

 1# Jenkins workspace 盤點
 2find . -name "Jenkinsfile" -o -name "*.groovy"
 3# 列所有 pipeline file
 4
 5# 統計 plugin 使用
 6# Jenkinsfile 內 import / @Library / sh "tool plugin..."
 7grep -rE "@Library|import|tools\s*\{" Jenkinsfile*
 8
 9# 每 pipeline 評估 complexity
10# - Simple linear pipeline: 1-3 stage、無 shared library
11# - Medium: parallel stage + 2-5 shared library
12# - Complex: 條件分支 + 動態 stage + 10+ plugin / 5+ shared library

Audit output：

• 列「100 個 pipeline、35 simple / 50 medium / 15 complex」
• 每 complexity level 估翻譯時間（simple 0.5 day / medium 2 day / complex 5-10 day）
• Plugin 依賴清單對應 GHA action 替代品

Phase 1：Schema 對位（Groovy DSL ↔ YAML）

 1// Jenkins Declarative Pipeline
 2pipeline {
 3  agent { label 'docker-build' }
 4  stages {
 5    stage('Test') {
 6      parallel {
 7        stage('Unit') { steps { sh 'mvn test' } }
 8        stage('Integration') { steps { sh 'mvn verify' } }
 9      }
10    }
11  }
12  post {
13    failure { mail to: 'devops@', subject: 'Build failed' }
14  }
15}

 1# GHA Workflow 對等
 2name: CI
 3on: [push]
 4jobs:
 5  test:
 6    runs-on: [self-hosted, docker-build]
 7    strategy:
 8      matrix:
 9        suite: [unit, integration]
10    steps:
11      - uses: actions/checkout@v4
12      - name: Run ${{ matrix.suite }}
13        run: |
14          case "${{ matrix.suite }}" in
15            unit) mvn test ;;
16            integration) mvn verify ;;
17          esac
18  notify-failure:
19    needs: test
20    if: failure()
21    runs-on: ubuntu-latest
22    steps:
23      - uses: dawidd6/action-send-mail@v3
24        with:
25          to: devops@
26          subject: Build failed

對位差異：

• parallel { ... } → strategy.matrix（粒度不同、matrix 是「同 step 不同參數」、parallel 是「不同 step」）
• post.failure → 獨立 job + if: failure()
• @Library shared library → reusable workflow（uses: ./.github/workflows/reusable.yml）
• Jenkins tools { jdk 'java17' } → setup-java action（手動配 toolchain）

Phase 2：Translation pipeline（3-tier hybrid）

對應 Splunk → Elastic translation 同 3-tier：

• Tier 1：community tool（jenkins-to-actions converter、cover 簡單 pipeline 30-50%）
• Tier 2：LLM-assisted（Claude / GPT 翻 medium complexity、人工 verify）
• Tier 3：manual（shared library 改 reusable workflow / conditional 動態 stage 重寫）

Phase 3：Parallel run（雙 CI 跑 4-8 週）

1Repository ──┬─→ Jenkins webhook ──→ Jenkinsfile pipeline
2             └─→ GitHub Action ────→ .github/workflows/ci.yml
3
4Compare:
5- 同 commit 兩端結果一致
6- Latency / cost / artifact location 對齊

Diff dashboard 列「test pass rate / build time / failure mode」三 metric、跑到 95%+ 一致才進 cutover。

Phase 4：Cutover + cleanup

• Disable Jenkins webhook
• GHA 成 primary CI
• Jenkins 留 standby 2 週 fallback
• Decommission Jenkins controller + agents

Production 故障演練

Case 1：Shared library equivalence、reusable workflow 表達不足

徵兆：複雜 Jenkins shared library（含 Groovy class / closure / 動態變數）翻成 reusable workflow 後失準、某些動態邏輯無法表達。

根因：Jenkins Groovy 是 imperative + 完整 programming language；GHA reusable workflow 是 declarative YAML、limited expressiveness。

修法：

1. 複雜邏輯外包到 script：reusable workflow 只當 orchestrator、複雜邏輯放 .github/scripts/*.sh 或 actions/javascript-action
2. 自定 composite action：multi-step logic 包進 composite action、reuse 程度比 reusable workflow 高
3. 退役過度設計的 shared library：trans 過程暴露 90% library code 其實只用 10%

Case 2：Ephemeral workspace、build cache 失敗

徵兆：cutover 後 build time 從 5 分鐘漲到 20 分鐘；Maven / Gradle / node_modules / Docker layer 每次都重抓。

根因：Jenkins agent workspace persistent、build cache 跨 build 保留；GHA ephemeral runner 每次新 VM、cache 預設沒帶。

修法：

1. actions/cache@v4：cache key 用 hashFiles('**/pom.xml') 等 lock file、cross-build 復用
2. Self-hosted runner with cache：critical pipeline 跑 self-hosted runner、persistent volume
3. Docker layer cache：用 docker/build-push-action 配 BuildKit cache、不 rebuild full image

Case 3：Plugin 不對等、CI feature 退化

徵兆：Jenkins 用 50+ plugin、GHA action marketplace 找不到對應；team 對 SonarQube quality gate / Jira integration / custom report 等失去 first-class 支援。

根因：Jenkins plugin ecosystem 20+ 年累積、GHA marketplace 5 年；某些 niche plugin 在 GHA 沒對等 action。

修法：

1. API-based integration：用 curl 對 vendor API 直接 call、不依賴 plugin / action
2. 自寫 action：critical feature 自寫 composite / JavaScript action、publish 到 marketplace
3. 退役舊 plugin：trans 期間 audit plugin 真實使用、80% 可退役

Case 4：Self-hosted runner setup + scaling

徵兆：production workload 需要 GPU / large memory runner；GHA hosted runner spec 不夠、想用 self-hosted runner、發現 scaling / security / monitoring 比 Jenkins agent 複雜。

根因：GHA self-hosted runner 是 ephemeral、scaling 需要 runner controller（actions-runner-controller on K8s）；跟 Jenkins agent / Kubernetes plugin 對應但 setup 不同。

修法：

1. actions-runner-controller (ARC)：K8s-native runner scaling、跟 Jenkins K8s plugin 對應
2. Runner labels：用 label 路由 job（runs-on: [self-hosted, gpu, linux]）
3. Security：ephemeral runner 用 short-lived token、不跨 job persist secret

Case 5：Matrix build vs parallel stage 表達差

徵兆：Jenkins 有 動態 parallel（runtime 決定要跑哪些 stage、按 input 變動）；GHA matrix 是 static at workflow load time、表達不到。

根因：GHA matrix 是 declarative、workflow parse 時 expand；runtime 動態決定 stage 需要用 if: condition + 多 job。

修法：

1. 動態 matrix：用 jobs.set-matrix 先跑一個 job 算 matrix、輸出 JSON、後續 job strategy.matrix: ${{ needs.set-matrix.outputs.matrix }}
2. conditional job：每個 dynamic stage 寫獨立 job + if: 控制觸發
3. 重設計：90% 動態邏輯其實可改 static matrix + condition、純 runtime 動態通常是 over-engineering

Capacity / cost

判讀：100+ pipeline organization 切 GHA 通常 6-12 月 ROI 持平、之後省 ops cost；< 30 pipeline 早就該切。

整合 / 下一步

跟 GitLab CI 對位

GitLab CI YAML 語法跟 GHA 接近、shared library 對應 include:、self-hosted runner 對等；Jenkins → GitLab CI migration 流程跟本文鏡像對稱、3-tier translation pipeline 通用。

跟 Circle CI 對位

CircleCI orb 對等 GHA composite action；跨 SaaS CI 切換比 Jenkins → GHA 簡單（都 YAML-based）。

反向 migration（GHA → Jenkins）

少數 enterprise（金融 / 政府）合規要求 self-hosted CI / on-prem；GHA → Jenkins 鏡像對稱、注意 Jenkins shared library 表達力更強、reusable workflow 內 dynamic 邏輯可不必拆。

下一步議題

• Reusable workflow + composite action 混用：reusable workflow 適合 跨 repo orchestration、composite action 適合 單 repo logic encapsulation
• OIDC + cloud deploy：用 OIDC token 取代 long-lived cloud credential、是 GHA migration 順便升級的機會
• Cost optimization：minute-based billing 對 high-volume CI 需要 monitoring + budget alert

相關連結

• Target vendor：GitHub Actions
• 平行 vendor：CircleCI
• 平行 migration playbook（Type A）：Splunk → Elastic Security / MySQL → PostgreSQL
• Methodology：Migration playbook methodology