跳至主要内容

GitHub Actions - 基本建構塊與組件

Key Components: Workflows, Jobs, Steps & More​

Workflow > Job > Step​

Workflow​

一個 Workflow 包含一個以上的 Job。
Workflow 可以手動執行，也可以藉由事件觸發自動執行。

Job​

Job 用以定義 Runner（執行環境）
一個 Job 包含一個以上的 Step。在預設情況下，Job 採平行執行，但也可更改為按順序執行。
Job 也可根據事先設定的條件決定執行與否。

Step​

Step 用以執行 action（shell script） 開發者可以自訂 Action，也可使用第三方編寫的 Action。 Step 依照順序執行，且可以設定執行條件。

Creating a First Workflow​

在未曾建立 Workflow 的 GitHub 儲存庫首頁，點擊畫面上方工具列的 action，
然後可以選擇適合的 Workflow 樣版，並以此為基礎編寫 Workflow。
編輯介面的上方有 Workflow 在專案的儲存路徑及檔案名稱。
通常不會更改儲存路徑，檔案名稱則可自由變更。 決定 Workflow 檔案名稱後，可參考以下範例編寫：

first-workflow.yml
# 為 Workflow 命名
name: First Workflow

# 將 Workflow 的執行條件設定為手動執行
on: workflow_dispatch

# 定義 jobs，注意必須是複數形。
jobs: 
    # 定義 job 名稱，非關鍵詞。
    first-job: 
        # 定義 job 的執行環境（runner）
        runs-on: ubuntu-latest
        # 定義 steps，注意必須是複數形。
        steps: 
            - name: Print greeting
              run: echo "Hello World!"
            - name: Print goodbye
              run: echo "Done - bye!"
GitHub Actions 官方文件

About GitHub-hosted runners

Running the First Workflow​

在 GitHub 線上編輯 Workflow 後，可點擊畫面右側的 Commit changes...

Running Multi-Line Shell Commands​

若需要執行多行 Shell 指令，可在指令的上一行結尾添增 pipe symbol，範例如下。

run: |
    echo "First output"
    echo "Second output"

A New Workflow & The "push" Event​

除了在 GitHub 介面建立 Workflow，也可在本地專案資料夾內建立 Workflow 再上傳至遠端。 此時必須在專案根目錄建立專屬目錄及檔案。

終端機指令
mkdir .github
mkdir .github/workflows
touch .github/workflows/fileName.yml

編寫 Workfile​

Workflow Triggers (Events)​

在 GitHub Actions 有許多事件可觸發 Workflow，事件大致分為兩類，
一類與 GitHub 儲存庫相關，另一類則與儲存庫無關。
下圖是一些常用的事件，詳情則可參考圖片下的官方文件連結。 Workflow Triggers

GitHub Actions 官方文件

Events that trigger workflows

Using Actions In Workflows​

Action 可以是 Shell Command，也可以是自己或第三方編寫的應用程式，
後者可在 GitHub Marketplace 搜尋並檢視其使用說明。 Checkout 即是一個常用的第三方 Action。

Checking Out Code In Workflows​

Shell Command 以關鍵詞 run 執行，Action 應用程式則以關鍵詞 uses 執行。

# run Shell Command
run: echo "Hellow"

# uses Action
uses: actions/someApplication@Version

Configuring Actions​

程式語言需要有對應的執行環境才能運行，在 Workflow 當中也不例外。
如果 Job Runner 未預先安裝專案所需的執行環境，就要在 steps 當中編寫安裝執行環境的代碼。
以前述範例「first-workflow.yml」為例，由於檔案中指定以 ubuntu（runs-on: ubuntu-latest）為伺服器，
而 ubuntu-latest 有預先安裝 Node.js，因此不需安裝 Node.js。
若需要安裝執行環境，可在 steps 之下編寫以下代碼。

      - name: Install NodeJS
        uses: actions/setup-node@v3
        with:
          node-version: 18
參考文件

Supported runners and hardware resources
actions/setup-node

Jobs: In Parallel vs Sequential​

在 job 名稱與 runs-on 之間編寫「needs: previousJobName」，
如此該 job 會在指定的 previous job 完成後才執行，而非與其他 job 平行執行。

Jobs in sequential 範例
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      # Write step detail
  job2:
    needs: jobName
    runs-on: ubuntu-latest

Using Multiple Triggers (Events)​

Workflow 中的 on 可加入多個描述，如此可使 Workflow 因多種事件而執行。

name: My Workflow
on: [push, workflow_dispatch, ...]

Expressions & Context Objects​

利用 Workflow 執行 Shell Command 時，可以利用 echo ${{}} 印出 Context Object。
下列範例代碼中，toJSON() 是 Expression，用以將輸出結果轉為易讀的 JSON 格式。 Context Object 及 Expression 的詳細說明可參考代碼下的官方文件。

GitHub Actions Context Objects & Expressions 範例代碼
        steps:
            - name: Output GitHub context
              run: echo "${{toJSON(github)}}"
GitHub Actions 官方文件

Contexts - GitHub Docs
Expressions - GitHub Docs