建立自訂的 GitHub 動作

8 分鐘

GitHub Actions 是強大的功能，協助您從程式碼到雲端，全都輕鬆自信地來自自有存放庫。您會在此了解不同類型的 GitHub 動作，以及用來建立自訂動作的中繼資料、語法和工作流程命令。

GitHub 動作類型

顯示三種 GitHub Actions 類型的圖表：Docker、JavaScript 和複合執行步驟動作。

動作是可用以自訂開發工作流程的個別工作。您可以透過撰寫與存放庫互動的自訂程式碼以執行自訂工作，或使用 GitHub 社群共用的動作來建立自己的動作。瀏覽各種動作後，您會發現三種不同類型的動作：Docker 容器動作、JavaScript 動作和複合執行步驟動作。讓我們進一步了解每種動作類型。

Docker 容器動作

Docker 容器會用 GitHub Actions 程式碼封裝環境。這表示該動作會在一致且可靠的環境中執行，因為其所有相依性都在該容器內。如果動作需要在特定環境設定中執行，則 Docker 容器會是很好的做法，因為您可以自訂作業系統和工具。缺點是因為作業必須建立並擷取容器，所以 Docker 容器動作通常會比 JavaScript 動作慢。

建立 Docker 容器動作之前，請先了解環境變數和 Docker 容器檔案系統的基本使用方法。建立 Docker 容器動作所需採取的步驟簡單直接：

建立 Dockerfile，定義組合 Docker 映像的命令。
建立 action.yml 中繼資料檔案，定義動作的輸入和輸出。將檔案中的 runs: using: 值設為 docker，runs: image: 值設為 Dockerfile。
建立 entrypoint.sh 檔案以描述 Docker 映像。
使用下列檔案來認可動作，並將其推送至 GitHub：action.yml、entrypoint.sh、Dockerfile 和 README.md。

JavaScript 動作

JavaScript 動作可以直接在執行器電腦上執行，並隔開動作程式碼與執行動作所用的環境。因此會簡化動作程式碼，且執行速度會比 Docker 容器內的動作快。

您必須下載 Node.js，包括 npm，才能建立及使用封裝的 JavaScript 動作。 GitHub Actions 工具組 Node.js 為選擇性步驟，但建議使用，因為這個 Node.js 套件集合可讓您快速建立一致性更高的 JavaScript 動作。

建立 JavaScript 動作所需採取的步驟簡單且直接：

建立 action.yml 中繼資料檔案，定義動作的輸入和輸出，以及通知動作執行器如何開始執行此 JavaScript 動作。
建立 index.js 檔案，包含工具組套件、路由和其他動作函式的相關內容資訊。
使用下列檔案認可動作，並將其推送至 GitHub：action.yml、index.js、node_modules、package.json、package-lock.json 和 README.md。

複合執行步驟動作

複合執行步驟動作可讓您利用 Shell 指令碼重複使用動作。您甚至可以在相同的動作中混合多個 Shell 語言。如果您有自動化數個工作的許多 Shell 指令碼，現可將其輕鬆轉換成動作，並針對不同的工作流程重複使用。撰寫 Shell 指令碼有時候比使用 JavaScript 或將程式碼包裝在 Docker 容器中更容易。

建立動作所需的中繼資料和語法

建立或檢查 GitHub 動作時，最理想的第一個步驟是檢查 action.yml 檔案，評估該動作需要哪些輸入、輸出、描述、執行和其他設定資訊。這些參數有些為必要，有些則為選擇性。 action.yml 檔案會定義動作的下列資訊：

參數	描述:	必要
名稱	動作的名稱。有助於以視覺化方式識別作業中的動作。	是
描述	動作功能的摘要。	是
輸入	輸入參數可讓您指定動作預期在執行階段使用的資料。這些參數會成為執行器中的環境變數。	否
輸出	輸出參數可讓您指定當後續動作執行定義這些輸出的動作之後，稍後可在工作流程中使用的資料。	否
執行	執行動作時要執行的命令。	是
商標	用來建立徽章的色彩與羽毛圖示，可在 GitHub Marketplace 中個人化並區別動作。	否

輸入

輸入參數可讓您指定動作預期在執行階段使用的資料。 GitHub 會將這些輸入參數儲存為環境變數。

以下是動作的輸入清單範例。 firstNameStudent 輸入為選擇性，studentGrade 輸入則為必要。

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

