GitHub Actions 9 月更新：vulnerability-alerts 與 reusable workflow 怎麼用？

先把 9 月更新分成三種問題#

不要把三項更新塞進同一個「安全性升級」步驟。前兩項是 workflow 內容與權限設計；第三項是 runner 生命週期。拆開後，失敗時比較容易判斷是 token 權限、context 不可用，還是 runner 版本問題。

用 vulnerability-alerts: read 讀 Dependabot alerts#

GitHub Actions 的 permissions 可以設定在 workflow 頂層，也可以設定在單一 job。若只讓一個稽核 job 呼叫 Dependabot alerts，建議把權限放在 job 層級，讓其他 job 不會一起拿到不需要的 token scope。未明確指定的權限會變成 none；vulnerability-alerts 只接受 read 或 none，不能設定 write。

下面的例子只列出目前 repository 的 Dependabot alerts，不需要 checkout 原始碼，因此沒有額外加入 contents 權限：

1
name: List Dependabot alerts
2

3
on:
4
  workflow_dispatch:
5

6
jobs:
7
  list-alerts:
8
    runs-on: ubuntu-latest
9
    permissions:
10
      vulnerability-alerts: read
11
    steps:
12
      - name: Read Dependabot alerts
13
        env:
14
          GH_TOKEN: ${{ github.token }}
15
          GH_REPO: ${{ github.repository }}
16
        run: |
17
          gh api --paginate "/repos/${GH_REPO}/dependabot/alerts?per_page=100" \
18
            --jq '.[] | [.number, .state, .dependency.package.name, .security_advisory.severity] | @tsv'

這段 YAML 的重點不是 gh api 本身，而是權限邊界：

• 只會授予這個 job 讀取 Dependabot alerts 的權限，其他未列出的 scope 維持 none。
• 如果 job 同時需要 checkout，才另外加入 contents: read；不要因為常見範本而把 contents: write 一起打開。
• Secret scanning 不是這個 permission 的延伸功能。GitHub 文件指出，secret scanning 需要 GitHub App 或 personal access token 的相應能力，不能只靠 vulnerability-alerts: read 取代。
• fork pull request 與 Dependabot 觸發的 workflow 仍有 token 只讀、不可使用 secrets 等限制；測試 permission 時要用實際事件再驗證一次。

若既有 workflow 已經在 job 層級明確設定 permissions，加入新的 key 後也要重新檢查其他 scope。GitHub 的行為是未列出的權限設為 none，所以「只補一行」可能讓原本依賴 contents 或 pull-requests 的步驟失敗。

用 job.workflow_* 確認 reusable workflow 來源#

Reusable workflow 最常見的稽核問題是：呼叫端寫的是一個 ref，但實際執行 job 的 workflow 檔案來自哪個 repository、哪個 commit？新的 job context 欄位讓被呼叫的 workflow 可以把來源記錄下來：

在 reusable workflow 內，這組值用來辨識 reusable workflow 自己的來源；它不是把 caller 的 repository 當成被呼叫檔案的來源。這個差異對跨 repository 的部署範本、稽核 log 和 checkout 很重要。

例如，平台團隊可以在 reusable workflow 內 checkout 定義該 workflow 的 repository 與 commit，並只記錄不含 secret 的來源欄位：

1
name: Reusable deploy
2

3
on:
4
  workflow_call:
5
    inputs:
6
      environment:
7
        required: true
8
        type: string
9

10
jobs:
11
  deploy:
12
    runs-on: ubuntu-latest
13
    steps:
14
      - name: Checkout workflow source
15
        uses: actions/checkout@v6
16
        with:
17
          repository: ${{ job.workflow_repository }}
18
          ref: ${{ job.workflow_sha }}
19

20
      - name: Record workflow source
21
        env:
22
          WORKFLOW_REF: ${{ job.workflow_ref }}
23
          WORKFLOW_SHA: ${{ job.workflow_sha }}
24
          WORKFLOW_REPOSITORY: ${{ job.workflow_repository }}
25
          WORKFLOW_FILE: ${{ job.workflow_file_path }}
26
        run: |
27
          printf 'workflow_ref=%s\n' "$WORKFLOW_REF"
28
          printf 'workflow_sha=%s\n' "$WORKFLOW_SHA"
29
          printf 'workflow_repository=%s\n' "$WORKFLOW_REPOSITORY"
30
          printf 'workflow_file_path=%s\n' "$WORKFLOW_FILE"

這些欄位是來源資訊，不是授權決策的替代品。若部署流程要求只能使用已審核的 reusable workflow，仍應在 caller 端 pin 到受控的 commit SHA，並維持最小 token 權限；不要只把 workflow_ref 印進 log 就當作供應鏈驗證完成。若 reusable workflow 還會傳遞 secrets，權限和傳遞方式可對照 GitHub Actions reusable workflow 的 secrets 邊界。

GHES 與跨事件測試不能省略#

GitHub 官方 contexts 文件目前註明，這四個 job.workflow_* 欄位在 GitHub Enterprise Server（GHES）不提供。若同一份 workflow 同時支援 GitHub.com 與 GHES，應把這些欄位視為可選資料，或由 caller 透過明確 input 傳入需要的識別資訊；不要在沒有 fallback 的情況下直接讓 null 進入部署路徑。

建議用以下矩陣做一次驗證：

測試時要保存 workflow run、事件類型、repository 與 commit，而不只是貼上一段成功的 console output。權限問題通常只在特定 trigger 或 fork 權限模式下出現。

一個可回滾的採用順序#

1. 先複製現有 workflow 的成功 run 與目前 permissions 設定，作為 baseline。
2. 只在 Dependabot audit job 加入 vulnerability-alerts: read，先驗證 API 和其他步驟。
3. 在 reusable workflow 加入 job.workflow_* 的非敏感 log，確認 caller、ref、SHA 和 path 的實際值。
4. 對 GitHub.com、fork／Dependabot 事件與 GHES 分別測試；為不可用的 context 加 fallback。
5. 最後才把來源資訊接到稽核或部署策略，並保留能回到舊版 workflow 的 commit。

這樣可以把「取得資料」和「相信資料」分成兩個 review。新 context 能幫你看清楚 job 由哪個 workflow 檔案定義，但真正的供應鏈安全仍取決於 ref pinning、token 權限、runner 和部署端的驗證。

實務上，這次更新的重點是兩個小而清楚的邊界：Dependabot alerts 用 vulnerability-alerts: read 精準授權；reusable workflow 用 job.workflow_* 記錄執行來源。先在單一 job 和非敏感 log 驗證，再擴大到部署或稽核流程，回滾與定位都會比較容易。

常見問題#