Github Actions总结

GitHub Actions 是 GitHub 的持续集成服务，于2018年10月推出。

Github Action VS Travis CI

在github推出action之前，Travis CI是一个很好对Github中仓库做自动化的一个工具，其语法也很简单，功能强大，深受用户的青睐。那么action出来后，势必会和travis对比。

在笔者的实际体验中，觉得action比较吸引我的点：

支持私有仓库
action对github各个事件的支持更为全面，如果release，pull-request，issue事件等等
github对action编写的支持更为友好，包括在线编辑器和marketplace的共享actions

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）。

为项目创建Action

如果想在仓库中开始action, 可以手动在仓库的根目录下新建.github/workflows文件夹，然后新建任意以.yml或者.yaml结尾的多个文件，这些文件都是action的配置文件，相当于travis中的.travis.yml

启动action也可以通过github仓库界面创建（后续查看action记录也是在这），点击Actions选项；

点击后会进入以下界面，此时我们可以直接使用官方的一些预设的模块，或者使用空模板：

下图就是github官方提供的action编辑器，能提供简单的语法提示和错误检测；右边可以直接搜索Marketplace里面的一下action使用，也可以通过Documentation查看文档。

workflow 文件

GitHub Actions 的配置文件叫做 workflow 文件，存放在代码仓库的.github/workflows目录。

workflow 文件采用 YAML 格式，文件名可以任意取，但是后缀名统一为.yml，比如foo.yml。

一个库可以有多个 workflow 文件。GitHub 只要发现.github/workflows目录里面有.yml文件，就会自动运行该文件。

workflow 文件的配置字段非常多，详见官方文档。

下面是一些基本字段：

on规定action的触发条件:

使用web事件触发工作流，并且可以具体指定branches，tags以及文件路径；
使用cron语法指定时间触发工作流；

其中web事件可以指定如上述例子的push事件，如果想指定多个事件，格式为：

on: [push, pull_request]
# 或
on:
  push:
  pull_request:

如果不特别指定某一个分支，触发机制会应用到所有分支；

如果要具体指定到某一个分支，可使用branch选项：

on:
  push:
    branches: [master]
  pull_request:
    branches: [other]

触发条件还可以过滤特定的tag或者文件路径，通过使用tags或者paths选项；

例如：如果想只在v1这个tag被推送时或者是当前推送包含test的文件时，构建操作被触发，可以使用下面配置：

on:
  push:
    tags: [v1]
    paths: ['test/*']

同时，还可以忽略某些branch, tag或者文件，通过使用branches-ignore，tags-ignore, paths-ignore, 如branches-ignore:[second]，可以排除second分支的更改，它等同于braches:[!second]。

需要特别注意的是：无法对工作流程中的同一事件同时使用 branches 和 branches-ignore 过滤器。需要过滤肯定匹配的分支和排除分支时，建议使用 branches 过滤器。只需要排除分支名称时，建议使用 branches-ignore 过滤器，tags-ignore和paths-ignore也是如此。

如果希望定时触发工作流，此时schedule就登场了；

例如：如果希望每10分钟运行一次，配置为：

on:
  schedule:
    - cron:  '*/10 * * * *'

简单说明cron中每一项的含义：

第一项是分钟，第二项是小时，第三项是天，第四项是月，第五项是星期几。可使用crontab在线配置想要的时间。

action中可以运行预定工作流程的最短间隔是每 5 分钟一次

完整事件详见触发工作流程的事件。

工作流默认包含一个或者多个job，每一个job都是一个独立的工作单元；

