使用環境變數自定義您的工作流程

已完成

在本單元中，您將瞭解如何使用 GitHub Actions 工作流程中的變數、內容和自定義腳本來設定和管理環境特定行為。

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

• 使用預設和自定義環境變數。
• 存取工作流程中的情境資訊。
• 在不同的工作流程範圍設定環境變數。
• 搭配執行關鍵字使用自訂指令碼。
• 運用環境保護措施於部署中。

預設環境變數和內容

在 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 來參考該分支。 請注意，預設環境變數為全大寫，其中的內容變數為全小寫。

工作流程中可用的背景資訊

使用內容來存取工作流程執行、變數、執行器環境、作業和步驟的相關信息。 每個上下文都是物件，其中包含可以是其他物件或字串的屬性。 可用的內容包括github、env、vars、job、jobs、steps、runner、secrets、strategy、matrix、needs和inputs。

下表列出工作流程內容和描述：

上下文	說明
github	工作流程執行的相關資訊。 如需詳細資訊，請參閱 github 內容。
env	包含您在工作流程、作業或步驟中設定的變數。 如需詳細資訊，請參閱 env 內容。
vars	包含您在存放庫、組織或環境層級設定的變數。 如需詳細資訊，請參閱 vars 內容。
job	目前執行中作業的相關資訊。 如需詳細資訊，請參閱 job 內容。
jobs	僅適用於可重複使用的工作流程，包含可重複使用工作流程的作業輸出。 如需詳細資訊，請參閱 jobs 內容。
steps	目前作業中所執行步驟的相關資訊。 如需詳細資訊，請參閱 steps 內容。
runner	執行目前作業之執行器的相關資訊。 如需詳細資訊，請參閱 runner 內容。
secrets	包含工作流程執行可用祕密的名稱和值。 如需詳細資訊，請參閱 secrets 內容。
strategy	目前作業之矩陣執行策略的相關信息。 如需詳細資訊，請參閱 strategy 內容。
matrix	包含套用至目前作業之工作流程中定義的矩陣屬性。 如需詳細資訊，請參閱 matrix 內容。
needs	包含定義為目前作業相依性的所有作業輸出。 如需詳細資訊，請參閱 needs 內容。
inputs	包含可重複使用或手動觸發之工作流程的輸入。 如需詳細資訊，請參閱 inputs 內容。

工作流程執行中的不同時間會提供不同的內容。 例如，您只能在作業的特定位置使用 secrets 內容。 此外，您可以只在特定位置使用某些函式，例如 hashFiles 函式。

下表列出工作流程中每個內容和特殊函式的限制。 列出的情境僅適用於指定的工作流程鍵。 您無法在其他地方使用它們。 除非函式列在下表中，否則您可以在任何位置使用函式。

