在 GitHub Actions 中管理和偵錯工作流程

  • 10 分鐘

回想一下，您的目標是將程式代碼建置和發佈程式自動化，以便在開發人員每次將變更新增至程式代碼基底時更新功能。

若要實作此程式，您將瞭解如何：

  • 識別觸發工作流程的事件。
  • 使用 GitHub Actions 工作流程記錄。
  • 儲存並存取構建產物。
  • 在檢閱之後，自動將標籤新增至提取要求。

識別觸發工作流程的事件

了解觸發 GitHub Actions 工作流程的內容對於偵錯、稽核及改善 CI/CD 管線至關重要。 觸發程序的類型包括推送至分支、建立或更新的提取要求、排程的工作或手動分派。 您可以檢查工作流程執行、存放庫變更，以及相關的 GitHub 問題或提取要求，以識別觸發事件。

顯示 GitHub Actions 中各種工作流程觸發器的圖表，例如推送、提取請求、排程和手動觸發。

什麼是工作流程觸發器？

工作流程觸發程式是導致工作流程執行的事件。 GitHub 支援各種類型的觸發程式，包括：

  • push 或 pull_request （根據程式代碼變更）
  • workflow_dispatch （手動觸發）
  • schedule (Cron 工作)
  • repository_dispatch （外部系統）
  • 問題、討論和提取要求事件 (例如issues.opened，pull_request.closed)

識別觸發事件

您可以透過多種方式識別工作流程觸發程式事件：

  • 使用 GitHub Actions UI：

    1. 在您的儲存庫中，選取 [動作] 索引標籤。
    2. 選取工作流程執行。

    事件類型，例如 push、 pull_request或 workflow_dispatch，會出現在工作流程執行摘要的頂端。

  • 在記錄或工作流程中使用 github.event_name。

    • GitHub 會在工作流程執行期間公開內容數據。 變數 github.event_name 會告訴您觸發工作流程的事件。

    • 您可以在步驟中列印資訊以進行偵錯：

      -name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"

  • 使用工作流程執行詳細資料：

    • 如果您以程式設計方式檢查工作流程執行個案，例如使用 API，則執行個案物件會包含一個 event 屬性，以指定觸發條件。
    • 您可以找到提交的安全哈希演算法（SHA）、操作人員和時間戳，以追蹤造成事件觸發的原因。

從資料庫效應中推斷觸發條件

您可能沒有工作流程執行的直接存取權，但仍想要根據存放庫活動推斷觸發工作流程執行的專案：

觀察到的行為 觸發事件
新的提交已推送至 main 並執行工作流程。 push 事件
提取要求已開啟或更新。 pull_request 事件
參與者手動執行工作流程。 workflow_dispatch
工作流程會在特定時間每天執行。 schedule (Cron)
工作流程在外部服務呼叫之後執行。 repository_dispatch
當標籤或批註新增至問題時，工作流程就會執行。 issues.* 事件

藉由檢閱時間戳、拉取請求活動和提交歷程記錄，您通常可以找出導致工作流程執行的動作。

摘要說明如何識別觸發工作流程的內容：

  • 請在 動作 索引標籤上查看工作流程運行摘要。
  • 在工作流程內列印或記錄 github.event_name 以取得可見度。
  • 比較時間戳記和儲存庫活動（如提交、拉取請求、問題）來推斷觸發事件。
  • 使用完整 event 內容進行更深入的調查。

這些作法可協助您偵錯、稽核及改善整個開發和部署管線的工作流程可靠性。

藉由讀取其組態檔來瞭解工作流程效果

若要通過閱讀其組態檔了解工作流程的影響，請分析儲存在.yml中的.github/workflows/檔案的結構和內容。

工作流程組態檔會指定工作流程的下列資訊：

  • 執行時間 (在 on 區段)。
  • 它做什麼（在 jobs 和 steps中）。
  • 執行地點 (runs-on 區段)。
  • 執行原因 (其目的，例如測試、部署或 Lint 分析)。
  • 它在特定條件下的行為方式（環境、篩選條件、邏輯）。

解譯工作流程效果

  1. 識別觸發因素。

    若要識別起始工作流程的動作，請參閱 on 工作流程的 區段。

    例如：

    on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:

    此範例工作流程：

    • 當程式代碼推送至主要分支push時，會自動執行。
    • 建立或更新提取要求時執行 （pull_request）。
    • 用戶可以手動觸發 （workflow_dispatch）。

  2. 識別工作流程作業和步驟。

    若要判斷工作流程的用途，請參閱 jobs 工作流程的 和 steps 區段。

    例如：

    jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

    此範例工作流程：

    • 使用 Linux 虛擬環境 （runs-on）。
    • 檢查存放庫的程式代碼 （steps>name）。
    • 安裝專案相依項目 (steps>name)。
    • 執行自動化測試 （steps>name）。

  3. 評估工作流程的用途和結果。

    藉由讀取組態檔，您可以描述工作流程的預期結果：

    「此工作流程為持續整合 (CI) 管線。 它可確保推送至存放庫或透過提取要求提交的任何新程式代碼都會自動測試。 如果測試失敗，GitHub 工作流程 UI 會顯示此結果，以協助您維護程式碼品質。

  4. 識別或設定會影響工作流程執行方式的選擇性功能：

    • env 會設定環境變數。
    • if 只有在符合準則時，才會新增條件式邏輯來執行特定步驟。
    • timeout-minutes 或 continue-on-error 設定工作流程執行和錯誤處理。

