GitHub Actions 入門教程

阮一峰發表於2019-09-12
Github

這些天，我一直在試用，覺得它非常強大，有創意，比 Travis CI 玩法更多。

本文是一個簡單教程，演示如何使用 GitHub Actions 自動釋出一個 React 應用到 GitHub Pages。

一、GitHub Actions 是什麼？

大家知道，持續整合由很多操作組成，比如抓取程式碼、執行測試、登入遠端伺服器，釋出到第三方服務等等。GitHub 把這些操作就稱為 actions。

很多操作在不同專案裡面是類似的，完全可以共享。GitHub 注意到了這一點，想出了一個很妙的點子，允許開發者把每個操作寫成獨立的指令碼檔案，存放到程式碼倉庫，使得其他開發者可以引用。

如果你需要某個 action，不必自己寫複雜的指令碼，直接引用他人寫好的 action 即可，整個持續整合過程，就變成了一個 actions 的組合。這就是 GitHub Actions 最特別的地方。

GitHub 做了一個官方市場，可以搜尋到他人提交的 actions。另外，還有一個 awesome actions 的倉庫，也可以找到不少 action。

上面說了，每個 action 就是一個獨立指令碼，因此可以做成程式碼倉庫，使用userName/repoName的語法引用 action。比如，actions/setup-node就表示github.com/actions/setup-node這個倉庫，它代表一個 action，作用是安裝 Node.js。事實上，GitHub 官方的 actions 都放在 github.com/actions 裡面。

既然 actions 是程式碼倉庫，當然就有版本的概念，使用者可以引用某個具體版本的 action。下面都是合法的 action 引用，用的就是 Git 的指標概念，詳見官方文件。


actions/setup-node@74bc508 # 指向一個 commit
actions/[email protected]    # 指向一個標籤
actions/setup-node@master  # 指向一個分支

二、基本概念

GitHub Actions 有一些自己的術語。

（1）workflow （工作流程）：持續整合一次執行的過程，就是一個 workflow。

（2）job （任務）：一個 workflow 由一個或多個 jobs 構成，含義是一次持續整合的執行，可以完成多個任務。

（3）step（步驟）：每個 job 由多個 step 構成，一步步完成。

（4）action （動作）：每個 step 可以依次執行一個或多個命令（action）。

三、workflow 檔案

GitHub Actions 的配置檔案叫做 workflow 檔案，存放在程式碼倉庫的.github/workflows目錄。

workflow 檔案採用 YAML 格式，檔名可以任意取，但是字尾名統一為.yml，比如foo.yml。一個庫可以有多個 workflow 檔案。GitHub 只要發現.github/workflows目錄裡面有.yml檔案，就會自動執行該檔案。

workflow 檔案的配置欄位非常多，詳見官方文件。下面是一些基本欄位。

（1）name

name欄位是 workflow 的名稱。如果省略該欄位，預設為當前 workflow 的檔名。


name: GitHub Actions Demo

（2）on

on欄位指定觸發 workflow 的條件，通常是某些事件。


on: push

上面程式碼指定，push事件觸發 workflow。

on欄位也可以是事件的陣列。


on: [push, pull_request]

上面程式碼指定，push事件或pull_request事件都可以觸發 workflow。

完整的事件列表，請檢視官方文件。除了程式碼庫事件，GitHub Actions 也支援外部事件觸發，或者定時執行。

（3）on.<push|pull_request>.<tags|branches>

指定觸發事件時，可以限定分支或標籤。


on:
  push:
    branches:    
      - master

上面程式碼指定，只有master分支發生push事件時，才會觸發 workflow。

（4）jobs.<job_id>.name

workflow 檔案的主體是jobs欄位，表示要執行的一項或多項任務。

jobs欄位裡面，需要寫出每一項任務的job_id，具體名稱自定義。job_id裡面的name欄位是任務的說明。


jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

上面程式碼的jobs欄位包含兩項任務，job_id分別是my_first_job和my_second_job。

（5）jobs.<job_id>.needs

needs欄位指定當前任務的依賴關係，即執行順序。


jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

上面程式碼中，job1必須先於job2完成，而job3等待job1和job2的完成才能執行。因此，這個 workflow 的執行順序依次為：job1、job2、job3。

（6）jobs.<job_id>.runs-on