工作流程關鍵要素	上下文	特殊功能
run-name	github、inputs、vars	沒有
concurrency	github、inputs、vars	沒有
env	github、secrets、inputs、vars	沒有
jobs.<job_id>.concurrency	github、needs、strategy、matrix、inputs、vars	沒有
jobs.<job_id>.container	github、needs、strategy、matrix、vars、inputs	沒有
jobs.<job_id>.container.credentials	github、needs、strategy、matrix、env、vars、secrets、inputs	沒有
jobs.<job_id>.container.env.<env_id>	github、needs、strategy、matrix、job、runner、env、vars、secrets、inputs	沒有
jobs.<job_id>.container.image	github、needs、strategy、matrix、vars、inputs	沒有
jobs.<job_id>.continue-on-error	github、needs、strategy、vars、matrix、inputs	沒有
jobs.<job_id>.defaults.run	github、needs、strategy、matrix、env、vars、inputs	沒有
jobs.<job_id>.env	github、needs、strategy、matrix、vars、secrets、inputs	沒有
jobs.<job_id>.environment	github、needs、strategy、matrix、vars、inputs	沒有
jobs.<job_id>.environment.url	github、needs、strategy、matrix、job、runner、env、vars、steps、inputs	沒有
jobs.<job_id>.if	github、needs、vars、inputs	always、canceled、success、failure
jobs.<job_id>.name	github、needs、strategy、matrix、vars、inputs	沒有
jobs.<job_id>.outputs.<output_id>	github、needs、strategy、matrix、job、runner、env、vars、secrets、steps、inputs	沒有
jobs.<job_id>.runs-on	github、needs、strategy、matrix、vars、inputs	沒有
jobs.<job_id>.secrets.<secrets_id>	github、needs、strategy、matrix、secrets、inputs、vars	沒有
jobs.<job_id>.services	github、needs、strategy、matrix、vars、inputs	沒有
jobs.<job_id>.services.<service_id>.credentials	github、needs、strategy、matrix、env、vars、secrets、inputs	沒有
jobs.<job_id>.services.<service_id>.env.<env_id>	github、needs、strategy、matrix、job、runner、env、vars、secrets、inputs	沒有
jobs.<job_id>.steps.continue-on-error	github、needs、strategy、matrix、job、runner、env、vars、secrets、steps、inputs	hashFiles
jobs.<job_id>.steps.env	github、needs、strategy、matrix、job、runner、env、vars、secrets、steps、inputs	hashFiles
jobs.<job_id>.steps.if	github、needs、strategy、matrix、job、runner、env、vars、steps、inputs	always、canceled、success、failure、hashFiles
jobs.<job_id>.steps.name	github、needs、strategy、matrix、job、runner、env、vars、secrets、steps、inputs	hashFiles
jobs.<job_id>.steps.run	github、needs、strategy、matrix、job、runner、env、vars、secrets、steps、inputs	hashFiles
jobs.<job_id>.steps.timeout-minutes	github、needs、strategy、matrix、job、runner、env、vars、secrets、steps、inputs	hashFiles
jobs.<job_id>.steps.with	github、needs、strategy、matrix、、jobrunner、env、vars、、secrets、、、 stepsinputs	hashFiles
jobs.<job_id>.steps.working-directory	github、needs、strategy、matrix、、jobrunner、env、vars、、secrets、、、 stepsinputs	hashFiles
jobs.<job_id>.strategy	github、需求、vars、inputs	沒有
jobs.<job_id>.timeout-minutes	github、needs、strategy、matrix、vars、inputs	沒有
jobs.<job_id>.with.<with_id>	github、needs、strategy、matrix、inputs、vars	沒有
on.workflow_call.inputs.<inputs_id>.default	github、inputs、vars	沒有
on.workflow_call.outputs.<output_id>.value	github、作業、vars、inputs	沒有

自訂環境變數

類似於使用預設環境變數，您可以在工作流程檔案中使用自訂環境變數。 若要建立自訂變數，您必須在工作流程檔案使用 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

在工作流程中設定自定義環境變數

您可以使用工作流程檔案的最上層，定義限定於整個工作流程 env 範圍的環境變數。 使用 jobs.<job_id>.env來限定工作流程中作業的內容。 您可以在作業中的特定步驟使用 jobs.<job_id>.steps[*].env 來設定環境變數的範圍。

以下是顯示工作流程檔案中這三個案例的範例：

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

在工作流程中使用預設內容

GitHub 平台會設定預設環境變數。 它們未定義於工作流程中，但您可以在適當的內容中使用工作流程中的默認環境變數。 除了 CI 以外，大部分變數的開頭為 GITHUB_* 或 RUNNER_*。 無法覆寫後兩種類型。 此外，這些預設變數具有對應的和類似名稱的內容屬性。 例如，一 RUNNER_* 系列的預設變數具有 相符的內容屬性 runner.*。

以下是如何藉由套用下列方法存取工作流程中預設變數的範例：

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

如需詳細資訊，請參閱 默認環境變數。

將自定義環境變數傳遞至工作流程

您可以將自定義環境變數從工作流程作業的一個步驟傳遞至作業內的後續步驟。 在作業的一個步驟中產生值，並將值指派給現有的或新的環境變數。 接下來，您會將變數/值組寫入GITHUB_ENV環境檔案。 您可以使用 run 關鍵字，在動作或從工作流程作業中的殼層命令中使用環境檔案。

