本文由 简悦 SimpRead 转码， 原文地址 cdmana.com

GitHub Action 简介 GitHub Actions 使你可以直接在你的 GitHub 库中创建自定义的工作流，工作流指的就是自动化的流

GitHub Actions 使你可以直接在你的 GitHub 库中创建自定义的工作流，工作流指的就是自动化的流程，比如构建、测试、打包、发布、部署等等，也就是说你可以直接进行 CI（持续集成）和 CD（持续部署）。

简单地说，就是利用官方以及第三方提供的 actions，组合 action 来实现一些你能做到的其他事情，比如抓取代码、运行测试、登录远程服务器，发布到第三方服务等等。

另外，官方以及第三方提供的 actions 都收集在这里 Marketplace Actions 和 awesome actions 的仓库

基本概念

  1. workflow （工作流程）：持续集成一次运行的过程，就是一个 workflow。
  2. job （任务）：一个 workflow 由一个或多个 jobs 构成，含义是一次持续集成的运行，可以完成多个任务。
  3. step（步骤）：每个 job 由多个 step 构成，一步步完成。
  4. action （动作）：每个 step 可以依次执行一个或多个命令（action）。

workflow 必须存储在你的 github 项目库路径下的 .github/workflows 目录中，每一个 workflow 对应一个具体的. yml 文件。GitHub 会检索. github/workflows 目录里面的. yml 文件，并按照设定的规则定时或监听触发条件运行。

看到这，或许你使用过 yaml，知道它是如何编写的，大概你就能知道它的工作原理了。

workflow 文件的配置可参考 https://help.github.com/en/articles/workflow-syntax-for-github-actions

配置字段说明

name

name 字段是 workflow 的名称。如果省略该字段，默认为当前 workflow 的文件名。

1
name: My GitHub Actions

on

on 字段指定触发 workflow 的条件，通常是某些事件。上面代码指定，push 事件触发 workflow。

on 字段也可以是事件的数组。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# push时触发 workflow
on: push

# 也可以是一系列触发的数组，push 或 pull_request时触发
on: [push, pull_request]

# main分支push时触发
on:
  push:
    branches:
      - main

# 点击star时触发
on: 
  watch:
    types: [started]  

# 使用cron定时执行，这里表示每小时执行一次
on: 
  schedule:
    - cron: "0 * * * *"

jobs

jobs 是 workflow 文件的主体，表示要执行的一项或多项任务。jobs 字段里面，需要写出每一项任务的 job_id，具体名称自定义。job_id 里面的 name 字段是任务的说明。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
jobs:
  first_job:
    name: My first job
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
    - name: first_step
      env: 
        START_STR: Hi there! My name is
        USER_NAME: Ber
        END_STR: Thank you
      run: | echo $START_STR $USER_NAME $END_STR.
        
  second_job:
    name: My second job
    needs: first_job
    timeout-minutes: 45
    runs-on: macOS-latest
    
  third_job:
    name: My third job
    needs: [first_job, second_job]
    timeout-minutes: 60
    runs-on: windows-latest

上面代码的 jobs 字段包含 first_job 和 second_job 两项任务，job_id 分别是 first_job、second_job 和 third_job。

needs：设定当前任务的执行依赖关系，即执行运行顺序，此 jobs 的执行顺序：first_job、second_job、third_job。

timeout-minutes：每个任务默认超时时间最长为 360 分钟，通过 timeout-minutes 自定义设置任务最长执行时间。

runs-on：指定运行所需要的虚拟机环境。必填字段
有三种系统选择，具体版本如下

1
2
3
ubuntu-latest，ubuntu-18.04或ubuntu-16.04
windows-latest，windows-2019或windows-2016
macOS-latest或macOS-10.14

steps：steps 字段指定每个 Job 的运行步骤，可以包含一个或多个步骤。每个步骤都可以指定 name、run、env、id、uses、with、continue-on-error、continue-on-error 字段。

1
2
3
4
5
6
7
8
name: 步骤名称
env: 该步骤所需的环境变量
run: 该步骤运行的命令，如上面的例子：bash输出环境变量
id : 每个步骤的唯一标识符
uses : 使用哪个 action
with : 指定某个 action 可能需要输入的参数
continue-on-error : 设置为 true 允许此步骤失败 job 仍然通过
timeout-minutes : step 的超时分钟数

一个完整例子

当 push 和 pull_request 时触发 workflow，包含一个 job，job 中包含一个 step，先注入四个环境变量，然后执行一条 bash 输出命令。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
name: say hi

on: [push, pull_request]

jobs: 
  my-job:
    name: My Job Say Hi
    runs-on: ubuntu-latest
    steps:
    - name: Say Hi
      env:
        START_STR: Hi there! My name is
        USER_NAME: Ber
        END_STR: Thank you
      run: | echo $START_STR $USER_NAME $END_STR.

学完以上的内容基础上可以使用一些常规的 action 持续集成了。如果还想学一些深入操作，比如多环境，action 作用等，请继续往下学吧。

runs-on 结合 strategy 配置 job 多环境

