D2：使用與疑難排解工作流程

D2-O1 解讀工作流程行為與結果

這個目標考的是「讀」：看著一份設定與一份日誌，說出它為什麼這樣跑、為什麼失敗、該怎麼重跑。先從設定判斷觸發條件與效果，再到執行紀錄驗證。

從設定與日誌辨認觸發條件

• 設定層：on: 列出事件，事件各自的細節（預設分支限制、GITHUB_SHA、GITHUB_REF）見領域一。
• 執行層：同一份工作流程可能由多個事件觸發，用 github.event_name 辨認這一次是哪個事件；run-name 可以用 github 與 inputs context 組出可讀的名稱，沒有設定時會退回事件資訊，例如 commit 訊息或 PR 標題。

診斷失敗的執行

1. 開 repository 的 Actions 頁籤，選工作流程與該次執行，再點 Jobs 底下的 job。需要有讀取權限。
2. 失敗的步驟會自動展開，每個步驟都顯示耗時。
3. 點步驟的行號可以產生指到那一行的連結。
4. 右上角的 Search logs 只搜尋已展開的步驟，所以要先展開要找的步驟。
5. 從齒輪選單可以 Download log archive。若工作流程只重跑了一部分，封存檔只含重跑的 job，要看前一次嘗試就必須下載先前嘗試的封存檔。
6. 命令列用 gh run view RUN_ID --log 看整次執行的日誌，--log-failed 只看失敗的步驟，gh run view --job JOB_ID --log 看單一 job。

啟用除錯記錄

• ACTIONS_STEP_DEBUG 設為 true：讓 job 日誌更詳細，出現更多除錯事件；::debug:: 訊息也只有在它為 true 時才顯示。
• ACTIONS_RUNNER_DEBUG 設為 true：啟用 runner 診斷記錄，封存檔會多出 runner-diagnostic-logs 資料夾，內含 runner 程序記錄與 worker 程序記錄。
• 兩者都可以建立成 secret 或 variable；同時存在時，secret 優先。建立它們需要 repository 的寫入權限（個人帳號的 repository 要是協作者）。
• 不想改設定時，重新執行時勾選 Enable debug logging（CLI 加 --debug）就會同時啟用 runner 診斷與步驟除錯；任何能執行該工作流程的人都能這樣做。
• runner.debug context 可以讓某些步驟只在除錯記錄啟用時執行。

重新執行

• 初次執行後 30 天內可以重跑；一次執行最多重跑 50 次（完整與部分重跑都計入）。
• 重跑使用與原事件相同的 GITHUB_SHA 與 GITHUB_REF，並以最初觸發者的權限執行。這代表重跑不會拿到新的 commit；要測新的程式碼，必須推新的 commit 或重新觸發。
• 工作流程被停用時不能重跑，要先啟用。
• REST API 的對應端點：POST /repos/{owner}/{repo}/actions/runs/{run_id}/rerun（整個）、.../rerun-failed-jobs（失敗的 job）、POST /repos/{owner}/{repo}/actions/jobs/{job_id}/rerun（單一 job）；後兩者會連同相依的 job 一起重跑，成功都回 201。

解讀矩陣、錨點與合併後的結果

• 矩陣會依變數組合展開成多個 job（見領域一）。診斷時先把 include、exclude 套用後的組合列出來，對照每個失敗 job 屬於哪個組合，再看失敗是否集中在某個軸（例如只有某個版本、只有 Windows）。矩陣 job 在介面上的名稱是 job-id (值1, 值2)（2026-11-03 實測，非官方文件）。
• 想只重跑某一個失敗的矩陣組合，用單一 job 重跑，不必整個矩陣重來。
• 有 YAML 錨點與別名時，先把它們展開成完整的設定再判斷實際行為；官方說展開後與完整寫出等價。

判斷練習

情境 A： 某次執行失敗後，你修好了程式碼並推送，然後在舊的執行上按 Re-run failed jobs，結果還是同樣的錯。

