5 GitHub Actions 手册

学习资源：

• GitHub 帮助
• 关于自述文件
• 忽略文件
• actions / starter-workflows
• sdras / awesome-actions

学习 Actions

记录学习 Github Actions 的笔记。

学习资料：使用 GitHub 操作 自动化工作流程

1 GitHub 操作使用入门

GitHub 操作 可让您直接在 GitHub 仓库中创建自定义的软件开发生命周期工作流程。GitHub 操作的核心概念：

• Workflow：工作流程是您可以在仓库中创建的自定义自动化的流程，用于在 GitHub 上构建、测试、封装、发行或部署任何代码项目。Workflows 由一个或者多个 jobs 组成 并且可以借由 event 部署和激活。
• Workflow run：workflow 的一个在 pre-configured event 发生时运行的实例。您可以看到每个工作流运行的作业、操作、日志和状态。
• Workflow file：使用至少一个作业定义的工作流配置（configuration）的 YAML 文件。此文件位于 GitHub 存储库的根目录中的 .github/workflows 位置。
• Job：作业（或称为任务）是由 step 组成的 task 定义。每个作业均在虚拟环境的新实例中运行。您可以定义工作流文件中作业的运行方式的依赖项规则。作业可以并行运行，也可以依赖于上一个作业的状态，按顺序运行。例如，工作流可以有两个顺序作业： build 和 test，其中测试作业取决于生成作业的状态。如果生成作业失败，则测试作业将不会运行。
• Step：步骤是作业执行的一组任务。作业中的每个步骤都在同一虚拟环境中执行，允许该作业中的操作使用文件系统共享信息。步骤可以通过 commands 或者 actions 运行。
• Action：操作作为创建作业的步骤合并的独立任务。操作是工作流中最小的可移植构建基块。您可以创建自己的操作，使用从 GitHub 社区共享的操作，以及自定义公共操作。要在工作流中使用操作，必须将其作为步骤包含在内。
• Continuous integration (CI)：持续集成通过提供有关代码更改的即时反馈来更快地检测和解决 Bug，从而节省了开发人员的时间。
• Continuous deployment (CD)：持续部署基于持续集成。提交新代码并通过 CI 测试时，代码将自动部署到生产中。使用 GitHub ，您可以创建自定义 CD 工作流，以自动将代码部署到存储库中的任何云、自托管服务或平台。CD 通过自动化部署过程并更快地向客户部署经过测试、稳定的代码更改来节省开发人员的时间。
• Virtual environment：GitHub 托管（hosts） Linux、macOS 和 Windows 虚拟环境以运行工作流。
• Runner：在每个虚拟环境中等待可用作业的 GitHub 服务，当 Runner 拾取作业时，它将运行作业的操作，并将进度、日志和最终结果报告回 GitHub。Runner 一次运行一个作业。
• Event：触发（triggers）工作流运行的特定活动。例如，当有人将提交推送到存储库或创建问题或拉取请求时，活动可能来自 GitHub。您还可以将工作流配置为在使用存储库调度 Webhook 发生外部事件时运行。
• Artifact：项目（构件或工件）是生成（build）和测试（test）代码时创建的文件。例如，项目可能包括二进制文件或包文件、测试结果、屏幕截图或日志文件。项目与创建项目的位置的工作流运行相关联，并且可以由其他作业使用或部署。

2 配置 worflow

如果您对某仓库具有写入或管理员权限，您可以创建、查看或编辑该仓库的工作流程。您可以根据工作流程中包含的操作类型自定义工作流程配置。

您可以在仓库中创建多个工作流程，但是必须将工作流程存储在仓库根目录的 .github/workflows 目录中。

工作流程必须至少有一项作业，并且作业包含一组用于执行个别任务的步骤。 步骤可以运行命令或使用操作。

您可以配置工作流程在 GitHub 事件发生时开始，按时间表开始，或者由外部事件触发。

您需要使用 YAML 语法配置工作流程，并将其在仓库中存储为工作流程文件。 在成功创建 YAML 工作流程文件并触发工作流程后，您会看到工作流程每个步骤的创建日志、测试结果、构件和状态。

2.1 创建工作流程文件

添加工作流程文件的步骤如下：

• 在仓库根目录创建目录 .github/workflows 并在此目录下新建文件 .yml。 例如 .github/workflows/continuous-integration-workflow.yml。
• 使用“GitHub 操作 的工作流程语法”参考文档选择可触发操作的事件、添加操作以及自定义工作流程。
• 将您在工作流程文件中的更改提交到您希望其中运行工作流程的分支。