輸出

輸出參數可讓您宣告資料。請記住，稍後在工作流程中執行的動作，可以使用前面所執行動作中宣告過的輸出資料。

以下範例是宣告學生平均成績的簡單輸出：

outputs:
  average:
    description: 'The average grade of the students'

執行

如先前所學到的，動作必須有定義執行動作所需命令的 runs 陳述式。根據您建立動作的方式，無論是使用 Docker 容器、JavaScript 還是複合執行步驟，runs 語法的定義方式都不一樣。

`runs` 用於 Docker 動作時

Docker 容器動作需要 runs 陳述式才能使用下列引數設定 Docker 動作所使用的映像：

using：必須設為 docker 才能執行 Docker 容器動作
image：作為執行動作容器的 Docker 映像

runs:
  using: 'docker'
  image: 'Dockerfile'

`runs` 用於 JavaScript 動作時

JavaScript 動作需要 runs 陳述式採用下列兩個引數：

using：用以執行程式碼的應用程式，如 main 中所定義
main：包含動作程式碼的檔案；在 using 中所定義的應用程式會執行此檔案

例如，以下是使用 Node.js 其 JavaScript 動作的 runs 陳述式：

runs:
  using: 'node12'
  main: 'main.js'

`runs` 用於複合執行步驟動作時

複合執行步驟動作需要 runs 陳述式採用下列三個引數：

using：必須設為 "composite" 才能執行複合執行步驟
steps：執行動作的執行步驟
steps[*].run：您要執行的命令 (可以是動作存放庫中的內嵌或指令碼)

例如，以下是將在檔案路徑 /test/script/sh 執行指令碼其複合執行步驟動作的 runs 陳述式：

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

商標

自訂動作徽章是一個選擇性但很有意思的功能。在 GitHub Marketplace 中，徽章會顯示在動作名稱旁邊。您可以使用色彩和羽毛圖示建立徽章。針對商標，您必須指定所要使用的圖示和色彩。

branding:
  icon: 'shield'  
  color: 'blue'

下例為 GitHub Marketplace 的結帳動作徽章：

GitHub Marketplace 中顯示動作商標的螢幕擷取畫面。

工作流程命令

只要可為步驟找到正確的動作，建立工作流程就相當簡單。在某些情況下，您可能需要建立自己的動作以達成所需結果，但您可以使用工作流程命令在工作流程中新增另一個層級的自訂。

工作流程命令可讓您將格式化的文字行列印到主控台，藉此與 GitHub Actions 執行器機器進行通訊。您可以將這些工作流程命令搭配 Shell 命令使用或用在自訂動作中。工作流程命令很有用，因為其可讓您在工作流程步驟間共用資訊、將偵錯或錯誤訊息列印至主控台、設定環境變數、設定輸出參數，或將輸出參數新增至系統路徑。

大部分工作流程命令會使用下列特定格式的 echo 命令，有些則是透過寫入檔案叫用：

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

以下是一些基本的訊息記錄範例，可將偵錯訊息、資訊訊息、錯誤訊息或警告訊息列印至主控台：

- name: workflow commands logging messages
  run: |
    echo "::debug::This is a debug message"
    echo "This is an info message"
    echo "::error::This is an error message"
    echo "::warning::This is a warning message"

您也可以建立要列印至記錄檔的訊息，內容為發生錯誤的檔案名稱 (file)、行號 (line) 及資料行號 (col)。警告訊息會顯示為黃色的醒目提示文字 "warning"，錯誤訊息則會顯示為紅色的醒目提示文字 "error"。

echo "::error file=app.js,line=10,col=15::Something went wrong"

請務必注意，這些工作流程命令都必須單獨一行。會干擾剖析的字元 (例如逗號和分行符號) 都必須為 URL 編碼。

例如，下方文字是多行訊息：

This text spans
across multiple lines

此訊息應以下列方式編碼：

This text spans%0Aacross multiple lines

除了工作流程命令之外，您還可以設定結束代碼來設定動作的狀態。這一點很重要，因為當處理工作流程的工作時，失敗的結束代碼會中止所有並行動作，並取消任何未來的動作。如果要建立 JavaScript 動作，您可以使用動作工具組 @actions/core 套件來記錄訊息並設定失敗結束代碼。如果要建立 Docker 容器動作，您可以在 entrypoint.sh 指令碼中設定失敗結束代碼。