建立或更新環境變數的步驟無法存取新值，但作業中的所有後續步驟都具有存取權。

以下為範例：

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

新增環境保護

您可以為 GitHub 存放庫定義的環境新增保護規則。

若要在存放庫中新增環境：

1. 選擇 [設定]。

   

2. 在左窗格中，選取 [ 環境]。

   

3. 選取 [ 新增環境] 按鈕以新增及設定環境並新增保護。

   

關於環境

使用環境來描述一般部署目標，例如生產、預備或開發。 當 GitHub Actions 工作流程部署到環境時，環境會出現在存放庫的主頁面上。 您可以使用環境來要求核准作業才能繼續、限制哪些分支可以觸發工作流程、使用自定義部署保護規則來網關部署，或限制對秘密的存取。

工作流程中的每個作業都可以參考一個環境。 您為環境設定的任何保護規則，都必須在參考環境的作業傳送至執行器之前通過。 只有在作業傳送至執行器之後，作業才能存取環境的祕密。

當工作流程參考環境時，環境會出現在存放庫的部署中。

環境保護規則

環境部署保護規則要求在引用環境的作業繼續之前必須滿足特定條件。 您可以使用部署保護規則來要求手動核准、延遲作業，或將環境限制為特定分支。 您也可以建立及實作 GitHub Apps 所提供的自定義保護規則，以使用合作夥伴系統來控制參考 GitHub 上設定環境的部署。

以下是這些保護規則的說明：

• 必需的檢閱者保護規則。 使用此規則來強制要求特定人員或團隊核准涉及環境的工作流程任務。 您最多可以列出六個使用者或小組作為檢閱者。 檢閱者必須至少有存放庫的讀取許可權。 只有指定的審核者核准作業後，作業才能繼續進行。

  您也可以避免對受保護環境的部署進行自我審查。 如果啟用此設定，則起始部署的用戶無法核准部署作業，即使他們是必要的檢閱者也一樣。 藉由啟用自我檢閱，可確保有一個以上的人員檢閱受保護環境的部署。

  如需檢閱參考具有必要檢閱者之環境的作業詳細資訊，請參閱檢閱部署。

• 等候計時器投影規則。 您可以使用等候計時器保護規則，在環境部署繼續進行之前，先觸發作業一段時間，再延遲作業。 時間（以分鐘為單位）必須是介於 1 到 43,200 （30 天） 之間的整數。 等候時間不會計入您的計費時間。

• 分支和標記保護規則。 您可以使用部署分支和標記保護規則來限制用來部署至環境的分支和標籤。 您有數個選項可用於部署分支，以及環境的標記保護規則。

  • 沒有任何限制 表示任何分支或標籤都可以部署至環境。
  • 受保護的分支只 允許已啟用分支保護規則的分支部署至環境。 如果未針對存放庫中的任何分支定義任何分支保護規則，則所有分支都可以部署。 [選取的分支和標籤] 設定可確保只有符合您指定名稱模式的分支和標籤可以部署到環境。
  • 如果您指定 releases/* 為部署分支或標記規則，則只有開頭為 的 releases/ 分支或標籤可以部署到環境。 (萬用字元不符合 /。若要比對開頭為 release/ 的分支或標籤，並包含另一個單斜線，請使用 release/*/*。)如果您新增 main 為分支規則，名為 main 的分支也可以部署到環境。

• 自訂部署保護規則。 您可以建立自訂保護規則來管理部署以便使用合作夥伴服務。 例如，您可以使用可檢視性系統、變更管理系統、程式代碼質量系統，或用來評估整備程度的其他手動設定，並提供自動化核准以部署至 GitHub。

  建立自訂部署保護規則並在存放庫上安裝它們之後，您可以針對存放庫中的任何環境啟用自定義部署保護規則。

  

備註

如果您有 GitHub Free、GitHub Pro 或 GitHub Team 方案，則環境部署投影規則僅適用於公用存放庫;分支和標記保護規則除外。 對於擁有 GitHub Pro 或 GitHub Team 方案的使用者，私人存放庫也提供分支和標籤保護規則。

工作流程中的指令碼

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

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

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

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