診斷工作流程執行失敗

  1. 在您的存放庫中，前往 [動作] 索引標籤。

  2. 尋找失敗的執行（通常以紅色 X 表示）。

  3. 選取失敗的工作流程以開啟執行摘要。

  4. 在工作流程記錄中，檢閱錯誤。

    1. 在執行摘要中，展開每個工作和步驟，直到您找到代表失敗的步驟。

    2. 選取作業或步驟以檢視其記錄。

    3. 尋找：

      • 錯誤訊息
      • 堆疊追蹤
      • 出口代碼

    例如，失敗的測試可能會顯示 npm ERR! Test failed 或 exit code 1。

  5. 檢查工作流程組態檔。

    使用 檔案 .yml 來判斷：

    • 每個步驟嘗試執行什麽？
    • 如果有環境變數 （env） 或條件式 （if） 會影響執行。
    • 如果失敗是因為遺漏相依性、語法錯誤或設定錯誤的步驟所造成。

    如果步驟失敗，請檢查下列原因：

    • 上一個步驟中，相關依賴項是否已成功安裝？
    • 測試檔案是否存在並在本機通過？

常見失敗案例

下表描述常見的工作流程失敗案例：

癥狀 可能的原因
步驟失敗並傳回 command not foundl 遺漏相依性或錯誤的設定
npm install 失敗。 損毀 package-lock.json 的檔案或網路問題
測試步驟失敗 單元測試問題、遺漏組態檔或無效的測試語法
Permission denied 隨即出現。 不正確的檔案許可權或遺漏秘密

識別如何在 GitHub 中存取工作流程記錄

  1. 在您的存放庫中，前往 [動作] 索引標籤。

  2. 在工作流程清單中，選取相關的工作流程。

    例如，如果您的 .yml 檔案具有下列程式代碼，清單中會出現標題為 CI 工作流程 的連結：

    name: CI Workflow

  3. 選取特定執行。

    在顯示狀態的執行清單中，選擇您要檢查之特定執行的時間戳或提交訊息。

  4. 展開每個工作和步驟。

    執行摘要頁面會顯示在工作流程文件中定義的作業，例如建置或測試：

    1. 選取要展開的工作。
    2. 在工作內，展開個別步驟，例如「安裝相依性」或「執行測試。」

  5. 檢視記錄輸出。

    若要檢視完整的記錄輸出，包括控制台記錄、錯誤訊息和偵錯資訊，請選取工作流程步驟。 您可以複製、搜尋及下載記錄。

下表摘要說明您存取工作流程記錄所採取的步驟：

動作 目標
動作標籤頁 檢視所有工作流程記錄。
選取工作流程名稱 依工作流程篩選執行。
選取執行項目 查看特定作業和步驟結果。
展開步驟 檢視詳細記錄。
下載記錄 下載用於離線或小組合作診斷的紀錄檔案。

建構過程的操作紀錄

工作流程執行時，會產生記錄，其中包含所發生狀況的詳細數據，以及任何錯誤或測試失敗。

如果發生錯誤或測試失敗，則記錄中會出現紅色 X，而不是綠色核取記號。 您可以檢查錯誤或失敗的詳細數據，以調查所發生的情況。

GitHub Actions 記錄的螢幕快照，其中包含失敗測試的詳細數據。

使用成品

當工作流程產生非記錄項目的產物時，該產物稱為工件。 例如，Node.js 組建會產生可部署的 Docker 容器。 容器是一種成品，您可以使用 actions/upload-artifact 動作上傳至記憶體。 您稍後可以使用 actions/download-artifact 從儲存空間下載工件。

儲存成品有助於在作業之間保留該成品。 每個作業都會使用 VM 的新實例，因此您無法藉由將成品儲存在 VM 上來重複使用。 如果您需要不同作業中的成品，您可以將成品上傳至某個作業中的記憶體，並下載該成品以供另一個作業使用。

文物儲存

成品會儲存在 GitHub 上的儲存空間中。 公開存放庫的空間是免費的，而私有存放庫則視帳戶類型而有部分免費的儲存空間。 GitHub 會儲存您的成品 90 天。

在下列工作流程代碼段中，請注意，在 actions/upload-artifact@main 動作中有一個 path 屬性。 這個屬性的值是儲存成品的路徑。 在此範例中，您會指定 public/ 將所有項目上傳至目錄。 如果您只想要上傳單一檔案，請使用 公用/mytext.txt之類的專案。

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

若要下載要測試的成品，組建必須順利完成並上傳成品。 在下列程式代碼中，您會指定測試作業相依於建置作業。

test:
    needs: build
    runs-on: ubuntu-latest

在下列工作流程程式碼片段中，您會下載成品。 現在測試作業可以使用成品進行測試。

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

如需在工作流程中使用成品的詳細資訊，請參閱 將工作流程數據儲存為成品。

使用工作流程在 GitHub 中自動化審查

除了透過 GitHub 事件（例如 push 和 pull-request）啟動工作流程之外，您也可以依排程或在 GitHub 之外的某些事件後執行工作流程。

您可能只想在使用者完成特定動作之後執行工作流程，例如在檢閱者核准提取要求之後。 在這個案例中，您可以在 pull-request-review 上觸發。

您可以採取的另一個動作是將標籤新增至提取要求。 在此情況下，請使用 pullreminders/label-when-approved-action 動作。

例如：

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

在區塊中 env ，您可以設定動作的環境變數。 例如，您可以設定執行工作流程所需的核准者數目。 在此範例中，它是其中一個。 secrets.GITHUB_TOKEN需要驗證變數，因為動作必須藉由新增標籤來變更您的存放庫。 最後，您輸入要新增的標籤名稱。

新增標籤可能是啟動另一個工作流程的事件，例如合併。 我們將在下一個課程模組中討論此事件，其中說明如何在 GitHub Actions 中使用持續傳遞。