此场景适用于项目多环境测试

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
jobs:
  first_job:
    name: My first job
    timeout-minutes: 30
    runs-on: ${
    {
     matrix.os }}
    strategy:
      matrix:
        os: [windows-2016, ubuntu-18.04]
        node: [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: 2
        exclude:
        - os: windows-2016
          node: 6
1
2
3
4
${{ matrix.os}} 表示一个上下文参数


strategy：包括 matrix、fail-fast、max-paraller 参数。
  • matrix：构建一个任务组合矩阵
  • fail-fast：一旦矩阵某个任务执行失败，就取消所有矩阵任务，默认为 true
  • max-paraller：同时执行的最大并发数，默认由 github 动态调整
    • include：表示增加一个 os 为 windows-latest、node、npm 特定版本的环境
    • exclude：表示移除一个 os 为 windows-2016，node 为 6 的环境

一个完整多环境例子

给 github 仓库点 star 时触发。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
name: My GitHub Actions

on: 
  watch:
    types: [started]  

jobs:
  first_job:
    name: My first job
    timeout-minutes: 30
    runs-on: ${
    {
     matrix.os }}
    strategy:
      matrix:
        os: [windows-2016, ubuntu-18.04]
        node: [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: 2
        exclude:
        - os: windows-2016
          node: 6
    steps:
    - name: first_step
      run: | echo hi ber.

action 总结

action 是封装好的一系列通用包，也就意味着可以直接使用已经定义好的 action 。

引用格式

引用公有库中的 action

1
引用 action 的格式为 {username}/{repo}@{res}，例如 actions/checkout@v2，表示使用 [actions/checkout 仓库](https://github.com/actions/checkout)，版本为 v2

引用同一个库中的 action

1
引用格式：{username}/{repo}@{ref} 或 ./path/to/dir

例如：

文件目录树为：

1
2
3
4
5
6
7
|-- workflow (repository)
|   |__ .github
|       └── workflows
|           └── first-workflow.yml
|       └── actions
|           |__ say-hello-action
|               └── action.yml

可以这样引用：

1
2
3
4
5
6
7
8
9
jobs:
  first_job:
    name: My first job
    runs-on: ubuntu-latest
    steps:
    - name: Checkout actions
      uses: actions/checkout@v2
    - name: Say hello
      uses: ./.github/actions/say-hello-action

引用 DockerHub 的镜像

1
也可以拉取 docker 镜像来构建，格式为 docker://{image}:{tag}
1
2
3
4
5
6
7
jobs:
  first_job:
    name: My first job
    runs-on: ubuntu-latest
    steps:
    - name: DockerHub image
      uses: docker://hello-world

常见的公开 action 库

比如常见的：checkout action、Setup Python 等

checkout action

这是一个官方提供的 action，如需要使用项目仓库中代码用来构建、测试等的，使用 checkout action 可以自动拉取项目仓库的代码。

1
2
3
4
5
6
jobs:
  first_job:
    name: My first job
    steps:
    - name: Checkout actions
      uses: actions/checkout@v2

Setup Python

设置 python 环境

1
2
3
4
5
6
7
8
jobs:
  first_job:
    name: My first job
    steps:
    - name: Setup Python 3.8
      uses: actions/setup-python@master
      with:
        python-version: 3.8

env 环境变量总结

env 可以定义在一级、job 和 step 下

1
2
3
4
5
6
7
8
9
10
11
env: 
  TEST_ENV: global

jobs:
  first_job:
    env:
      TEST_ENV: first job
    steps:
      - name: first step
        env:
          TEST_ENV: first step

上例中，环境变量名是重复的，会优先使用最近的变量

一个实验例子

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
name: My GitHub Actions

on: 
  watch:
    types: [started]  

env: 
  TEST_ENV: global

jobs:
  first_job:
    name: My first job
    env:
      TEST_ENV: first job
    runs-on: ubuntu-latest
    steps:
    - name: test 1
      env:
        TEST_ENV: first step
      run: | echo $TEST_ENV
    - name: test 2
      run: | echo $TEST_ENV

if 条件

if 语句可以在 job 和 step 中使用，只有满足条件时才执行具体的 job 或 step

相关的函数

1
2
3
4
5
# 任务状态检查函数
success() : 当上一步执行成功时返回 true
always() : 总是返回 true
cancelled() : 当 workflow 被取消时返回 true
failure() : 当上一步执行失败时返回 true

一个例子

first_step 会总是执行，second_step 需要上一步 first_step 执行成功才会执行，third_step 只有上一步 second_step 执行失败才执行。

1
2
3
4
5
6
7
8
9
10
11
12
13
jobs:
  first_job:
    name: My first job
    runs-on: ubuntu-latest
	steps:
	  - name: first_step
	    if: always()
	
	  - name: second_step
	    if: success()
	
	  - name: third_step
	    if: failure()

密钥以及上下文表达式

1
${{}} 可以获取上下文环境变量、检查函数以及 Secrets 中秘钥。

Secrets 说明

当使用 workflow 时，一些不能公开的密码、token 等，可以使用 Secrets 进行保存，在项目仓库中 settings->Secrets ->new repository secrets

Secrets 使用

如果 Secrets 添加了 TOKEN，workflow 中这样就可以获取到。

1
2
3
4
5
6
7
8
9
10
jobs:
  first_job:
    name: My first job
    runs-on: ubuntu-latest
	steps:
	  - name: first_step
	    env:
	      TOKEN: ${
    {
     secrets.TOKEN }}

一些常用上下文

1
2
3
4
github.event_name : 触发 workflow 的事件名称
job.status : 当前 job 的状态，如 success, failure, or cancelled
steps.<step id>.outputs : 某个 action 的输出
runner.os : runner 的操作系统如 Linux, Windows, or macOS

参考

版权声明
本文为 [鳄鱼儿] 所创，转载请带上原文链接，感谢
https://blog.csdn.net/Ber_Bai/article/details/120310024