解析： 重跑使用原本事件的 GITHUB_SHA 與 GITHUB_REF，不會拿到新 commit。新推送會觸發新的執行；要驗證修復就看新執行，不是重跑舊的。

情境 B： 你要看某個 job 的 runner 如何被配置，一般日誌看不出來。

解析： 重新執行並勾選 Enable debug logging（或設定 ACTIONS_RUNNER_DEBUG），下載封存檔，在 runner-diagnostic-logs 資料夾找 runner 與 worker 程序記錄。

來源：Re-run workflows and jobs（GH200-DOC-14）、Use workflow run logs（GH200-DOC-15）、Enable debug logging（GH200-DOC-16）、REST: workflow runs（GH200-DOC-22）；2026-11-03 以頁面原文比對本節的數字與條件。重新執行頁面沒有涵蓋 run_attempt、可重用工作流程與矩陣 job 的重跑細節，本節沒有補寫。

D2-O2 存取工作流程成品與記錄

在介面、命令列與 API 取得

REST API 的細節

• 列出成品：GET /repos/{owner}/{repo}/actions/artifacts（整個 repository）與 GET .../actions/runs/{run_id}/artifacts（單次執行）回傳相同結構；後者可用 name 與 direction（asc 或 desc，預設 desc）。兩者都支援 per_page（最多 100）與 page。
• 下載成品：archive_format 必須是 zip；回應是 302 重新導向，下載網址在 Location: 標頭，這個網址只有 1 分鐘有效，所以要立刻跟著抓。
• 下載執行日誌：同樣回 302 導向封存檔，連結 1 分鐘後失效。
• 每個成品物件都有布林欄位 expired 與 expires_at；用來判斷是否已被保留期清掉。
• 列出執行時，帶 actor、branch、event、status 等篩選條件，單次搜尋最多回傳 1,000 筆結果。
• 權限：讀取類端點需要 repository 讀取權限；私有 repository 若用 OAuth 或 classic PAT，需要 repo scope；下載與刪除成品需要 repo scope。
• 刪除一次執行時，它的成品也會一起從儲存空間刪除。

在工作流程內取得成品

actions/download-artifact 預設只能取得同一次執行稍早上傳的成品；跨執行下載要提供 token 與執行編號。指定 name 下載單一成品，不指定則全部下載，各放進以成品命名的資料夾。上傳端回傳的 digest（SHA256）會被下載端重新計算比對，不符時在介面與日誌顯示警告。

判斷練習

情境 A： 你的指令稿呼叫成品下載端點後拿到 302，並把 Location: 網址存起來，隔天才用它下載，結果失敗。

解析： 下載網址只有 1 分鐘有效。每次要下載時都重新呼叫端點，取得新的 Location: 網址並立刻使用。

情境 B： 需要清掉一個含大量成品的舊執行，以釋放儲存空間。

解析： 刪除該次執行（DELETE .../actions/runs/{run_id}，需要寫入權限）會連同它的成品一起刪除；只想保留日誌、清掉成品時，改刪個別成品。

來源：REST: artifacts（GH200-DOC-20）、REST: workflow runs（GH200-DOC-22）、Use workflow run logs（GH200-DOC-15）、Remove workflow artifacts（GH200-DOC-11）、Store and share data（GH200-DOC-12）；2026-11-03 以頁面原文比對。gh 指令中下載成品的子指令，本節沒有核對。

D2-O3 使用與管理工作流程範本

三種重用機制，三種用法

• 可重用工作流程的 job 自己指定機器類型；複合 action 跑在呼叫 job 的機器上。步驟需要不同機器時，用可重用工作流程。
• 可重用工作流程的 job 與步驟會分開、即時記錄；複合 action 在呼叫端日誌中只是一個步驟。
• 被重用的工作流程會出現在 repository 的相依性圖（dependency graph）中。
• 官方 Study Guide 的描述是：起始工作流程是「複製的鷹架，建立後就獨立」；可重用工作流程是「集中維護、有版本的定義，以 workflow_call 呼叫」；複合 action 是「封裝的步驟邏輯」。

