GH-200 名詞庫

D1 撰寫與管理工作流程

schedule: 以 cron 設定的定時觸發，只在預設分支的檔案上執行；最短間隔每 5 分鐘，高負載時可能延遲，公開 repository 60 天無活動會停用。
workflow_dispatch: 手動觸發，可定義 inputs；只在預設分支的檔案上可用，最多 25 個頂層 input、資料量不超過 65,535 個字元。
workflow_call: 讓工作流程可被其他工作流程呼叫的事件，在 inputs 與 secrets 底下宣告可接受的參數。
repository_dispatch: 由外部以 API 送出的自訂事件；event_type 最多 100 個字元，client_payload 最多 10 個頂層屬性。
pull_request: PR 事件，預設只在 opened、synchronize、reopened 執行；GITHUB_SHA 是 PR 的合併 commit。
pull_request_target: 在基底 repository 預設分支的 context 執行的特權觸發條件，可取得 secrets；不要搭配 checkout 不受信任的 PR 程式碼。
GITHUB_SHA: 觸發執行的 commit；pull_request 是合併 commit，schedule 與 workflow_run 是預設分支的最後 commit。
GITHUB_REF: 觸發執行的 ref；pull_request 是 refs/pull/編號/merge，schedule 是預設分支。
permissions: 設定 GITHUB_TOKEN 權限，可放在工作流程或 job 層；只要明確設定其中一項，沒列出的權限都變成 none。
inputs context: 保留 boolean 型別的輸入值 context，可直接用在條件。
github.event.inputs: 舊式輸入值 context，會把 boolean 轉成字串，所以與 false 比較永遠不成立。
needs: 建立 job 相依；被需要的 job 失敗或略過時，依賴它的 job 也會被略過。
always(): 狀態檢查函式，用在 job 的 if 時，無論相依 job 結果如何都執行。
context 可用位置: 不同位置可用的 context 不同，例如 jobs.<id>.if 可用 github、needs、vars、inputs，不含 secrets 與 env。
vars context: 讀取組織、repository、環境層級設定變數的 context，未設定時是空字串。
steps outcome: 套用 continue-on-error 之前的步驟結果。
steps conclusion: 套用 continue-on-error 之後的步驟結果。
strategy.matrix: 依變數組合展開成多個 job；每次執行最多 256 個 job。
include: 矩陣的擴充：加進所有不衝突的原始組合，會覆寫既有值時成為獨立的新組合。
exclude: 從矩陣移除特定組合，可只寫部分欄位比對。
fail-fast: 啟用時，一個 continue-on-error 為 false 的組合失敗，所有進行中與排隊的 job 都被取消。
max-parallel: 限制同時執行的矩陣 job 數量。
服務容器 services: 在 job 內宣告的相依服務；job 在容器內用標籤當主機，直接在 runner 上用 localhost 並設定 ports。
快取鍵 key: 快取的識別；查找順序為完全相同、key 前綴、restore-keys；快取不可變，要更新就用新鍵。
restore-keys: 找不到完全相同的 key 時依序比對的備援鍵。
成品 artifact: 在 job 之間或執行之後保存的檔案；v4 不可變，預設保留 90 天。
GITHUB_ENV: 寫入後讓之後的步驟取得環境變數；寫入的那一步看不到。
GITHUB_OUTPUT: 寫入步驟輸出，步驟需有 id，用 steps.<id>.outputs 讀取。
GITHUB_STEP_SUMMARY: 寫入工作摘要的 Markdown 檔，每個步驟上限 1 MiB。

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

Search logs: 日誌頁的搜尋，只搜尋已展開的步驟。
Download log archive: 從日誌頁下載封存檔；只重跑部分 job 時，封存檔只含重跑的 job。
gh run view: 用命令列看執行日誌；--log 看整次，--log-failed 只看失敗步驟。
ACTIONS_STEP_DEBUG: 設為 true 讓步驟日誌更詳細，並顯示 ::debug:: 訊息。
ACTIONS_RUNNER_DEBUG: 設為 true 啟用 runner 診斷記錄，封存檔多出 runner-diagnostic-logs 資料夾。
Enable debug logging: 重新執行時勾選，同時啟用 runner 診斷與步驟除錯；CLI 用 --debug。
runner.debug: context，可讓步驟只在除錯記錄啟用時執行。
Re-run failed jobs: 只重跑失敗的 job；沿用原本的 GITHUB_SHA 與 GITHUB_REF。
gh run rerun: 命令列重跑；加 --failed 只重跑失敗的 job，加 --job 重跑單一 job。
重新執行的限制: 初次執行後 30 天內、最多重跑 50 次；工作流程被停用時不能重跑。
成品下載端點: REST 下載成品，archive_format 必須是 zip，回應 302 導向。
Location 網址: 下載導向的網址，只有 1 分鐘有效。
expired 與 expires_at: 成品物件的欄位，用來判斷是否已被保留期清掉。
gh run delete: 命令列刪除整次執行；刪除執行時它的成品也一併刪除。
可重用工作流程: 在 job 層級用 uses 呼叫整個工作流程檔，可用 secrets，最多 10 層，不能發佈到 Marketplace。
複合 action: 在步驟層級呼叫的一組步驟，跑在呼叫它的 job 的機器上，不能直接用 secrets。
起始工作流程: 新工作流程的起點範本，複製後就是自己的獨立檔案。
workflow-templates: 組織 .github repository 中放起始工作流程範本的目錄。
.properties.json: 範本的中繼資料檔，name 與 description 必填。
$default-branch: 範本內的佔位符，建立時被換成 repository 的預設分支名。
Disable workflow: 停用工作流程使其不再觸發；不會取消進行中的執行，停用期間不能重跑。
github.event_name: 辨認這次執行由哪個事件觸發的欄位。

