使用環境變數和成品資料自訂您的工作流程

12 分鐘

在此，您將了解如何使用預設和自訂環境變數、自訂指令碼、快取相依性，以及在工作之間傳遞成品資料。您也將了解如何從 GitHub 網站和 REST API 端點存取工作流程記錄。

預設環境變數和內容

在 GitHub Actions 工作流程內，有數個預設環境變數可供您使用，但只能在執行工作的執行器內。這些預設變數會區分大小寫，而且會參考系統及目前使用者的組態值。我們建議您使用這些預設環境變數來參考檔案系統，而不是使用硬式編碼的檔案路徑。若要使用預設的環境變數，請指定 $ 後面接著環境變數的名稱。

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

除了預設環境變數之外，您還可以使用定義的變數做為內容。內容和預設變數很類似，因為它們都能提供環境資訊的存取，但有一些重要的差異。雖然預設環境變數只能在執行器內使用，但內容變數可以在工作流程內的任何時間點使用。例如，內容變數可讓您在執行器執行之前，執行 if 陳述式來評估運算式。

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

此範例會使用 github.ref 內容來檢查觸發工作流程的分支。如果分支為 main，則執行器會執行，並印出「正在部署到分支 $GITHUB_REF 上的生產伺服器」。執行器中會使用預設環境變數 $GITHUB_REF 來參考分支。請注意，預設環境變數為全大寫，其中的內容變數為全小寫。

自訂環境變數

類似於使用預設環境變數，您可以在工作流程檔案中使用自訂環境變數。若要建立自訂變數，您必須在工作流程檔案使用 env 內容定義它。如果您想要在執行器內使用環境變數的值，您可以使用執行器作業系統用來讀取環境變數的一般方法。

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

工作流程中的指令碼

在上述的工作流程程式碼片段範例中，run 關鍵字只是用來列印文字的字串。由於 run 關鍵字會告知工作在執行器上執行命令，因此您可以使用 run 關鍵字來執行動作或指令碼。

jobs:
  example-job:
    steps:
      - run: npm install -g bats

在此範例中，您會使用 npm 來使用 run 關鍵詞來安裝bats軟體測試套件。您也可以以動作形式執行指令碼。您可以將指令碼儲存在存放庫中 (通常是在 .github/scripts/ 目錄中完成)，然後使用 run 關鍵字提供路徑和 shell 類型。

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash

快取動作的快取相依性

建立工作流程時，您通常會發現需要重複使用相同的輸出，或將相依性從某個執行下載到另一個執行。您不需再次下載這些相依性，而是可以快取這些相依性，讓您的工作流程執行速度更快且更有效率。這可大幅減少在工作流程中執行特定步驟所需的時間，因為 GitHub 裝載的執行器上的工作每次都會在乾淨的虛擬環境中啟動。快取相依性將有助於加速重新建立這些相依性檔案所需要的時間。

若要快取作業的相依性，請使用 GitHub 的 cache 動作。此動作會擷取依您提供的唯一索引鍵所識別的快取。當動作找到快取，就會將快取的檔案擷取到您設定的路徑。若要使用 cache 動作，您必須設定一些特定參數：

參數	描述:	必要
索引鍵	是指儲存和搜尋快取時所建立的金鑰識別碼。	Yes
路徑	是指執行器上要快取或搜尋的檔案路徑。	Yes
還原索引鍵	會包含要快取的替代現有索引鍵 (如果找不到所需的快取索引鍵)。	No

steps:
  - uses: actions/checkout@v2

  - name: Cache NPM dependencies
    uses: actions/cache@v2
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-cache-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-cache-

在上述範例中，path 設定為 ~/.npm，而 key 包含執行器的作業系統和 package-lock.json 檔案的 SHA-256 雜湊。將索引鍵前端加上識別碼 (此範例中的 npm-cache) 在您使用 restore-keys 後援且擁有多個快取時很有用。

在工作之間傳遞成品資料

類似於在工作流程內快取相依性的概念，您可以在相同工作流程內的工作之間傳遞資料。您可以使用動作 upload-artifact 和 download-artifact 來達成目的。相依於先前作業成品的作業必須等候先前的作業順利完成，才能執行。如果您有一系列的工作需要根據從先前工作上傳的成品循序執行，這會很有用。例如，job_2 會使用 needs: job_1 語法來要求 job_1。

name: Share data between jobs
on: push
jobs:
  job_1:
    name: Upload File
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello World" > file.txt
      - uses: actions/upload-artifact@v2
        with:
          name: file
          path: file.txt

  job_2:
    name: Download File
    runs-on: ubuntu-latest
    needs: job_1
    steps:
      - uses: actions/download-artifact@v2
        with:
          name: file
      - run: cat file.txt

上述範例中有兩個工作。 job_1 會將一些文字寫入檔案 file.txt 中，然後使用 actions/upload-artifact@v2 動作來上傳此成品，並儲存資料供未來於工作流程內使用。 job_2 會使用 needs: job_1 語法來要求 job_1 完成，然後使用動作 actions/download-artifact@v2 來下載該成品，接著列印 file.txt 的內容。

在工作流程中啟用步驟偵錯記錄

在某些情況下，預設工作流程記錄無法提供足夠的詳細資料，以診斷特定工作流程執行、工作或步驟失敗的原因。針對這些情況，您可以針對兩個選項 (執行和步驟) 啟用其他偵錯記錄。將需要 admin 存取存放庫的兩個存放庫秘密設定為 true，以啟用此診斷記錄：

若要啟用執行器診斷記錄，請將包含工作流程的存放庫中的 ACTIONS_RUNNER_DEBUG 密碼設定為 true。
若要啟用步驟診斷記錄，請將包含工作流程的存放庫中的 ACTIONS_STEP_DEBUG 密碼設定為 true。

從使用者介面存取工作流程記錄

當您考慮成功的自動化時，您的目標是要花最少的時間來查看自動化的部分，讓您可以專注於相關的部分。但有時候，動作的執行可能不如預期，因此您需要檢查發生了什麼。該偵錯程序可能會令人沮喪，但 GitHub 提供一個配置清楚的結構，讓您快速瀏覽工作，同時保持在目前偵錯步驟的內容。若要檢視工作流程在 GitHub 中執行的記錄，您可以遵循下列步驟：

瀏覽至存放庫中的 [動作] 索引標籤。
在左側的側邊欄中，按一下所需的工作流程。
從工作流程執行的清單中，選取所需的執行。
在 [工作] 底下，選取所需的工作。
讀取記錄輸出。

如果您在工作流程內有數個執行，您也可以在選擇工作流程後選取 [狀態] 篩選，並將其設定為 [失敗]，以只顯示該工作流程內失敗的執行。

從 REST API 存取工作流程記錄

除了使用 GitHub 來檢視記錄之外，您也可以使用 GitHub 的 REST API 來檢視工作流程執行的記錄、重新執行工作流程，或甚至取消工作流程執行。若要使用 API 來檢視工作流程執行的記錄，您必須將 GET 要求傳送至記錄端點。請記住，擁有存放庫讀取權限的任何人都可以使用此端點。如果存放庫是私人的，您必須對範圍 repo 使用存取權杖。

例如，檢視特定工作流程執行記錄的 GET 要求，將會遵循此路徑：

GET /repos/{owner}/{repo}/actions/runs/{run_id}/logs

繼續