Github actions

本文转自 阮一峰 的 GitHub Actions 入门教程

在线查看

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

这些天在整理前端工程化这块知识，相比其他持续集成服务觉得有特有的创意。

本文是一个简单教程，演示如何使用 GitHub Actions 自动发布一个 React 应用到 GitHub Pages。

GitHub Actions 是什么

持续集成是由很多操作组成的，比如抓取代码、运行测试、登录远程服务器，发布到第三方服务等等。GitHub 把这些操作就称为 actions。

很多操作在不同项目里面是类似的，完全可以共享。GitHub 注意到了这一点，想出了一个很妙的点子：允许开发者把每个操作写成独立的脚本文件，存放到代码仓库，使得其他开发者可以引用。

如果你需要某个 action，不必自己写复杂的脚本，直接引用他人写好的 action 即可，整个持续集成过程，就变成了一个 actions 的组合。这就是 GitHub Actions 最特别的地方。

GitHub 做了一个 Actions 官方市场，可以搜索到他人提交的 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@1c5c137 # 指向一个 commit
actions/setup-node@v1.4.0    # 指向一个标签
actions/setup-node@master  # 指向一个分支
复制代码

基本概念

GitHub Actions 有一些自己的术语。

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

workflow 文件 xx.yml

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

workflow 文件采用 YAML 格式，文件名可以任意取，但是后缀名统一为.yml，比如foo.yml。一个库可以有多个 workflow 文件。GitHub 只要发现 .github/workflows 目录里面有 .yml 文件，就会自动运行该文件。

workflow 文件的配置字段非常多，详见官方文档。下面是一些基本字段。

name

name 字段是 workflow 的名称。GitHub在存储库的“操作”页面上显示工作流程的名称。如果省略name，则GitHub将其设置为相对于存储库根目录的工作流文件路径。

name: GitHub Actions Build and Deploy Demo
复制代码

on

必需触发工作流程的GitHub事件的名称。您可以提供一个事件string，array一个事件，array一个事件types或一个事件配置map，以安排工作流程或将工作流程的执行限制为特定的文件，标记或分支更改。有关可用事件的列表，请参阅“ 触发工作流的事件” 。

单个事件的示例

# Trigger on push
on: push
复制代码

事件列表的示例

# Trigger the workflow on push or pull request
on: [push, pull_request]
复制代码

完整的事件列表，请查看官方文档。除了代码库事件，GitHub Actions 也支持外部事件触发，或者定时运行。

使用具有活动类型或配置的多个事件的示例

指定触发事件时，可以限定分支或标签。

on:
  # Trigger the workflow on push or pull request,
  # but only for the master branch
  push:
    branches:
      - master
复制代码

上面代码指定，只有 master 分支发生 push 事件时，才会触发 workflow。

jobs

jobs.<job_id>.name

workflow 文件的主体是 jobs 字段，表示要执行的一项或多项任务。

jobs 字段里面，需要写出每一项任务的 job_id，具体名称自定义。job_id 里面的 name 字段是显示在 GitHub 上任务的说明。

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job
复制代码

上面代码的 jobs 字段包含两项任务，job_id 分别是 my_first_job 和 my_second_job。

jobs.<job_id>.needs

needs 字段指定当前任务的依赖关系，即运行顺序。

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]
复制代码

上面代码中，job1 必须先于 job2 完成，而 job3 等待 job1 和 job2 的完成才能运行。因此，这个 workflow 的运行顺序依次为：job1、job2、job3。

jobs.<job_id>.runs-on

runs-on 字段指定运行所需要的虚拟机环境。它是必填字段。GitHub 托管的可用虚拟机为：

虚拟环境	YAML工作流程标签
Windows Server 2019	windows-latest 要么 windows-2019
Ubuntu 18.04	ubuntu-latest 要么 ubuntu-18.04
Ubuntu 16.04	ubuntu-16.04
macOS卡塔利娜10.15	macos-latest 要么 macos-10.15

下面代码指定虚拟机环境为 ubuntu-18.04。

runs-on: ubuntu-18.04
复制代码

jobs.<job_id>.steps

steps 字段指定每个 Job 的运行步骤，可以包含一个或多个步骤。每个步骤都可以指定以下三个字段。

• jobs.<job_id>.steps.name：步骤名称。
• jobs.<job_id>.steps.run：该步骤运行的命令或者 action。
• jobs.<job_id>.steps.env：该步骤所需的环境变量。

下面是一个完整的 workflow 文件的范例。

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
    - name: Print a greeting
      env:
        MY_VAR: Hi there! My name is
        FIRST_NAME: Mona
        MIDDLE_NAME: The
        LAST_NAME: Octocat
      run: |
        echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.
复制代码

上面代码中，steps 字段只包括一个步骤。该步骤先注入四个环境变量，然后执行一条 Bash 命令。

实例

将 React 项目发布到 GitHub Pages

下面是一个实例，通过 GitHub Actions 构建一个 React 项目，并发布到 GitHub Pages。最终代码都在这个仓库里面，发布后的参考网址为 ruizhengyun.cn/github-acti…。

步骤一

示例需要将构建源代码发到 GitHub 仓库，因此需要 GitHub 密钥。按照官方文档，生成一个密钥。然后，将这个密钥储存到当前仓库的 Settings/Secrets 里面。

上图是储存秘密的环境变量的地方。环境变量的名字可以随便起，这里用的是 ACCESS_TOKEN。如果你不用这个名字，后面脚本里的变量名也要跟着改。

步骤二

本地使用 create-react-app，生成一个 React 应用，推荐使用 npx 来使用 create-react-app 脚手架，用过就删除。

npx create-react-app github-actions
cd github-actions
复制代码

然后，打开 package.json 文件，加一个 homepage 字段，表示该应用发布后的根目录（参见官方文档）。

"homepage": "https://username.github.io/github-actions",
复制代码

上面代码中，将 username 替换成你的 GitHub 用户名，参见范例。

步骤三

在这个仓库的 .github/workflows 目录，生成一个 workflow 文件，名字可以随便取，这个示例是 ci.yml。

我们选用一个别人已经写好的 action：JamesIves/github-pages-deploy-action，它提供了 workflow 的范例文件，直接拷贝过来就行了（查看源码）。

name: GitHub Actions Build and Deploy Demo
on:
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@master

      - name: Build and Deploy
        uses: JamesIves/github-pages-deploy-action@master
        env:
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          BRANCH: gh-pages
          FOLDER: build
          BUILD_SCRIPT: npm install && npm run build
复制代码

workflow 文件这里做个说明

• 首先，整个流程在 master 分支发生 push 事件时触发。
• 只有一个 job，运行在虚拟机环境 ubuntu-latest。
• 第一步是获取源码，使用的 action 是 actions/checkout。
• 第二步是构建和部署，使用的 action 是 JamesIves/github-pages-deploy-action。
• 第二步需要四个环境变量，分别为 GitHub 密钥、发布分支、构建成果所在目录、构建脚本。其中，只有 GitHub 密钥是秘密变量，需要写在双括号里面，其他三个都可以直接写在文件里。

步骤四

保存上面的文件后，将整个仓库推送到 GitHub。

GitHub 发现了 workflow 文件以后，就会自动运行，此时在网站上实时查看运行日志。

等到 workflow 运行结束，访问 GitHub Page，会看到构建成果已经发上网了。

以后，每次修改后推送源码，GitHub Actions 都会自动运行，将构建产物发布到网页。

阅读文章或评论

参考链接

• GitHub Pages 官方文档
• Github Actions for web apps, Luke Boyle
• My First Week With GitHub Actions

文末