D3 撰寫與維護 actions

Docker 容器 action: runs.using 為 docker，只能在 Linux runner 執行，啟動較慢。
JavaScript action: runs.using 為 node20 或 node24，可跨 Linux、macOS、Windows，啟動快。
composite（runs.using）: 把多個步驟包成一個 action，每個有 run 的步驟必須指定 shell。
action.yml: action 的中繼資料檔，也可命名為 action.yaml，定義輸入、輸出與 runs。
name、description、runs: action.yml 頂層必填的三個鍵；author 與 inputs 是選填。
main: JavaScript action 必填，指向執行的檔案，通常是打包後的 dist/index.js。
pre 與 post: JavaScript action 在 main 前後執行的檔案；pre-if 與 post-if 預設都是 always()。
@actions/core: toolkit 套件，提供輸入輸出、結束狀態與除錯訊息，例如 core.setOutput。
@actions/github: toolkit 套件，回傳已驗證的 Octokit 用戶端並可存取 context。
core.setFailed: 記錄訊息並設定失敗結束碼，讓 action 失敗。
rollup.js 與 @vercel/ncc: 把程式碼與相依套件打包成單一檔案的工具，取代提交 node_modules。
inputs 的 required: 只是標記，缺值時不會自動報錯，action 要自己檢查。
inputs 的 default: 工作流程沒提供該輸入時使用的字串。
deprecationMessage: 輸入被使用時以警告記錄的訊息。
複合 action 的 value: 複合 action 輸出必填的鍵，指向某個步驟的輸出。
github.action_path: 指向 action 所在目錄的路徑，可用來呼叫目錄內的指令碼。
branding: 選填，控制 Marketplace 的圖示與顏色。
私有 action 共用: 在私有 repository 的 Settings → Actions → General → Access 開放給其他 repository。
GitHub Marketplace 發佈: 要公開 repository、根目錄單一 action.yml、name 唯一，且帳號接受開發者協議；符合條件即立即發佈，不經 GitHub 審核。
主版本標籤: 如 v1，要指向最新且相容的 commit，使用者釘在 v1 就能取得相容更新。
immutable release: 發佈後標籤與資產不能更動；鎖定的標籤不能移動，也不能強制推送。
語意化版本: 以 v1.1.3 這類標籤建立 release，並維持主、次版本標籤。

D4 管理企業的 GitHub Actions

