GitHub Actions工作流语法

一个工作流示例.
欢迎来访我的个人博客Torch-Fan

name: Build and Deploy to ACK

on:
  release:
    types: [created]

# Environment variables available to all jobs and steps in this workflow.
env:
  REGION_ID: cn-hangzhou
  REGISTRY: registry.cn-hangzhou.aliyuncs.com
  NAMESPACE: namespace
  IMAGE: repo
  TAG: ${{ github.sha }}
  ACK_CLUSTER_ID: clusterID
  ACK_DEPLOYMENT_NAME: nginx-deployment

  ACR_EE_REGISTRY: myregistry.cn-hangzhou.cr.aliyuncs.com
  ACR_EE_INSTANCE_ID: instanceID
  ACR_EE_NAMESPACE: namespace
  ACR_EE_IMAGE: repo
  ACR_EE_TAG: ${{ github.sha }}

jobs:
  build:
    runs-on: ubuntu-latest
    environment: production
    
    steps:
    - name: Checkout
      uses: actions/checkout@v2
    
    # 1.1 Login to ACR   
    - name: Login to ACR with the AccessKey pair
      uses: aliyun/acr-login@v1
      with:
        region-id: "${{ env.REGION_ID }}"
        access-key-id: "${{ secrets.ACCESS_KEY_ID }}"
        access-key-secret: "${{ secrets.ACCESS_KEY_SECRET }}"

1. 关于工作流的YAML语法:

• 工作流文件的语法是YAML语法，以.yml或者.yaml作为文件后缀。
• 必须将工作流文件存储在你仓库的.github/workflows目录下

2. name

该字段标识了该工作流的名字.

如果该字段空缺，则GitHub在仓库的Actions页面展示的名字是从仓库根目录到工作流文件的相对路径。

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idsteps

3. on

Required

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#on

该字段用于指示触发工作流的GitHub事件。 所有可触发工作流的GitHub事件可见该链接：GitHub 可触发工作流的事件

• on
• on.<event_name>.types
• on.<push|pull_request>.<branches|tags>
• on.<push|pull_request>.paths
• on.schedule

如需了解GitHub Actions编写中的模式匹配规则，可参考：{% post_link GitHub-Actions模式匹配规则 %}

这里是一些触发事件的例子:

on: push

on: [push, pull_request]

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  # 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

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      # Push events on main branch
      - main
      # Push events to branches matching refs/heads/mona/octocat
      - 'mona/octocat'
      # Push events to branches matching refs/heads/releases/10
      - 'releases/**'
      - '!release/**-alpha'  # 将不会匹配release/**-alpha分支!, 
    # Sequence of patterns matched against refs/tags
    tags:        
      - v1             # Push events to v1 tag
      - v1.*   	       # Push events to v1.0, v1.1, and v1.9 tags

# 当分支或tag和 branches-ignore 和 tags-ignore中的内容匹配时,工作流将不会运行
on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      # Push events to branches matching refs/heads/mona/octocat
      - 'mona/octocat'
      # Push events to branches matching refs/heads/releases/beta/3-alpha
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:
      - v1.*           # Push events to tags v1.0, v1.1, and v1.9

on:
  schedule:
    - cron: '30 5,17 * * *'

4. premissions

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#permissions

使用该字段，可以限制GITHUB_TOKEN赋予的权限。这是一个全局的权限设置，会运用在工作流的所有任务中。也可以为某个单独的任务添加premissions字段单独设置权限.

下面是可用的字段即权限访问值:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  packages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

当你为某些字段设定了权限后，所有未设定权限的字段值为None

可以使用如下语法为所有字段设置为可写或可读:

permissions: read-all|write-all

5. env

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#env

使用该字段，可以设置一系列的环境变量，这些环境变量可以被工作流中的jobs使用。当然也可以在job中单独设置环境变量，在工作流文件根节点设置的环境变量为全局的。

例如:

env:
  SERVER: production

6. defaults

为job提供默认的设置.

