配置工作流程

People with write or admin permissions to a repository can create, edit, or view workflows.

关于工作流程

工作流程是您可以在仓库中创建的自定义自动化流程，用于在 GitHub 上构建、测试、封装、发行或部署任何项目。 通过工作流程可以利用广泛的各种工具和服务自动化软件开发生命周期。 更多信息请参阅“关于 GitHub 操作”。

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

工作流程必须至少有一项作业，并且作业包含一组用于执行个别任务的步骤。 步骤可以运行命令或使用操作。 您可以创建自己的操作，或者使用 GitHub 社区共享的操作并根据需要自定义。

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

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

您也可以接收工作流程状态更新的通知。 有关通知选项的更多信息，请参阅“选择通知的递送方式”。

使用限制应用到个别工作流程。 更多信息请参阅“工作流程的使用限制”。

创建工作流程文件

简言之，添加工作流程文件的步骤如下。 您可以在后面的章节中查找具体的配置示例。

1. 在仓库的根目录，创建名为 .github/workflows 的目录以存储工作流程文件。

2. 在 .github/workflows 中，为您的工作流程添加 .yml 或 .yaml 文件。 例如 .github/workflows/continuous-integration-workflow.yml。

3. 使用“GitHub 操作 的工作流程语法”参考文档选择可触发操作的事件、添加操作以及自定义工作流程。

4. 将您在工作流程文件中的更改提交到您希望其中运行工作流程的分支。

工作流程文件示例

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 }}.'

通过事件触发工作流程

您可以配置工作流程以下事件发生后开始：

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

要在 GitHub 上的事件发生后触发工作流程，请在工作流程名称后面添加 on: 和事件值。 例如，此工作流程在更改推送到仓库中的任何分支时触发。

name: descriptive-workflow-name
on: push

要计划工作流程的运行，可以在工作流程文件中使用 POSIX cron 语法。 您可以运行预定工作流程的最短间隔是每 5 分钟一次。 例如，此工作流程每小时触发一次。

on:
  schedule:
    - cron:  '0 * * * *'

要在外部事件发生后触发工作流程，您可以呼叫“创建仓库分发事件”REST API 端点来调用 repository_dispatch web 挂钩事件。 更多信息请参阅 GitHub 开发者文档 中的“创建仓库分发事件”。

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

过滤特定分支、标记和路径

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

例如，在 master 分支上进行包含 test 目录中文件的推送或推送到 v1 标记时，此工作流程运行。

on:
  push:
    branches:
      - master
    tags:
      - v1
    # 事件中要考虑的文件路径。 Optional; defaults to all.
    paths:
      - 'test/*'

有关分支、标记和路径过滤语法的更多详细，请参阅 "on.<push|pull_request>.<branches|tags>" 和 "on.<push|pull_request>.paths"。

Choosing a runner

You can run workflows on GitHub-hosted runners or self-hosted runners. Jobs can run directly on the machine or in a Docker container.

You can specify the runner for each job in a workflow using runs-on. For more information about runs-on, see "Workflow syntax for GitHub 操作."

Using a GitHub-hosted runner

您可以选择不同类型和版本的虚拟主机，包括 Linux、Windows 和 macOS。 Each job in a workflow executes in a fresh instance of the virtual environment, and steps within a job can share information using the filesystem. For more information, see "Virtual environments for GitHub 操作-hosted runners."

For example, you can use ubuntu-latest to specify the latest version of an Ubuntu GitHub-hosted runner.

runs-on: ubuntu-latest

Using a self-hosted runner

If you've added self-hosted runners to your repository, you can specify a self-hosted runner using labels. All self-hosted runners get the self-hosted label and each self-hosted runner has labels for its operating system and system architecture. For more information, see "Using self-hosted runners in a workflow."

For example, if you added a self-hosted runner with a Linux operating system and ARM32 architecture, you can select that runner using the self-hosted, linux, and ARM32 labels.

runs-on: [self-hosted, linux, ARM32]

配置构建矩阵

要同时在多个操作系统、平台和语言版本上测试，可以配置构建矩阵。

A build matrix allows you to test your code with different software and operating system configurations. 例如，工作流程可为多个支持的语言、操作系统或工具版本运行作业。 对于每项配置，将运行作业的副本并报告状态。

您可以使用矩阵在 strategy: 下列出配置选项，在工作流程文件中指定构建矩阵。 例如，此构建矩阵将通过不同版本的 Node.js、Ubuntu 和 Linux 操作系统运行作业。

When you define a matrix of operating systems, you must set the value of runs-on to the matrix.os context property you defined.

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-16.04, ubuntu-18.04]
    node: [6, 8, 10]

更多信息请参阅“GitHub 操作 的工作流程语法”。

使用检出操作

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

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

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

- uses: actions/checkout@v2

此示例中使用 v2 确保您使用检出操作的稳定版本。 更多信息请参阅检出操作。

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

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

• Docker 容器操作
• JavaScript 操作

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

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

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

在工作流程中引用操作

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

工作流程可以使用以下位置定义的操作：

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

要使用私人仓库中定义的操作，工作流程文件和操作必须在同一仓库中。 您的工作流程不能使用在其他私人仓库中定义的操作，即使该仓库在同一组织中。

为使工作流程在操作有更新时也保持稳定，您可以在工作流程文件中指定 Git 引用或 Docker 标记号以引用所用操作的版本。 有关示例，请参阅“GitHub 操作 的工作流程语法”。

For more detailed configuration options, see "Workflow syntax for GitHub 操作."

从公共仓库引用操作

如果操作定义在公共仓库中，必须使用语法 {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

要查看完整的工作流程示例，请参阅设置节点模板仓库。

在工作流程文件使用操作的同一仓库中引用操作

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

示例仓库文件结构：

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

示例工作流程文件：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - uses: actions/checkout@v2
      # This step references the directory that contains the action.
      - uses: ./.github/actions/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 容器操作”。

更多信息请参阅“GitHub 操作 的工作流程语法”。

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

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

If your workflow uses the name keyword, you must reference the workflow by name. 如果工作流程名称包含空格，您需要将空格替换为 URL 编码字符串 %20。 有关 name 关键词的更多信息，请参阅“GitHub 操作 的工作流程语法”。

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg

Alternatively, if your workflow doesn't have a name, you must reference the workflow file using the file path relative to the repository's root directory.

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_FILE_PATH>/badge.svg

使用工作流程名称的示例

此 Markdown 示例为名为 "Greet Everyone" 的工作流程添加状态徽章。仓库的 OWNER 为 actions 组织，REPOSITORY 名称为 hello-world。

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg)

使用工作流程文件路径的示例

此 Markdown 示例为文件路径为 .github/workflows/main.yml 的工作流程添加状态徽章。 仓库的 OWNER 为 actions 组织，REPOSITORY 名称为 hello-world。

![](https://github.com/actions/hello-world/workflows/.github/workflows/main.yml/badge.svg)

使用 branch 参数的示例

此 Markdown 示例为名为 feature-1 的分支添加状态徽章。

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg?branch=feature-1)

使用 event 参数的示例

此 Markdown 示例添加显示通过 pull_request 事件触发运行的工作流程状态的徽章。

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg?event=pull_request)

延伸阅读

• "Managing billing for GitHub 操作"