GitHub Actions workflow 被跳過後卡在 Pending？先處理 required check

先分清楚是 workflow 被跳過，還是 job 被跳過#

GitHub 官方把這幾種結果分得很清楚：

這個差異很重要。把 if 從 job 移到 on.pull_request.paths，看起來只是把條件往上移一層，實際上卻會讓整個 workflow 消失。GitHub 的保護規則無法把「不存在的 workflow run」當成成功。

先查三個地方，不要重跑一個不存在的 run#

遇到 Pending 時，我會按照這個順序查：

1. PR 的 Checks 頁面：確認缺少的是哪一個 check 名稱，以及它要套用在哪個 commit SHA。
2. 分支保護或 ruleset：確認這個 check 是否被列為 required，是否還要求 branch 必須先更新到最新 base branch。
3. workflow 的 on 區段：搜尋 paths、paths-ignore、branches、branches-ignore，再看最近的 commit message 是否包含 skip 指令。

可以先在 repository 根目錄列出可能的觸發條件：

1
rg -n \
2
  '(^|[[:space:]])(paths|paths-ignore|branches|branches-ignore|pull_request|push|merge_group):|skip (ci|actions)' \
3
  .github/workflows .github 2>/dev/null

這個搜尋只協助定位，不會告訴你某個 PR 的檔案是否真的符合 glob。最後仍要把實際變更檔案和 workflow 的 pattern 對照；branches 與 paths 同時存在時，兩組條件都要通過才會觸發。

最容易重現 Pending 的 workflow 寫法#

下面的 workflow 只在 scripts/ 變更時觸發：

1
name: ci
2

3
on:
4
  pull_request:
5
    paths:
6
      - 'scripts/**'
7

8
jobs:
9
  build:
10
    runs-on: ubuntu-latest
11
    steps:
12
      - uses: actions/checkout@v4
13
      - run: npm ci
14
      - run: npm test

如果分支保護把 build 列為 required，而 Pull Request 只修改 repository 根目錄的 README.md，這個 workflow 不會建立 run。GitHub 官方的排錯文件也直接以這種情境說明：required check 會留在等待狀態，PR 因此無法合併。

三種修法，依你的檢查邊界選一種#

1
name: ci
2

3
on:
4
  pull_request:
5
  merge_group:
6

7
jobs:
8
  build:
9
    if: >-
10
      github.event_name == 'merge_group' ||
11
      contains(github.event.pull_request.changed_files, 'scripts')
12
    runs-on: ubuntu-latest
13
    steps:
14
      - uses: actions/checkout@v6
15
      - run: npm ci
16
      - run: npm test

1
jobs:
2
  lint:
3
    runs-on: ubuntu-latest
4
    steps:
5
      - run: ./scripts/run-lint.sh
6

7
  build:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - run: ./scripts/run-build.sh
11

12
  required:
13
    if: ${{ always() }}
14
    needs: [lint, build]
15
    runs-on: ubuntu-latest
16
    steps:
17
      - name: Fail when a required job failed or was cancelled
18
        if: >-
19
          needs.lint.result == 'failure' ||
20
          needs.lint.result == 'cancelled' ||
21
          needs.build.result == 'failure' ||
22
          needs.build.result == 'cancelled'
23
        run: exit 1
24
      - run: echo 'Required jobs completed'

Merge queue 還要加上 merge_group#

如果 repository 啟用了 merge queue，pull_request 和 push 不一定能涵蓋被放進 queue 的測試事件。GitHub 官方要求需要在 workflow 觸發條件中加入 merge_group，否則 required check 可能不會在 queue 的測試合併提交上產生。

最小設定如下：

1
on:
2
  pull_request:
3
  merge_group:

加上事件後，仍要檢查 workflow 使用的 context。merge_group 的事件資料和 pull_request 不完全相同，不要把所有 github.event.pull_request.* 直接假設成兩種事件都存在。需要路徑判斷時，先為兩種事件分別設計 input，再在測試 PR 和 merge queue 中各跑一次。

提交前的最小驗證表#

修改 workflow 或 branch protection 後，至少驗證這四種 PR：

如果目前已經卡在 Pending，先把修法提交到新的 commit，再回到 PR 的最新 commit SHA 確認 check。GitHub 文件指出，較早 commit 的成功結果不能代替最新 SHA 上的 required check。

結論：required 的應該是結果，不是偶爾存在的 workflow#

GitHub Actions 的 paths 和 branches 很適合減少不必要的執行，但它們放在 workflow 觸發層時，可能讓 required check 完全沒有結果。遇到 Pending，先判斷是 workflow 沒有 run、job 被條件跳過，還是 merge queue 少了 merge_group；再決定要移除 required、把條件下移，或建立永遠回報的 gate。

常見問題#