defaults:
	run:
		shell: bash
		working-directory: scripts

上面的配置为所有的job配置了默认的shell和工作目录

7. jobs

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobs

• 一个工作流中会包含若干个job
• 这些job的执行默认是并行的，如果需要串行执行job，需要设定job.<job_id>.needs关键字
• 每一个job运行的环境由runs-on指定

1. job.<job_id>

每一个job都必须有一个id与之相关联，job_id是一个字符串, 他的值是一个map, 里面是job相关的配置数据. 每个job_id都应该是唯一的. job_id 只能以 _ 、字母开头，且只能包含_、字母和-

例如：

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

2. job.<job_id>.name

job展示在GitHub上的名字

3. job.<job_id>.needs

表示执行该job之前，哪些job必须先完成

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

4. job.<job_id>.runs-on

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on

每一个job都必须指定一个运行环境, GitHub-Hosted runner types:

Virtual environment	YAML workflow label
Windows Server 2019	windows-latest or windows-2019
Windows Server 2016	windows-2016
Ubuntu 20.04	ubuntu-latest or ubuntu-20.04
Ubuntu 18.04	ubuntu-18.04
Ubuntu 16.04	ubuntu-16.04
macOS Big Sur 11.0	macos-11.0
macOS Catalina 10.15	macos-latest or macos-10.15

runs-on: ubuntu-latest

当然也可以自定义环境，但是大多数情况似乎没有必要。如何自定义环境

5. job.<job_id>.permissions

见全局权限

6. job.<job_id>.environment

为github创建一个environment, github pages就是一个environment.

暂时没有使用过, 后续补充了解

7. job.<job_id>.outputs

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idoutputs

job的outputs可以被依赖该job的所有jobs访问。输出中如果有密钥，则会被修改且不会发送给GitHub Actions

如果需要使用被依赖job的输出，可以使用needs上下文环境

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}

8. job.<job_id>.env

见全局环境变量

9. job.<job_id>.defaults

见全局默认配置

10. job.<job_id>.if

使用if, 我们可以让job只在if的条件条件满足时才运行

注意, 如果要告诉GitHub if后面要视为一个表达式而不是一个字符串, 需要用: ${{ <expression> }}$

相关表达式运算和函数可见: GitHub支持的运算和函数

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: always()  # 无论 job1, job2执行是否成功都执行
    needs: [job1, job2]

常用的函数有:

steps:
  ...
  - name: The job has succeeded 
    if: ${{ success() }}  # 该step之前的步骤都成功执行在执行该step

if: ${{ always() }}  # 无论咋样都执行(工作流被取消也返回True)

if: ${{ cancelled() }}  # 工作流被取消时执行

if: ${{ failure() }}  # 前面的失败了再执行

11. job.<job_id>.steps

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idsteps

steps 内容很丰富，为了不过多和文档重合，这里只介绍主要部分：

1. run

• 每一条命令行指令都使用操作系统的shell进行执行
• 每个run都可以有个字段name, 如果不指定, 则名字为run对应的命令
• 每一个run关键字都对应一个新的进程，如果run中有多条指令,那么这些指令会执行在同一个shell内

# single-line command
- name: Install Dependencies
  run: npm install

# multi-line command
- name: Clean install dependencies and build
  run: |  # yaml的保留换行
  	npm cli
  	npm run build

working-directory 可以指定执行指令的工作路径

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: powershell

2. with

该字段用于为Actions传参

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona  # 这些都是参数
          middle_name: The
          last_name: Octocat    

当使用的Actions来自Docker容器时, with用法如下:

steps:
  - name: Explain why this job ran
    uses: monacorp/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

来自Docker的Action在使用with时有两个字段, 一个是entrypoint, 一个是args. args是传给entrypoint的参数 经常使用docker的人知道，entrypoint就是在进入容器时立即执行的可执行文件路径。

3. container

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idcontainer

容器相关使用及验证

4. services

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idservices

服务使用(如ngnix)、配置及验证