👋 We've unified all of GitHub's product documentation in one place! Check out the content for REST API, GraphQL API, and Developers. Learn more on the GitHub blog.


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

配置工作流程

您可以创建自定义工作流程来实现项目软件开发周期流程的自动化。

GitHub 操作 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 GitHub 操作 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 更多信息请参阅“GitHub 的产品”。

本文内容

对仓库具有写入或管理员权限的人员可以创建、编辑或查看工作流程。

关于工作流程

工作流程是您可以在仓库中创建的自定义自动化流程,用于在 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/workflows含有无效的工作流程文件,则 GitHub 操作 将为每次新提交生成失败的工作流程运行。

通过事件触发工作流程

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

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

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

name: descriptive-workflow-name
on: push

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

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

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

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

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

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

例如,在 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"。

选择运行器

您可以在 GitHub 托管的运行器或自托管运行器上运行工作流程。 作业可以直接在机器或 Docker 容器中运行。

您可以使用 runs-on 指定工作流程中每项作业的运行器。 有关 runs-on 的更多信息,请参阅“GitHub 操作 的工作流程语法”。

使用 GitHub 托管的运行器

您可以选择不同类型和版本的虚拟主机,包括 Linux、Windows 和 macOS。 工作流程中的每项作业都在虚拟环境的新实例中执行,作业中的步骤可以使用文件系统共享信息。 更多信息请参阅“GitHub 操作 托管的运行器的虚拟环境”。

例如,您可以使用 ubuntu-later 指定 Ubuntu GitHub 托管的运行器的最新版本。

runs-on: ubuntu-latest

使用自托管的运行器

您可以使用标签将作业路由到特定类型的自托管运行器。 所有自托管的运行器都将获得 self-hosted 标签,且每个自托管的运行器都有其操作系统和系统架构的标签。 更多信息请参阅“在工作流程中使用自托管的运行器”。

例如,如果您添加了使用 Linux 操作系统和 ARM32 架构的自托管运行器, 您可以使用 self-hostedlinuxARM32 标签选择该运行器。

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

配置构建矩阵

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

构建矩阵允许您用不同的软件和操作系统配置测试代码。 例如,工作流程可为多个支持的语言、操作系统或工具版本运行作业。 对于每项配置,将运行作业的副本并报告状态。

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

定义操作系统矩阵时,必须将 runs-on 的值设置为您定义的 matrix.os 上下文属性。

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 操作 的工作流程语法”。

You can also enable GitHub Dependabot 版本更新 for the actions that you add to your workflow. For more information, see "Keeping your actions up to date with GitHub Dependabot."

有关配置选项的更多详细信息,请参阅“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 中使用 branchevent 查询参数显示特定分支或事件运行的工作流程状态。

如果您的工作流程使用 name 关键词,则必须按名称引用工作流程。 如果工作流程名称包含空格,您需要将空格替换为 URL 编码字符串 %20。 有关 name 关键词的更多信息,请参阅“GitHub 操作 的工作流程语法”。

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

或者,如果工作流程没有 name,则必须使用相对于仓库根目录的文件路径引用工作流程文件。

注意:如果工作流程具有 名字,则无法使用文件路径引用工作流程文件。

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

使用工作流程名称的示例

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

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

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

此 Markdown 示例为文件路径为 .github/workflows/main.yml 的工作流程添加状态徽章。 仓库的 OWNERactions 组织,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)

延伸阅读

问问别人

找不到要找的内容?

联系我们