GitHub Action简介

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

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 的文件名。

name: My GitHub Actions

on

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

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

# 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字段是任务的说明。

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：指定运行所需要的虚拟机环境。必填字段
有三种系统选择，具体版本如下

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字段。

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 输出命令。

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多环境

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

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

${{ 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时触发。

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

引用action的格式为 {username}/{repo}@{res}，例如actions/checkout@v2，表示使用actions/checkout仓库，版本为v2

引用同一个库中的 action

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

文件目录树为：

|-- workflow (repository)
|   |__ .github
|       └── workflows
|           └── first-workflow.yml
|       └── actions
|           |__ say-hello-action
|               └── action.yml

可以这样引用：

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的镜像

也可以拉取docker镜像来构建，格式为 docker://{image}:{tag}

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可以自动拉取项目仓库的代码。

jobs:
  first_job:
    name: My first job
    steps:
    - name: Checkout actions
      uses: actions/checkout@v2

Setup Python

设置python环境

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下

env: 
  TEST_ENV: global

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

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

一个实验例子

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

相关的函数

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

一个例子

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

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()

密钥以及上下文表达式

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

Secrets 说明

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

Secrets 使用

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

jobs:
  first_job:
    name: My first job
    runs-on: ubuntu-latest
    steps:
      - name: first_step
        env:
          TOKEN: ${{ secrets.TOKEN }}

一些常用上下文

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

参考

• https://help.github.com/en/categories/automating-your-workflow-with-github-actions
• https://blog.csdn.net/Ber_Bai/article/details/120303880