GitHub Actions 入门教程

# 前言

本篇文章参考自 阮一峰 的 GitHub Actions 入门教程 (opens new window)

GitHub Actions (opens new window) 是 GitHub 的持续集成服务 (opens new window)，于2018年10月推出。正式版于 2019 年 11 月正式推出。
持续集成由很多操作组成，比如拉取代码、运行测试、登录远程服务器，发布到第三方服务等等，GitHub 把这些操作就称为 actions。
GitHub Actions 最特别的地方是可以共享，你可以直接引用他人写好的 action，也可将自己写好的 action 共享给别人使用。

# 基本概念

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

# workflow 文件

GitHub Actions 的配置文件叫做 workflow 文件，存放在代码仓库的 .github/workflows 目录。必须是这个目录下，就是这么规定的。

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

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

# `name`

含义：workflow 的名称，如果省略该字段，默认为当前 workflow 的文件名。
示例：name: CI

# `on`

含义：指定触发 workflow 的条件，通常是某些事件。
示例1：on: push 发生 push 事件时触发。
示例2：on: [push, pull_request] 发生 push 事件或 pull_request 事件都可以触发。
示例3：只有在 master 分支发生 push 事件时，才会触发 workflow。

on:
  push:
    branches:    
      - master

1
2
3
4

示例4：手动触发 (在github仓库的action下对应的action开启了 Runs workflow 按钮，方便手动测试)

on:
  workflow_dispatch:

1
2

*示例5：在 workflow: ci.yml 完成之后运行

on:
  workflow_run:
    workflows: [ci]
    types:
      - completed

1
2
3
4
5

Running a workflow based on the conclusion of another workflow

通过 github.event.workflow_run.conclusion 的值为 success 或 failure 可以知道 workflow_run 指定的 workflows 执行成功还是失败。

if: $${{ github.event.workflow_run.conclusion == 'success' }}

就可以实现在某个workflow执行成功之后，再执行。具体看这里 (opens new window)

# `env`

含义：可用于设置 workflow 中的环境变量，一般用于设置运行时需要的数据，以便其他步骤或者脚本能够使用
示例：

env:
  TOKEN: ${{ secrets.ACCESS_TOKEN }}

1
2

# `jobs`

含义：表示要执行的一项或多项任务。

# `jobs.<job_id>`

含义：job_id 是 job 的唯一标识，必须以 字母 或 _ 开头，并且只包含 字母、- 或 _。

# `jobs.<job_id>.name`

含义 name 字段是任务的名称，显示在 github 上。
示例：

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

1
2
3
4
5

jobs 包含两项任务，分别是 job_id 为 my_first_job 的任务和 job_id 为 my_second_job 的任务

# `jobs.<job_id>.needs`

含义: needs 字段指定当前任务的依赖关系，即运行顺序。
示例1：指定在某个 job 成功 执行完成之后执行

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

1
2
3
4
5
6

job2 需要在 job1 成功执行完之后才会执行，而 job3 需要在 job1、job2 成功执行完之后才会执行。

示例2：指定在某个 job 执行完成之后执行，不管它是否成功。

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

1
2
3
4
5
6
7

job3 使用 always() (opens new window) 条件表达式，总是在 job1、job2 完成之后执行，不管它们是否成功。

# `jobs.<job_id>.runs-on`

含义：runs-on 字段指定运行任务所需要的虚拟机环境，它是必填字段。一般使用 ubuntu-latest、windows-latest、macos-latest 虚拟机即可。
示例：

runs-on: ubuntu-latest

# `jobs.<job_id>.steps`

含义：steps 字段指定每个 Job 的运行步骤，可以包含一个或多个步骤。每个步骤下又有很多字段，具体看这里 (opens new window)。
示例1：

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

name: 步骤名字
env: 环境变量，这些变量只能在该步骤中用
run: 要执行的命令或脚本，| 是换行的意思

上面 workflow 中，steps 字段只包括一个步骤。该步骤先注入四个环境变量，然后执行一条 Bash 命令，然后执行一条 Bash 命令输出 Hi there! My name is Mona The Octocat

示例2：github-pages-deploy-action (opens new window)

name: Build and Deploy
on:
  push:
    branches:
      - main
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v2

      - name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
        run: |
          npm install
          npm run build

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4.2.5
        with:
          branch: gh-pages # The branch the action should deploy to.
          folder: docs/.vuepress/dist # The folder the action should deploy.

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

uses: 使用别人写好的 action 作为我们的一个 step 来执行
with: 要传给所使用 action 的参数

上面 workflow 中，steps 字段包含三个步骤:

第一个步骤使用官方提供的action, 作用是拉取本仓库的代码
第二个步骤执行两条命令, 作用是构建打包第一步拉取的代码
第三个步骤是将第二步打包生成的文件推送到本仓库的 gh-pages 分支下, 即将你的网页部署到 Github Pages

提示

JamesIves/github-pages-deploy-action (opens new window) 从 V4 版本开始默认使用仓库登录的 token。
如果你只是部署到脚本所在仓库的 gh-pages下，不需要添加 token，如果添加会报 128 错误。
如果你需要部署到其他仓库，需要提供 token，将token存放在仓库的 Settings/secrets/actions 下, 名字设置为: ACCESS_TOKEN。

...
with:
  token: ${{ secrets.ACCESS_TOKEN }}

1
2
3

# 实例演示

请看本站部署

编辑此页

#GitHub

上次更新: 2022/02/26, 20:06:42

← GitHub Token git日常错误及解决办法→

GitHub Actions 入门教程

# 前言

# 基本概念

# workflow 文件

# name

# on

# env

# jobs

# jobs.<job_id>

# jobs.<job_id>.name

# jobs.<job_id>.needs

# jobs.<job_id>.runs-on

# jobs.<job_id>.steps