iT邦幫忙

2021 iThome 鐵人賽

DAY 12
0
DevOps

不僅是程式碼代管平台 - Github 能做些什麼?系列 第 12

GitHub Action YAML - 語意解析與指令說明

GitHub Action 的 workflow 是以 YAML 檔案進行設定 (副檔名為 .yml 或 .yaml)。YAML 是一種 data serialisation 語言,可讀性高。YAML 以換行符號與縮排方式進行語法區隔,但相當嚴謹,多餘的空白或 Tab 是不被允許的。以上一篇使用的 simple workflow 為例,它的 YAML 檔案長相如下(我們翻譯/修改了部分註解為中文,讓您比較好閱讀):

# workflow 名稱
name: CI

# 什麼情況下觸發 workflow
on:
  # 對於 main branch 建立 Branch 與 Pull Request 時觸發 workflow 
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # 允許你從 Action 頁簽上手動執行 workflow
  workflow_dispatch:

# Job 可以循序或平行執行
jobs:
  # 這個 workflow 只有一個 job,名稱為 "build"
  build:
    # 這個 job 會執行在作業系統為 ubuntu 的 runner
    runs-on: ubuntu-latest

    # 作為 Job 的一部分,Steps 會循序執行一連串的動作
    steps:
      # 在 $GITHUB_WORKSPACE 下簽出您的存儲庫,以便您的工作可以訪問它
      - uses: actions/checkout@v2

      # 在 Runner 上使用 shell 顯示出 Hello world
      - name: Run a one-line script
        run: echo Hello, world!

      # 執行一組的指令
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

接下來,我們會對常見的語意進行說明:

name

Workflow 名稱,也是在 Action 操作頁面中,工作流程清單的顯示名稱;倘若沒有設定名稱,則會以 workflow 文件路徑+檔案名稱命名,如下圖所示:
https://ithelp.ithome.com.tw/upload/images/20210912/20091494dVSZC2HC5T.png

on

必填,觸發在 workflow 的 Event 名稱。可以以單一 Event 字串、Event 陣列、事件類型陣列 或 event configuration map 進行設定

job

預設情況下是平行(並行)執行,你可以使用 jobs.<job_id>.needs 來設定每個 Job 相依性,進而設定循序執行

step

Job 包含一系列的 Step,以循序方式執行命令、設定工作與 action。step 內不一定只能執行 action,但 action要作為 step 執行。每個步驟皆在 Runner 上執行,可以存取資料區與文件系統。

uses

選擇要執行的 Action

Action 是可以重複使用的程式碼單元(Unit of Code),可以透過 JavaScript 或 Docker Container 方式撰寫,並發布至 marketplace 提供其他人使用。您可以使用已經定義好的 Action (放置於 workflow 相同的 Repo、public repo 或已經發布的 Docker Continer Registry) 來進行重複的工作 (如:簽出儲存庫)

Action 的名稱格式相當重要,官方也建議在使用上指定版本(Git Ref, SHA, 或 Docker Tag),確保使用正確的 Action,也不會因為發布者更新版本而導致 workflow 中斷。其格式如下:
{owner}/{repo}@{ref}

範例如下
actions/heroku@main


看完上面密密麻麻的註解與語意說明,開始覺得頭痛了嗎? 別著急,YAML 檔案本身可讀性很高,只要了解每個語意代表的意思,靜下心讀完,你即可發現這個 workflow 其實在:

當 Main branch 發生建立 Branch/Pull request,會觸發 CI workflow,將儲存庫的內容簽出,並且列印出下列文字

Hello, world!
Add other actions to build,
test, and deploy your project.

而這個 Workflow 執行在 ubuntu 的 runner,允許手動執行;執行內容有一個 Job,依序執行 3 個 Step:

  1. 簽出 Repo 內容 (使用 actions/checkout@v2 這個 action)
  2. 印出文字
  3. 印出文字

閱讀完本篇文章,相信你已經擁有閱讀 YAML 且大致理解 workflow 想要做什麼事情的基本能力。若有遇到不能理解的語法,可以參考本篇文章最下面的參考資料(GitHub Docs),也能快速融會貫通其功能。在下一篇文章,我們會針對 Event 做更詳細的介紹。

若喜歡我的文章,歡迎點 like、分享與訂閱,謝謝


參考資料

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
https://docs.github.com/en/actions/creating-actions/about-actions


上一篇
GitHub Actions 基本介紹 - 開始自動化 workflow 的第一步
下一篇
GitHub Event - 觸發 workflow 重要設定
系列文
不僅是程式碼代管平台 - Github 能做些什麼?30

尚未有邦友留言

立即登入留言