使用起始工作流程

1. repository 的 Actions 頁籤 → New workflow（已有工作流程時）。
2. 在 Choose a workflow 搜尋關鍵字或依分類篩選；頁面會推薦工作流程範本。
3. 對想用的範本按 Configure；若註解寫了額外設定就先照做；範本用到的 secrets 要存成 repository secrets。
4. 視需要修改（例如 on），按 Start commit，選擇直接提交到預設分支或開 PR。

組織的起始工作流程（給組織成員挑選）

• 在組織建立名為 .github 的 repository，把範本放在 workflow-templates 目錄。
• 每個範本需要兩個檔案：工作流程檔（例如 octo-organization-ci.yml）與同名、副檔名為 .properties.json 的中繼資料檔。
• .properties.json 的欄位：name（必填）、description（必填）、iconName（選填，目錄中的 SVG 檔名不含副檔名，或寫成 octicon <圖示名稱>）、categories（選填）、filePatterns（選填，正規表示式；使用者 repository 根目錄有符合的檔案時，範本才會出現）。
• 工作流程檔內用 $default-branch 代表 repository 的預設分支，建立工作流程時會被換成實際的分支名。
• 私有（非公開）組織範本的可見範圍（官方 Study Guide 有列這一項）：我沒有在所讀頁面找到對公開與私有 repository 可見性的規定，本節不下結論，請在官方頁面確認。

使用組織層級的可重用工作流程

呼叫方式是在 job 上寫 uses: 擁有者/儲存庫/.github/workflows/檔名@ref（同一 repository 用 ./.github/workflows/檔名）；ref 可以是 SHA、發佈標籤或分支，標籤與分支同名時標籤優先，用 commit SHA 最穩定也最安全。uses 的值不能使用 context 與表達式。可重用工作流程必須放在 .github/workflows，不支援子目錄。誰能存取組織內的可重用工作流程屬於領域四的治理，見該章。

停用與刪除

• 停用（Actions 頁籤 → 工作流程 → ⋯ → Disable workflow，或 gh workflow disable）：讓工作流程不再觸發，但不必刪除檔案。不會取消進行中的執行；停用期間不能重新執行那些執行或其 job，要先重新啟用（Enable workflow，或 gh workflow enable）。
• 公開 repository 在 60 天沒有活動後，排程工作流程會被自動停用；公開 repository 被 fork 時，排程工作流程預設是停用的。
• 刪除工作流程指刪除 .github/workflows 裡的檔案，與停用不同：停用保留檔案，之後可以啟用；刪檔案後工作流程不再有定義。本節沒有在所讀頁面核對到官方對「刪除工作流程」的詳細說明（例如既有執行紀錄的處理），備考前請在官方頁面確認。

判斷練習

情境 A： 平台團隊要讓全公司的 CI 邏輯集中維護，使用者的 repository 只需要幾行設定就能呼叫，且更新後各專案要能用同一個版本。

解析： 用可重用工作流程：集中維護、以 workflow_call 被 job 呼叫，並用標籤或 SHA 控制版本。起始工作流程複製後就各自獨立，無法集中更新。

情境 B： 某個複合 action 需要使用 secret，卻拿不到。

解析： secrets context 不能在複合 action 內直接使用，要把 secret 當作 input 由呼叫它的工作流程傳入。

情境 C： 團隊想暫時停止一個排程工作流程，但不想失去設定。

解析： 用 Disable workflow。檔案保留、之後可以 Enable workflow；停用不會取消進行中的執行。

來源：Reusing workflow configurations（概念）（GH200-DOC-19）、Use workflow templates（GH200-DOC-18）、Create workflow templates（GH200-DOC-21）、Reuse workflows（GH200-DOC-08）、Disable and enable workflows（GH200-DOC-17）、Study Guide（GH200-SG）；2026-11-03 以頁面原文比對本節的數字與條件。使用起始工作流程的頁面沒有說明建立後是否仍與範本連結，「建立後就獨立」一句引用自 Study Guide。