job`属性主要包含：

name: job显示的名字
runs-on: 指定job运行的机器
steps: 一个job包含多个step, step是job的最小单元，所有step配置在steps中
env: 指定环境变量
needs: 指定job的依赖

① id和name

其中name和job id可能一开始会让人有点混淆，如：

jobs:
  build:
    name: Greeting

其中job id指的是build，是在配置文件中可别其他部分引用；

name指的是Greeting, 他将会显示在action的记录页面中；

② runs-on

action可使用的机器包括：

虚拟环境 YAML 工作流程标签 Windows Server 2019 windows-latest 或 windows-2019 Ubuntu 18.04 ubuntu-latest 或 ubuntu-18.04 Ubuntu 16.04 ubuntu-16.04 macOS Catalina 10.15 macos-latest or macos-10.15

并且每台机器的配置都是：

2-core CPU，7 GB RAM 内存，14 GB SSD 硬盘空间。

可以说是相当良心了。

needs

当action中有多个job时，默认是并行运行；

如果某一个job需要依赖另一个job，可使用needs属性，如：

jobs:
  job1:
  job2:
    needs: job1

此时job2会在job1成功完成后才会开始执行

steps

job中所有的操作都在steps中，每个step主要包含id,name, run, uses等属性。

jobs:
  first_job:
    steps:
      - name: first step
        uses: actions/heroku@master
      - name: second step
        run: echo 'finish'

run指定具体命令，如果是多条命令，格式为：

run: |
  echo 'first line'
  echo 'second line'

uses用于使用其他用户所发布的action；

如：actions/heroku@master；

如果其他action需要参数，使用with传参，如：

- name: Setup Node.js for use with actions
  uses: actions/[email protected]
  with:
    version:10.x

可以在github action marketplace查看更多好用的action。

至此就是acion的基础语法，更多细节参见完整语法

Action进阶用法

为工作流加一个Badge

在action的面板中，点击Create status badge就可以复制badge的markdown内容到README.md中；

之后就可以直接在README.md中看到当前的构建结果：

使用构建矩阵

如果我们想在多个系统或者多个语言版本上测试构建，就该构建矩阵发挥作用了。

例如：我们想在多个node版本下跑测试，可以使用如下配置，action会分别使用10.x和12.x的版本各运行一次job

jobs:
  build:
    strategy:
      matrix:
        node-version: [10.x, 12.x]

    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}

      - run: npm ci
      - run: npm test

使用Secrets

构建过程可能需要用到ssh或者token等敏感数据，而我们是不希望这些数据直接暴露在仓库中，此时就可以使用secrets：

在对应项目中选择Settings-> Secrets即可创建secret；

配置文件中的使用方法：

steps:
  - name: use secrets
    env: 
      super_secret: ${{ secrets.YourSecrets }}

secret name不区别大小写；

所以如果新建secret的的名字是name，使用时secrets.name或者secrets.Name都是ok的；

并且就算此时直接使用echo打印secret, 控制台也只会打印出*来保护secret！

Cache

在构建过程中，会安装很多第三方依赖，而这些依赖并不需要每次都重新下载，可以将这些依赖缓存起来，加快构建速度。

主要使用action/cache。

该action主要包含三个属性：

path: 需要缓存的文件的路径
key: 对缓存的文件指定的唯一表示
restore-key: 主要用于没有再找目标key的缓存的backup选项（可选项）

下面以node项目为例，将node_modules缓存起来。

这里只列出关键步骤：

steps:
      - name: Cache Node Dependencies
        id: cache
        uses: actions/cache@v1
        with:
          path: node_modules
          key: ${{runner.OS}}-npm-caches-${{ hashFiles('package-lock.json') }}

      - name: Install Dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: npm install

首先使用action/cache指定path和key；

这里的key包含OS信息和package-lock.json文件的hash值，通常OS是固定下来的；

而一旦使用了新的第三方库，package-lock.json的hash值就会改变，得到一个新的key；

action/cache会抛出一个cache-hit的输出，如果找到对应key的缓存，值为true。

在随后的安装步骤中，可以使用if对cache-hit做判断。如果找到缓存就跳过，否则就安装依赖。

在第一次运行时，cache找不到，执行npm install，在随后的post cache步骤中对node_modules做缓存。

第二次运行时，找到cache, 则跳过npm install，直接使用缓存：

artifact

在构建过程中，可能需要输出一些构建产物，并且不同于cache，这些构建产物在action执行完成后，用户还是可以下载查看。

通常artifact主要有：日志文件，测试结果等等；

主要使用action/upload-artifact 和 download-artifact 进行构建参悟的相关操作。

这里以输出jest测试报告为例，jest测试后的测试报告的路径是coverage:

steps:
      - run: npm ci
      - run: npm test

      - name: Collect Test Coverage File
        uses: actions/[email protected]
        with:
          name: coverage-output
          path: coverage

执行成功后就能在对应action面板看到生成的artifact：

Action限制

这里简单列出action的各种使用限制：

action的最大执行时间是72小时，超过该时间，action会自动失败
action一小时最大的API请求数量是1000
action中每个job最大执行时间为6小时，超过该时间，job会自动失败
action中矩阵最多能构建256个job
action中多个job默认会并行执行，但对于最大的并行数也是有限制的：

GitHub 计划同时运行的作业总数 MacOS 作业同时运行的最大数量免费 20 5 Pro 40 5 团队 60 5 企业 180 50

关于GitHub Actions付费条款详见About billing for GitHub Actions。

GitHub Actions相关资源

GitHub Actions官方文档：

https://docs.github.com/en/actions

GitHub Actions的相关资源有：

本文摘自：

Github Actions总结