允許的 actions 政策: 組織可選全部啟用、停用，或限制為組織自己的加選定來源。
只允許組織自己的 actions: 會封鎖所有 GitHub 作者的 actions，包含 actions/checkout。
樣式語法: OWNER/REPO@TAG-OR-SHA；* 為萬用字元，! 開頭表示封鎖，最多 1000 個樣式。
要求固定完整 commit SHA: 適用於組織與 GitHub 作者的 actions；可重用工作流程仍可用標籤。
本機 action: 以 ./ 路徑參照的 action，不受企業或組織 Actions 政策限制。
企業政策覆蓋: 企業啟用的政策下層可選擇停用；企業停用的政策下層不能再啟用。
fork PR 核准政策: 公開 repository 的外部協作者可設需要核准；預設所有首次貢獻者需核准，pull_request_target 一律執行。
預設 GITHUB_TOKEN 權限: 新組織對 contents 與 packages 預設唯讀；企業更嚴格時組織不能選更寬鬆。
建立與核准 PR 設定: Allow GitHub Actions to create and approve pull requests，預設停用。
保留期: 預設 90 天，公開 repository 可設 1–90 天，私有與 internal 可設 1–400 天。
快取保留與容量: 預設 7 天與每個 repository 10 GB；企業可設上限。
自訂映像: 只能搭配 larger runners 使用，儲存另計入 Actions 儲存。
larger runners: 有更多核心或 GPU 的 GitHub 代管 runner，用於 Team 與 Enterprise Cloud。
靜態 IP 位址範圍: larger runners 的選用功能，需 Enterprise Cloud，macOS 不支援。
最大並行數: larger runners 同時可執行的 job 上限。
自管 runner: 自己部署與維護的 runner，job 之間狀態可能殘留，有 repository、組織、企業三種範圍。
自管 runner 連線需求: 出站 HTTPS 443、至少 70 kbps，並連到 github.com、api.github.com 等網域；使用 IP 允許清單要加入 runner 的 IP。
runner 自動更新: 預設啟用；停用後必須在新版釋出後 30 天內更新，否則 GitHub 不再排 job 給它。
暫時性 runner: 註冊時用 --ephemeral，執行一個 job 後取消註冊，日誌要轉送外部。
runner 群組: 組織有預設群組；群組預設只開放私有 repository，可覆寫。
job 如何選 runner: 標籤與群組都符合的線上閒置 runner；60 秒沒接起會重新排隊，排隊超過 24 小時失敗。
runner 狀態: Idle 為閒置、Active 為執行中、Offline 為未連線。
_diag 日誌: runner 安裝目錄中的日誌：Runner_、Worker_、SelfUpdate。
config --check: 檢查網路連線，需搭配 --url 與 --pat。
secrets 層級: 組織、repository、環境三層；同名時環境優先於 repository 與組織。
環境 secret 與審核: 啟用必要審核者時，核准前 job 拿不到環境 secret。
variables: 設定變數，用 vars context 讀取，不遮蔽，不要放機密。
secret 的限制: 不能直接用在 if；fork 與 Dependabot 觸發的工作流程拿不到；不會自動傳給可重用工作流程。
REST 設定 secret: 用 LibSodium 以公鑰加密，PUT 時帶 encrypted_value 與 key_id。
超過 48 KB 的 secret: 官方做法是用 gpg 加密檔案並把密碼存成 secret；日誌不會被遮蔽。

D5 保護與最佳化自動化

script injection: ${{ }} 在 shell 執行前被替換成文字，不受信任的值可能變成指令；用中間環境變數或改用 action 防範。
中間環境變數: 把運算式的值設成 env，指令碼內以 $NAME 引用，值不會成為指令碼語法。
環境 environment: 含保護規則、secrets 與 variables 的部署目標；job 通過規則才會執行。
必要審核者: 最多 6 個人或團隊，其中一人核准即可。
防止自我審核: 阻止使用者核准自己觸發的執行。
等待計時器: job 在環境上繼續之前的延遲，以分鐘計。
部署分支與標籤: 限制哪些分支與標籤可以部署到該環境，兩者分別設定。
管理員繞過: 預設管理員可繞過環境保護規則，可在設定中取消。
Verified creator: Marketplace 上身分已驗證的徽章，是有用訊號，但不能取代檢視原始碼。
完整 commit SHA 固定: 標籤可被移動或刪除，SHA 不會；要確認 SHA 來自原 repository 而非 fork。
lockfile: 鎖定工作流程相依項目的確切 commit，官方說對採用者取代 SHA 固定。
Dependabot 與 actions: version updates 開 PR 更新 actions；alerts 不涵蓋釘在 SHA 的 actions。
CODEOWNERS: 把 .github/workflows 加入，讓工作流程修改需指定審核者核准。
OpenSSF Scorecards: 自動標出風險做法的工具，檢查包含 script injection、權杖權限與固定版本。
GITHUB_TOKEN 生命週期: 每個 job 開始建立；代管 runner 最長 6 小時，自管 runner 最多更新到 24 小時。
GITHUB_TOKEN 與 PAT: 前者限單一 repository 且通常不觸發新執行；跨 repository 或需觸發時用 GitHub App 權杖或 PAT。
OIDC: 以短期權杖取代雲端長期憑證；雲端端必須定義信任條件。
id-token: write: 允許工作流程請求 OIDC 權杖，不給任何資源的寫入權限。
sub claim: OIDC 權杖的主體，預設如 repo:組織/儲存庫:environment:環境名稱，可用 REST 自訂。
OIDC 簽發者與受眾: 簽發者是 token.actions.githubusercontent.com；預設受眾是 repository 擁有者的網址。
artifact attestation: 對建置來源的簽章聲明，用 actions/attest 產生，需 id-token、contents、attestations 權限。
SLSA Build Level: 單獨使用證明為 Level 2；在共用可重用工作流程建置可達 Level 3。
gh attestation verify: 消費者驗證成品證明的指令，搭配 -R 組織/儲存庫。
concurrency: 同群組只同時執行一個；群組名稱不分大小寫，cancel-in-progress 取消執行中的。
queue: max: 最多 100 個等待中的執行，不能與 cancel-in-progress: true 同時使用。
job 時間上限: GitHub 代管 runner 6 小時、自管 runner 5 天；整次執行最長 35 天。
方案內含用量: 是金額而非分鐘數；標準代管 runner 在公開 repository 免費，larger runners 要計費。