2.1.1 通过事件触发工作流程

事件：

• GitHub 上的事件，例如有人推送提交到仓库或者创建议题或拉取请求时。
• 安排或计划的事件。
• 外部事件发生。

要在 GitHub 上通过事件触发工作流程，请在工作流程名称后面添加 on:（指定触发 workflow 的条件，通常是某些事件）和事件值（如 push）。例如，工作流程在更改推送到仓库中的任何分支时触发：

name: descriptive-workflow-name
on: push

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

on: [push, pull_request]

要计划工作流程的运行，可以在工作流程文件中使用 POSIX cron 语法。 例如，工作流程每小时触发一次：

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
  - cron:  '0 * * * *'

下面的例子表示设定 workflow 运行的时间为周一至周五的 2:00 UTC 时间：

on:
  schedule:
  - cron: "0 2 * * 1-5"

要在外部事件发生后触发工作流程，您可以回调“创建仓库分发事件”REST API 端点来调用 repository_dispatch web 挂钩事件。 更多信息参阅 "Create a repository dispatch event" in GitHub 开发者文档。

更多信息和示例请参阅“触发工作流程的事件”。

2.1.2 过滤特定分支

您可以设置工作流程仅在特定分支上运行。

例如，工作流程限定在 master 分支上发生推送时运行：

