我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

配置工作流程

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

GitHub 操作 is currently in limited public beta and is subject to change. We strongly recommend that you do not use this feature for high-value workflows and content during the beta period.

For more information, see "About GitHub 操作."

本文内容

关于工作流程

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

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

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

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

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

标注的工作流程运行映像

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

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

创建工作流程文件

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

  1. 在仓库根目录的新目录 .github/workflows 中新建文件 .yml。 例如 .github/workflows/continuous-integration-workflow.yml

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

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

工作流程文件示例

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

jobs:
  build:
    # Job name is Greeting
    name: Greeting
    # This job runs on Linux
    runs-on: ubuntu-latest
    steps:

    - uses: actions/checkout@v1
    # This step uses the hello-world-action stored in this workflow's repository.
    - uses: ./hello-world-action
      with:
        who-to-greet: 'Octocat'
      id: hello
    # This step prints the time.
    - run: echo "The time was ${{ steps.hello.outputs.time }}"

通过事件触发工作流程

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

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

name: descriptive-workflow-name
on: push

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

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

要在外部事件发生后触发工作流程,您可以呼叫“创建仓库分发事件”REST API 端点来调用 repository_dispatch web 挂钩事件。 For more information, see "Create a repository dispatch event" in GitHub 开发者文档.

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

过滤特定分支

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

例如,此工作流程在 master 分支上发生推送时运行。

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

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

选择虚拟环境

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

要指定想在其中运行工作流程的虚拟环境的操作系统、工具、软件包和设置,必须在工作流程文件中使用特殊语法。

更多信息请参阅“GitHub 操作 的虚拟环境”。

虚拟主机

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

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

runs-on: ubuntu-18.04

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

配置构建矩阵

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

构建矩阵提供不同的配置供虚拟环境测试。 例如,工作流程可为多个支持的语言、操作系统或工具版本运行作业。 对于每项配置,将运行作业的副本并报告状态。

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

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

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

使用检出操作

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

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

<br />- uses: actions/checkout@v1

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

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

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

更多信息请参阅检出操作

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

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

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

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

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

在工作流程中引用操作

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

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

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

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

有关配置选项的更多详细信息,请参阅“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 语法引用操作。

示例仓库文件结构:

.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 操作仓库

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

延伸阅读

问问别人

找不到要找的内容?

联系我们