GitHub Actions 使你可以直接在你的 GitHub 庫中創(chuàng )建自定義的工作流,工作流指的就是自動(dòng)化的流程,比如構建、測試、打包、發(fā)布、部署等等,也就是說(shuō)你可以直接進(jìn)行 CI(持續集成)和 CD (持續部署)。
workflow : 一個(gè) workflow 工作流就是一個(gè)完整的過(guò)程,每個(gè) workflow 包含一組 jobs 任務(wù)。
job : jobs 任務(wù)包含一個(gè)或多個(gè) job ,每個(gè) job 包含一系列的 steps 步驟。
step : 每個(gè) step 步驟可以執行指令或者使用一個(gè) action 動(dòng)作。
action : 每個(gè) action 動(dòng)作就是一個(gè)通用的基本單元。
workflow 必須存儲在你的項目庫根路徑下的 .github/workflows 目錄中,每一個(gè) workflow 對應一個(gè)具體的 .yml 文件(或者 .yaml)。
workflow 示例:
name: Greet Everyone# This workflow is triggered on pushes to the repository.on: [push]jobs: your_job_id: # Job name is Greeting name: Greeting # This job runs on Linux runs-on: ubuntu-latest steps: # This step uses GitHub's hello-world-javascript-action: https://github.com/actions/hello-world-javascript-action - name: Hello world uses: actions/hello-world-javascript-action@v1 with: who-to-greet: 'Mona the Octocat' id: hello # This step prints an output (time) from the previous step's action. - name: Echo the greeting's time run: echo 'The time was ${{ steps.hello.outputs.time }}.'說(shuō)明:
最外層的 name 指定了 workflow 的名稱(chēng)。
on 聲明了一旦發(fā)生了 push 操作就會(huì )觸發(fā)這個(gè) workflow 。
jobs 定義了任務(wù)集,其中可以有一個(gè)或多個(gè) job 任務(wù),示例中只有一個(gè)。
runs-on 聲明了運行的環(huán)境。
steps 定義需要執行哪些步驟。
每個(gè) step 可以定義自己的 name 和 id ,通過(guò) uses 可以聲明使用一個(gè)具體的 action ,通過(guò) run 聲明需要執行哪些指令。
${{ }} 可以使用上下文參數。
上述示例可以抽象為:
name: <workflow name>on: <events that trigger workflows>jobs: <job_id>: name: <job_name> runs-on: <runner> steps: - name: <step_name> uses: <action> with: <parameter_name>: <parameter_value> id: <step_id> - name: <step_name> run: <commands>on 聲明了何時(shí)觸發(fā) workflow ,它可以是:
一個(gè)或多個(gè) GitHub 事件,比如 push 了一個(gè) commit、創(chuàng )建了一個(gè) issue、產(chǎn)生了一次 pull request 等等,示例:
on: [push, pull_request]預定的時(shí)間,示例(每天零點(diǎn)零分觸發(fā)):
on: schedule: - cron: '0 0 * * *'某個(gè)外部事件。所謂外部事件觸發(fā),簡(jiǎn)而言之就是你可以通過(guò) REST API 向 GitHub 發(fā)送請求去觸發(fā),具體請查閱官方文檔: repository-dispatch-event
配置多個(gè)事件,示例:
on: # Trigger the workflow on push or pull request, # but only for the master branch push: branches: - master pull_request: branches: - master # Also trigger on page_build, as well as release created events page_build: release: types: # This configuration does not affect the page_build event above - created詳細文檔請參考: 觸發(fā)事件
jobs 可以包含一個(gè)或多個(gè) job ,如:
jobs: my_first_job: name: My first job my_second_job: name: My second job如果多個(gè) job 之間存在依賴(lài)關(guān)系,那么你可能需要使用 needs :
jobs: job1: job2: needs: job1 job3: needs: [job1, job2]這里的 needs 聲明了 job2 必須等待 job1 成功完成,job3 必須等待 job1 和 job2 依次成功完成。
每個(gè)任務(wù)默認超時(shí)時(shí)間最長(cháng)為 360 分鐘,你可以通過(guò) timeout-minutes 進(jìn)行配置:
jobs: job1: timeout-minutes:runs-on 指定了任務(wù)的 runner 即執行環(huán)境,runner 分兩種:GitHub-hosted runner 和 self-hosted runner 。
所謂的 self-hosted runner 就是用你自己的機器,但是需要 GitHub 能進(jìn)行訪(fǎng)問(wèn)并給與其所需的機器權限,這個(gè)不在本文描述范圍內,有興趣可參考 self-hosted runner 。
GitHub-hosted runner 其實(shí)就是 GitHub 提供的虛擬環(huán)境,目前有以下四種:
windows-latest : Windows Server 2019
ubuntu-latest 或 ubuntu-18.04 : Ubuntu 18.04
ubuntu-16.04 : Ubuntu 16.04
macos-latest : macOS Catalina 10.15
比較常見(jiàn)的:
runs-on: ubuntu-latest有時(shí)候我們常常需要對多個(gè)操作系統、多個(gè)平臺、多個(gè)編程語(yǔ)言版本進(jìn)行測試,為此我們可以配置一個(gè)構建矩陣。
例如:
runs-on: ${{ matrix.os }}strategy: matrix: os: [ubuntu-16.04, ubuntu-18.04] node: [6, 8, 10]示例中配置了兩種 os 操作系統和三種 node 版本即總共六種情況的構建矩陣,${{ matrix.os }} 是一個(gè)上下文參數。
strategy 策略,包括:
matrix : 構建矩陣。
fail-fast : 默認為 true ,即一旦某個(gè)矩陣任務(wù)失敗則立即取消所有還在進(jìn)行中的任務(wù)。
max-paraller : 可同時(shí)執行的最大并發(fā)數,默認情況下 GitHub 會(huì )動(dòng)態(tài)調整。
示例:
runs-on: ${{ matrix.os }}strategy: matrix: os: [macos-latest, windows-latest, ubuntu-18.04] node: [4, 6, 8, 10] include: # includes a new variable of npm with a value of 2 for the matrix leg matching the os and version - os: windows-latest node: 4 npm: 2include 聲明了 os 為 windows-latest 時(shí),增加一個(gè) node 和 npm 分別使用特定的版本的矩陣環(huán)境。
與 include 相反的就是 exclude :
runs-on: ${{ matrix.os }}strategy: matrix: os: [macos-latest, windows-latest, ubuntu-18.04] node: [4, 6, 8, 10] exclude: # excludes node 4 on macOS - os: macos-latest node: 4exclude 用來(lái)刪除特定的配置項,比如這里當 os 為 macos-latest ,將 node 為 4 的版本從構建矩陣中移除。
steps 的通用格式類(lèi)似于:
steps: - name: <step_name> uses: <action> with: <parameter_name>: <parameter_value> id: <step_id> continue-on-error: true - name: <step_name> timeout-minutes: run: <commands>每個(gè) step 步驟可以有:
id : 每個(gè)步驟的唯一標識符
name : 步驟的名稱(chēng)
uses : 使用哪個(gè) action
run : 執行哪些指令
with : 指定某個(gè) action 可能需要輸入的參數
continue-on-error : 設置為 true 允許此步驟失敗 job 仍然通過(guò)
timeout-minutes : step 的超時(shí)時(shí)間
action 動(dòng)作通常是可以通用的,這意味著(zhù)你可以直接使用別人定義好的 action 。
checkout action 是一個(gè)標準動(dòng)作,當以下情況時(shí)必須且需要率先使用:
workflow 需要項目庫的代碼副本,比如構建、測試、或持續集成這些操作。
workflow 中至少有一個(gè) action 是在同一個(gè)項目庫下定義的。
使用示例:
- uses: actions/checkout@v1如果你只想淺克隆你的庫,或者只復制最新的版本,你可以在 with 中使用 fetch-depth 聲明,例如:
- uses: actions/checkout@v1 with: fetch-depth: 1官方 action 標準庫: github.com/actions
社區庫: marketplace
引用 action 的格式是 {owner}/{repo}@{ref} 或 {owner}/{repo}/{path}@{ref} ,例如上例的中 actions/checkout@v1 ,你還可以使用標準庫中的其它 action ,如設置 node 版本:
jobs: my_first_job: name: My Job Name steps: - uses: actions/setup-node@v1 with: node-version: 10.x引用格式:{owner}/{repo}@{ref} 或 ./path/to/dir 。
例如項目文件結構為:
|-- hello-world (repository)| |__ .github| └── workflows| └── my-first-workflow.yml| └── actions| |__ hello-world-action| └── action.yml當你想要在 workflow 中引用自己的 action 時(shí)可以:
jobs: build: runs-on: ubuntu-latest steps: # This step checks out a copy of your repository. - uses: actions/checkout@v1 # This step references the directory that contains the action. - uses: ./.github/actions/hello-world-action如果某個(gè) action 定義在了一個(gè) docker container image 中且推送到了 Docker Hub 上,你也可以引入它,格式是 docker://{image}:{tag} ,示例:
jobs: my_first_job: steps: - name: My first step uses: docker://alpine:3.8更多信息參考: Docker-image.yml workflow 和 Creating a Docker container action 。
請參考:building-actions
環(huán)境變量可以配置在以下地方:
env
jobs.<job_id>.env
jobs.<job_id>.steps.env
示例:
env: NODE_ENV: devjobs: job1: env: NODE_ENV: test steps: - name: env: NODE_ENV: prod如果重復,優(yōu)先使用最近的那個(gè)。
你可以在 job 和 step 中使用 if 條件語(yǔ)句,只有滿(mǎn)足條件時(shí)才執行具體的 job 或 step :
jobs.<job_id>.if
jobs.<job_id>.steps.if
任務(wù)狀態(tài)檢查函數:
success() : 當上一步執行成功時(shí)返回 true
always() : 總是返回 true
cancelled() : 當 workflow 被取消時(shí)返回 true
failure() : 當上一步執行失敗時(shí)返回 true
例如:
steps: - name: step1 if: always() - name: step2 if: success() - name: step3 if: failure()意思就是 step1 總是執行,step2 需要上一步執行成功才執行,step3 只有當上一步執行失敗才執行。
${{ <expression> }}上下文和表達式: ${{ <expression> }} 。
有時(shí)候我們需要與第三方平臺進(jìn)行交互,這時(shí)候通常需要配置一個(gè) token ,但是顯然這個(gè) token 不可能明文使用,這種個(gè)情況下我們要做的就是:
在具體 repository 庫 Settings 的 Secrets 中添加一個(gè)密鑰,如 SOMEONE_TOKEN
然后在 workflow 中就可以通過(guò) ${{ secrets.SOMEONE_TOKEN }} 將 token 安全地傳遞給環(huán)境變量。
steps: - name: My first action env: SOMEONE_TOKEN: ${{ secrets.SOMEONE_TOKEN }}這里的 secrets 就是一個(gè)上下文,除此之外還有很多,比如:
github.event_name : 觸發(fā) workflow 的事件名稱(chēng)
job.status : 當前 job 的狀態(tài),如 success, failure, or cancelled
steps.<step id>.outputs : 某個(gè) action 的輸出
runner.os : runner 的操作系統如 Linux, Windows, or macOS
這里只列舉了少數幾個(gè)。
另外在 if 中使用時(shí)不需要 ${{ }} 符號,比如:
steps: - name: My first step if: github.event_name == 'pull_request' && github.event.action == 'unassigned' run: echo This event is a pull request that had an assignee removed.上下文和表達式詳細信息請參考: contexts-and-expression
最后給個(gè)自己寫(xiě)的示例,僅供參考:
name: GitHub Actions CIon: [push]jobs: build-test-deploy: runs-on: ubuntu-latest strategy: matrix: node-version: [8.x, 10.x, 12.x] steps: - uses: actions/checkout@v1 - name: install linux packages run: sudo apt-get install -y --no-install-recommends libevent-dev - name: install memcached if: success() run: | wget -O memcached.tar.gz http://memcached.org/files/memcached-1.5.20.tar.gz tar -zxvf memcached.tar.gz cd memcached-1.5.20 ./configure && make && sudo make install memcached -d - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v1 if: success() with: node-version: ${{ matrix.node-version }} - name: npm install, build, and test env: CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} if: success() run: | npm ci npm test npm run report-coverage聯(lián)系客服