on:
  push:
    branches:
    - master
    # file paths to consider in the event. Optional; defaults to all.
    paths:
      - test/*

有关在工作流程中引用分支的更多信息，请参阅“GitHub 操作 的工作流程语法”。

2.1.3 选择虚拟环境

您可以在 GitHub 托管的虚拟机上或者 Docker 容器中运行工作流程。可以为工作流程中的每项作业指定虚拟环境。

要指定想在其中运行工作流程的虚拟环境的操作系统、工具、软件包和设置，必须在工作流程文件中使用特殊语法。更多信息请参阅“GitHub 操作 的虚拟环境”。

您可以选择不同类型和版本的虚拟主机，包括 Ubuntu、Linux 和 macOS。 工作流程中的每项作业在同一虚拟环境中执行，让该作业中的操作使用文件系统共享信息。

要在全新的虚拟环境实例上运行作业，可以指定虚拟主机运行作业：

runs-on: ubuntu-18.04

有关详细信息，包括支持的版本，请参阅“GitHub 操作 的工作流程语法”。

2.1.4 配置构建矩阵

要同时在多个操作系统、平台和语言版本上测试，可以配置构建矩阵。构建矩阵提供不同的配置供虚拟环境测试。 例如，工作流程可为多个支持的语言、操作系统或工具版本运行作业。对于每项配置，将运行作业的副本并报告状态。您可以使用矩阵在 strategy: 下列出配置选项，在工作流程文件中指定构建矩阵。

例如，构建矩阵将通过不同版本的 Node.js、Ubuntu 和 Linux 操作系统运行作业：

strategy:
  matrix:
    node: [6, 8, 10]
    os: [ubuntu-14.04, ubuntu-18.04]

2.1.5 使用检出（checkout）操作

在工作流程中可以使用多个标准操作。检出操作是标准操作，在以下情况下，在工作流程中必须位于其他操作前面：

• 工作流程需要仓库代码的副本，比如在创建并测试仓库或使用持续集成时。
• 工作流程中至少有一项操作在同一仓库中定义。 更多信息请参阅“在工作流程中引用操作”。

要使用标准检出操作而不做进一步的指定，请包含此步骤：

- uses: actions/checkout@v1

此示例中使用 v1 确保您使用检出操作的稳定版本。

要浅层克隆仓库，或者只复制仓库的最新版本，请使用 with 语法设置 fetch-depth：

- uses: actions/checkout@v1
  with:
    fetch-depth: 1

更多信息请参阅检出操作。

2.1.6 选择用于工作流程的操作类型

您可以根据项目需求在工作流程中使用不同类型的操作：

• Docker 容器操作
• JavaScript 操作

更多信息请参阅“关于操作”。

选择要在工作流程中使用的操作类型时，建议探索公共仓库中或 Docker Hub 上的现有操作，并根据需要为项目自定义这些操作。

您可以在 github.com/actions 组织中找到并使用 GitHub 创建的操作。 要访问 Docker Hub，请参阅 Docker 网站上的“Docker Hub”。

2.1.7 在工作流程中引用操作

要在工作流程文件中使用正确的语法引用操作，必须考虑定义操作的位置。工作流程可以使用以下位置定义的操作：

• 公共仓库
• 工作流程文件引用操作的同一仓库
• Docker Hub 上发布的 Docker 容器图像

要使用私人仓库中定义的操作，工作流程文件和操作必须在同一仓库中。您的工作流程不能使用在其他私人仓库中定义的操作，即使该仓库在同一组织中。为使工作流程在操作有更新时也保持稳定，您可以在工作流程文件中指定 Git 引用或 Docker 标记号以引用所用操作的版本。

从公共仓库引用操作：如果操作定义在公共仓库中，必须使用语法 {owner}/{repo}@{ref} 或 {owner}/{repo}/{path}@{ref} 引用操作。

jobs:
   my_first_job:
       name: My Job Name
       steps:
       - uses: actions/setup-node@v1
        with:
          node-version: 10.x

要查看完整的工作流程示例，请参阅设置节点模板仓库。下面简单列出一些说明：

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

再看一个完整的例子：

name: Greet Everyone
# This workflow is triggered on pushes to the repository.
on: [push]

jobs:
  build:
    # 作业名称为 Greeting
    name: Greeting
    # 此作业在 Linux 上运行
    runs-on: ubuntu-latest
    steps:
      # 此步骤使用 GitHub 的 hello-world-javascript-action：https://github.com/actions/hello-world-javascript-action
      - name: Hello world
        uses: actions/hello-world-javascript-action@v1
        with:
          who-to-greet: 'Mona the Octocat'
        id: hello
      # 此步骤打印上一步操作的输出（时间）。
      - name: Echo the greeting's time
        run: echo 'The time was ${{ steps.hello.outputs.time }}.'

在工作流程文件使用操作的同一仓库中引用操作：如果操作在工作流程文件使用该操作的同一仓库中定义，您可以在工作流程文件中通过 ‌{owner}/{repo}@{ref} 或 ./path/to/dir 语法引用操作。

示例仓库文件结构：

.github
└── workflows
    └── my-first-workflow.yml
.
└── hello-world-action
    └── action.yml

示例工作流程文件：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    # This step checks out a copy of your repository.
    - uses: actions/checkout@v1
    # This step references the directory that contains the action.
    - uses: ./hello-world-action

引用 Docker Hub 上的容器：如果操作在 Docker Hub 上发布的 Docker 容器的镜像中定义，您必须在工作流程文件中通过 docker://{image}:{tag} 语法引用操作。为保护代码和数据，强烈建议先验证 Docker Hub 中 Docker 容器镜像的完整性后再将其用于工作流程。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

有关 Docker 操作的部分示例，请参阅 Docker-image.yml 工作流程或 Docker 操作仓库。

2.2 创建多个任务的 workflow

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

jobs 字段里面，需要写出每一项任务的 job_id，具体名称自定义。job_id 里面的 name 字段是任务的说明。比如：

jobs:
  first_job:
    name: My first job
  second_job:
    name: My second job

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

有时，我们需要创建有依赖关系的任务，此时需要借助 needs 字段：

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

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

2.3 将工作流程状态徽章添加到您的仓库

状态徽章显示工作流程目前失败还是通过。 添加状态徽章的常见位置是仓库的 README.md 文件，但也可将其添加到您喜欢的任何网页。 徽章显示默认分支（通常是 master）的状态。 您也可以在 URL 中使用 branch 和 event 查询参数显示特定分支或事件运行的工作流程状态。具体的格式：

https://github.com///workflows//badge.svg

2.4 为操作创建自述文件

如果计划公开分享您的操作，建议创建自述文件以帮助人们了解如何使用您的操作。 您可以将此信息包含在 README.md 中：

• 操作的详细描述
• 必要的输入和输出变量
• 可选的输入和输出变量
• 操作使用的密码
• 操作使用的环境变量
• 如何在工作流程中使用操作的示例

配置工作流程：

• 配置工作流程
• 管理工作流程运行
• GitHub 操作的工作流程语法
• 触发工作流程的事件
• GitHub 操作的虚拟环境
• Software in virtual environments for GitHub Actions
• Contexts and expression syntax for GitHub Actions

构建操作

• 关于操作
• Metadata syntax for GitHub Actions
• GitHub 操作的开发工具

在 GitHub 上设置持续集成

• 关于持续集成
• 使用 GitHub 操作设置持续集成