探索 GitHub 中的內容和表達式

已完成

上下文是存取有關工作流程執行、變數、執行環境、作業和步驟信息的一種方法。 每個內容都是包含屬性的物件,可以是字串或其他物件。

您可以使用表示式語法來存取內容。 表達式可以是常值、內容參考或函式的任何組合。 您可以使用運算子來結合常值、內容參考和函式。

上下文

建立工作流程和動作時,您應該一律考慮您的程式代碼是否可能執行來自可能攻擊者的不受信任輸入。 某些內容應該被視為不受信任的輸入,因為攻擊者可能會插入自己的惡意內容。 如需詳細資訊,請造訪 GitHub Actions 的安全性強化。」

下表包含 GitHub 中可用的內容範例,這不是完整的清單。

內容名稱 類型 描述
github object 工作流程執行的相關資訊。
env object 包含工作流程、作業或步驟中設定的變數。
vars object 包含存放庫、組織或環境層級所設定的變數。
job object 目前執行中作業的相關資訊。

提示

如需上下文的完整清單,請瀏覽 關於上下文。

判斷何時使用上下文

GitHub Actions 包含兩個變數集合,稱為 預設變數 和 內容。 這些變數適用於工作流程中的不同點:

  • 預設環境變數:這些環境變數只存在於執行作業的執行器上。
  • 內容:您可以在工作流程中的任何時間點使用大部分內容,包括何時無法使用預設變數。

在下列範例中,if 語句會檢查 github.ref 內容,以判斷目前的分支名稱。 系統會處理 if 檢查,且只有在結果為 true 時,才會將工作傳送給執行器。 將作業傳送至執行器之後,就會執行步驟,並參考執行器中的 $GITHUB_REF 變數。

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 Actions 中可用的情境

下表包含可用的最上層內容、簡短描述,以及物件屬性詳細信息的連結。

最上層內容 描述 屬性和範例
github 工作流程中任何作業或步驟中可用的最高層級的上下文。 github 內容的屬性。
env 包含工作流程、作業或步驟中設定的變數。 它不包含執行器進程繼承的變數。 env 內容的屬性。
vars 包含組織、存放庫和環境層級所設定的自定義組態變數。 vars 使用方式的範例。
job 包含目前執行中作業的相關資訊。 job 內容的屬性。
jobs 僅適用於可重複使用的工作流程,而且只能用來設定可重複使用工作流程的輸出。 jobs 內容的屬性。
steps 包含目前作業中已指定 id 之已完成步驟的相關資訊。 steps 內容的屬性。
runner 包含執行目前作業的執行器相關信息。 runner 內容的屬性。
secrets 包含工作流程執行可用祕密的名稱和值。 secrets 內容的屬性。
strategy 包含目前作業之矩陣執行策略的相關信息。 strategy 內容的屬性。
matrix 包含套用至目前作業之工作流程檔案中定義的矩陣屬性。 matrix 內容的屬性。
needs 包含定義為目前作業直接相依性的所有作業輸出。 matrix 內容的屬性。
inputs 包含傳遞至動作、可重複使用工作流程或手動觸發工作流程的輸入屬性。 inputs 內容的屬性。

運算式

您可以使用表達式,以程序設計方式在工作流程檔案中設定環境變數,以及存取內容。 表達式可以是常值、內容參考或函式的任何組合。 您可以使用運算子來結合常值、內容參考和函式。

表達式通常會與工作流程檔案中的條件式 if 關鍵詞搭配使用,以判斷是否應該執行步驟。 當 if 的條件為 true時,步驟將會執行。

您必須使用特定語法 ${{ <expression> }},告訴 GitHub 評估表示式,而不是將它視為字串。 此規則的例外狀況是當您在 if 子句中使用表示式時,通常可以省略這些表示式 ${{ 和 }}。

下列程式代碼範例顯示設定環境變數。

env:
  MY_ENV_VAR: ${{ <expression> }}

常值

在表達式中,您可以使用 boolean、null、number或 string 數據類型。 在條件式中,假值(false、0、-0、""、''、null)強制 false,而真理(true 和其他非假值)則強制 true。 下列顯示實作常值的範例。

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99e-2 }}
  myString: Mona the Octocat
  myStringInBraces: ${{ 'It''s open source!' }}

運營商

運算符在評估表達式方面扮演了重要角色。 表達式可以包含常值、內容參考或函式。 運算子可讓您結合這些元素來建立更複雜的表達式。 以下是一些主要運算符:

  • 邏輯運算子:

    • && (和): 結合兩個條件,這兩個條件必須皆為 true,才能讓整體運算式判斷為 true。
    • || (或): 結合兩個條件,如果任一條件為 true,則表達式會評估為 true。
    • ! (非):否定條件,並翻轉其真值。
  • 等號比較運算子:

    • == (equal):比較兩個值是否相等。
    • != (不相等):檢查兩個值是否不相等。
  • 比較運算子:

    • < (小於)
    • > (大於)
    • <= (小於或等於)
    • >= (大於或等於)

這些運算符可讓您藉由判斷應根據條件執行特定步驟的時機,來建立動態工作流程。 請記得針對表達式使用正確的語法,例如 $\{\{ <expression> \}\}$,以確保適當的評估。

如需運算子的詳細資訊,請造訪運算子。