runs-on欄位指定執行所需要的虛擬機器環境。它是必填欄位。目前可用的虛擬機器如下。

  • ubuntu-latest，ubuntu-18.04或ubuntu-16.04
  • windows-latest，windows-2019或windows-2016
  • macOS-latest或macOS-10.14

下面程式碼指定虛擬機器環境為ubuntu-18.04。


runs-on: ubuntu-18.04

（7）jobs.<job_id>.steps

steps欄位指定每個 Job 的執行步驟，可以包含一個或多個步驟。每個步驟都可以指定以下三個欄位。

  • jobs.<job_id>.steps.name：步驟名稱。
  • jobs.<job_id>.steps.run：該步驟執行的命令或者 action。
  • jobs.<job_id>.steps.env：該步驟所需的環境變數。

下面是一個完整的 workflow 檔案的範例。


name: Greeting from Mona
on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
    - name: Print a greeting
      env:
        MY_VAR: Hi there! My name is
        FIRST_NAME: Mona
        MIDDLE_NAME: The
        LAST_NAME: Octocat
      run: |
        echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

上面程式碼中，steps欄位只包括一個步驟。該步驟先注入四個環境變數，然後執行一條 Bash 命令。

四、例項：React 專案釋出到 GitHub Pages

下面是一個例項，透過 GitHub Actions 構建一個 React 專案，併發布到 GitHub Pages。最終程式碼都在這個倉庫裡面，釋出後的參考網址為ruanyf.github.io/github-actions-demo。

第一步，GitHub Actions 目前還處在測試階段，需要到這個網址申請測試資格。申請以後，可能需要幾天才能透過。據說，2019年11月就會放開。

獲得資格後，倉庫頂部的選單會出現Actions一項。

第二步，這個示例需要將構建成果發到 GitHub 倉庫，因此需要 GitHub 金鑰。按照官方文件，生成一個金鑰。然後，將這個金鑰儲存到當前倉庫的Settings/Secrets裡面。

上圖是儲存秘密的環境變數的地方。環境變數的名字可以隨便起，這裡用的是ACCESS_TOKEN。如果你不用這個名字，後面指令碼里的變數名也要跟著改。

第三步，本地計算機使用create-react-app，生成一個標準的 React 應用。


$ npx create-react-app github-actions-demo
$ cd github-actions-demo

然後，開啟package.json檔案，加一個homepage欄位，表示該應用釋出後的根目錄（參見官方文件）。


"homepage": "https://[username].github.io/github-actions-demo",

上面程式碼中，將[username]替換成你的 GitHub 使用者名稱，參見範例。

第四步，在這個倉庫的.github/workflows目錄，生成一個 workflow 檔案，名字可以隨便取，這個示例是ci.yml。

我們選用一個別人已經寫好的 action：JamesIves/github-pages-deploy-action，它提供了 workflow 的範例檔案，直接複製過來就行了（檢視原始碼）。


name: GitHub Actions Build and Deploy Demo
on:
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@master

    - name: Build and Deploy
      uses: JamesIves/github-pages-deploy-action@master
      env:
        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
        BRANCH: gh-pages
        FOLDER: build
        BUILD_SCRIPT: npm install && npm run build

上面這個 workflow 檔案的要點如下。

  1. 整個流程在master分支發生push事件時觸發。
  2. 只有一個job，執行在虛擬機器環境ubuntu-latest。
  3. 第一步是獲取原始碼，使用的 action 是actions/checkout。
  4. 第二步是構建和部署，使用的 action 是JamesIves/github-pages-deploy-action。
  5. 第二步需要四個環境變數，分別為 GitHub 金鑰、釋出分支、構建成果所在目錄、構建指令碼。其中，只有 GitHub 金鑰是秘密變數，需要寫在雙括號裡面，其他三個都可以直接寫在檔案裡。

第五步，儲存上面的檔案後，將整個倉庫推送到 GitHub。

GitHub 發現了 workflow 檔案以後，就會自動執行。你可以在網站上實時檢視執行日誌，日誌預設儲存30天。

等到 workflow 執行結束，訪問 GitHub Page，會看到構建成果已經發上網了。

以後，每次修改後推送原始碼，GitHub Actions 都會自動執行，將構建產物釋出到網頁。

五、參考連結

  • GitHub Pages 官方文件
  • Github Actions for web apps, Luke Boyle
  • My First Week With GitHub Actions, Adam Zolyak

（完）

相關文章