关于工作流

获取 GitHub Actions 工作流的高级概述，包括触发器、语法和高级功能。

GitHub Actions 入门

学习路径中的 4/6
下一步：重用工作流

本文内容

关于工作流

工作流是一个可配置的自动化流程，它将运行一个或多个作业。工作流由签入到您的仓库的 YAML 文件定义，并在您的仓库中发生事件时触发，或者可以手动触发，或者在定义的时间表上触发。

工作流在仓库的 .github/workflows 目录中定义，一个仓库可以有多个工作流，每个工作流可以执行不同的任务集。例如，您可以有一个工作流来构建和测试拉取请求，另一个工作流在每次创建发布时部署您的应用程序，还有一个工作流在每次有人打开新问题时添加标签。

工作流基础

工作流必须包含以下基本组件

  1. 一个或多个事件，将触发工作流。
  2. 一个或多个作业，每个作业将在运行器机器上执行并运行一系列一个或多个步骤。
  3. 每个步骤可以运行您定义的脚本，也可以运行操作，操作是可重用的扩展，可以简化您的工作流。

有关这些基本组件的更多信息，请参阅“了解 GitHub Actions”。

Diagram of an event triggering Runner 1 to run Job 1, which triggers Runner 2 to run Job 2. Each of the jobs is broken into multiple steps.

触发工作流

工作流触发器是导致工作流运行的事件。这些事件可以是

  • 在您的工作流存储库中发生的事件
  • 在 GitHub 外部发生的事件，并在 GitHub 上触发 repository_dispatch 事件
  • 预定的时间
  • 手动

例如，您可以配置您的工作流，以便在将代码推送到存储库的默认分支时、在创建发布时或在打开问题时运行。

有关更多信息，请参阅“触发工作流”，以及有关事件的完整列表，请参阅“触发工作流的事件”。

工作流语法

工作流使用 YAML 定义。有关用于编写工作流的 YAML 语法的完整参考，请参阅“GitHub Actions 的工作流语法”。

创建示例工作流

GitHub Actions 使用 YAML 语法定义工作流。每个工作流都存储在代码存储库中名为 .github/workflows 的目录中的单独 YAML 文件中。

您可以在您的仓库中创建一个示例工作流，该工作流会在每次代码被推送时自动触发一系列命令。在这个工作流中，GitHub Actions 会检出推送的代码，安装 bats 测试框架，并运行一个基本命令来输出 bats 版本：bats -v。

  1. 在您的仓库中，创建 .github/workflows/ 目录来存储您的工作流文件。

  2. 在 .github/workflows/ 目录中，创建一个名为 learn-github-actions.yml 的新文件，并添加以下代码。

    YAML
    name: learn-github-actions
run-name: ${{ github.actor }} is learning GitHub Actions
on: [push]
jobs:
  check-bats-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g bats
      - run: bats -v

  3. 提交这些更改并将其推送到您的 GitHub 仓库。

现在，您的新 GitHub Actions 工作流文件已安装在您的仓库中，并且会在每次有人将更改推送到仓库时自动运行。要查看有关工作流执行历史记录的详细信息，请参阅 "查看工作流运行的活动"。

了解工作流文件

为了帮助您了解如何使用 YAML 语法创建工作流文件，本节将解释介绍示例中的每一行。

YAML
name: learn-github-actions

可选 - 工作流的名称，它将显示在 GitHub 仓库的“操作”选项卡中。如果省略此字段，则将使用工作流文件的名称。

run-name: ${{ github.actor }} is learning GitHub Actions

可选 - 从工作流生成的运行的名称，它将显示在仓库的“操作”选项卡上的工作流运行列表中。此示例使用带有 github 上下文的表达式来显示触发工作流运行的执行者的用户名。有关更多信息，请参阅 "GitHub Actions 的工作流语法"。

on: [push]

指定此工作流的触发器。此示例使用 push 事件，因此每次有人将更改推送到仓库或合并拉取请求时，都会触发工作流运行。这由对每个分支的推送触发；有关仅在对特定分支、路径或标签进行推送时运行的语法的示例，请参阅 "GitHub Actions 的工作流语法"。

jobs:

将所有在 learn-github-actions 工作流中运行的作业分组在一起。

  check-bats-version:

定义一个名为 check-bats-version 的作业。子键将定义作业的属性。

    runs-on: ubuntu-latest

将作业配置为在最新版本的 Ubuntu Linux 运行器上运行。这意味着该作业将在 GitHub 托管的新虚拟机上执行。有关使用其他运行器的语法示例，请参阅 "GitHub Actions 的工作流语法"

    steps:

将所有在 check-bats-version 任务中运行的步骤组合在一起。此部分下嵌套的每个项目都是一个单独的操作或 shell 脚本。

      - uses: actions/checkout@v4

uses 关键字指定此步骤将运行 actions/checkout 操作的 v4 版本。这是一个将您的仓库检出到运行器上的操作，允许您对代码运行脚本或其他操作（例如构建和测试工具）。只要您的工作流程使用仓库的代码，您就应该使用 checkout 操作。

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

此步骤使用 actions/setup-node@v4 操作来安装指定版本的 Node.js。（此示例使用版本 20。）这将 node 和 npm 命令都放入您的 PATH 中。

      - run: npm install -g bats

run 关键字告诉任务在运行器上执行命令。在本例中，您使用 npm 安装 bats 软件测试包。

      - run: bats -v

最后，您将使用一个参数运行 bats 命令，该参数输出软件版本。

# Optional - The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. If this field is omitted, the name of the workflow file will be used instead.
name: learn-github-actions

# Optional - The name for workflow runs generated from the workflow, which will appear in the list of workflow runs on your repository's "Actions" tab. This example uses an expression with the `github` context to display the username of the actor that triggered the workflow run. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#run-name)."
run-name: ${{ github.actor }} is learning GitHub Actions

# Specifies the trigger for this workflow. This example uses the `push` event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request.  This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see "[AUTOTITLE](/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)."
on: [push]

# Groups together all the jobs that run in the `learn-github-actions` workflow.
jobs:

# Defines a job named `check-bats-version`. The child keys will define properties of the job.
  check-bats-version:

# Configures the job to run on the latest version of an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see "[AUTOTITLE](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)"
    runs-on: ubuntu-latest

# Groups together all the steps that run in the `check-bats-version` job. Each item nested under this section is a separate action or shell script.
    steps:

# The `uses` keyword specifies that this step will run `v4` of the `actions/checkout` action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will use the repository's code.
      - uses: actions/checkout@v4

# This step uses the `actions/setup-node@v4` action to install the specified version of the Node.js. (This example uses version 20.) This puts both the `node` and `npm` commands in your `PATH`.
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

# The `run` keyword tells the job to execute a command on the runner. In this case, you are using `npm` to install the `bats` software testing package.
      - run: npm install -g bats

# Finally, you'll run the `bats` command with a parameter that outputs the software version.
      - run: bats -v

可视化工作流程文件

在此图中，您可以看到您刚刚创建的工作流程文件以及 GitHub Actions 组件如何在层次结构中组织。每个步骤执行一个单独的操作或 shell 脚本。步骤 1 和 2 运行操作，而步骤 3 和 4 运行 shell 脚本。要查找更多用于工作流程的预构建操作，请参阅“查找和自定义操作”。

Diagram showing the trigger, runner, and job of a workflow. The job is broken into 4 steps.

查看工作流程运行的活动

当您的工作流程被触发时，将创建一个执行工作流程的工作流程运行。工作流程运行开始后，您可以在 GitHub 上看到运行进度可视化图表，并查看每个步骤的活动。

  1. 在 GitHub.com 上，导航到仓库的主页。

  2. 在您的仓库名称下，单击 操作.

    Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.

  3. 在左侧边栏中，单击您要查看的工作流程。

    Screenshot of the left sidebar of the "Actions" tab. A workflow, "CodeQL," is outlined in dark orange.

  4. 从工作流程运行列表中，单击运行的名称以查看工作流程运行摘要。

  5. 在左侧边栏或可视化图表中，单击您要查看的任务。

  6. 要查看步骤的结果，请单击该步骤。

有关管理工作流程运行的更多信息，例如重新运行、取消或删除工作流程运行，请参阅“管理工作流程运行”。

使用入门工作流程

GitHub 提供预配置的入门工作流程，您可以对其进行自定义以创建自己的持续集成工作流程。GitHub 会分析您的代码并向您展示可能对您的存储库有用的 CI 入门工作流程。例如，如果您的存储库包含 Node.js 代码，您将看到针对 Node.js 项目的建议。您可以使用入门工作流程作为起点来构建自定义工作流程，也可以直接使用它们。

您可以在 actions/starter-workflows 存储库中浏览完整的入门工作流程列表。

有关使用和创建入门工作流程的更多信息，请参阅“使用入门工作流程”和“为您的组织创建入门工作流程”。

高级工作流程功能

本节简要介绍了 GitHub Actions 的一些高级功能，这些功能可以帮助您创建更复杂的工作流程。

存储密钥

如果您的工作流程使用敏感数据（例如密码或证书），您可以将这些数据保存在 GitHub 中作为密钥，然后在您的工作流程中将其用作环境变量。这意味着您将能够创建和共享工作流程，而无需将敏感值直接嵌入工作流程的 YAML 源代码中。

此示例作业演示了如何将现有密钥引用为环境变量，并将其作为参数发送到示例命令。

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Retrieve secret
        env:
          super_secret: ${{ secrets.SUPERSECRET }}
        run: |
          example-command "$super_secret"

有关更多信息，请参阅“在 GitHub Actions 中使用密钥”。

创建依赖作业

默认情况下，工作流程中的作业都同时并行运行。如果您有一个作业必须在另一个作业完成后才能运行，您可以使用needs关键字来创建此依赖关系。如果其中一个作业失败，所有依赖作业都将被跳过；但是，如果您需要作业继续执行，则可以使用if条件语句来定义这一点。

在此示例中，setup、build和test作业按顺序运行，build和test依赖于它们之前作业的成功完成。

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - run: ./setup_server.sh
  build:
    needs: setup
    runs-on: ubuntu-latest
    steps:
      - run: ./build_server.sh
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: ./test_server.sh

有关更多信息，请参阅“在工作流程中使用作业”。

使用矩阵

矩阵策略允许您在单个作业定义中使用变量，以根据变量组合自动创建多个作业运行。例如，您可以使用矩阵策略在多种语言版本或多个操作系统上测试您的代码。矩阵是使用 `strategy` 关键字创建的，该关键字接收构建选项作为数组。例如，此矩阵将使用不同的 Node.js 版本多次运行作业。

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [14, 16]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

有关更多信息，请参阅“为您的作业使用矩阵”。

缓存依赖项

如果您的作业经常重复使用依赖项，您可以考虑缓存这些文件以帮助提高性能。创建缓存后，它可用于同一存储库中的所有工作流。

此示例演示如何缓存 `~/.npm` 目录。

jobs:
  example-job:
    steps:
      - name: Cache node modules
        uses: actions/cache@v3
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-

有关更多信息，请参阅“缓存依赖项以加快工作流速度”。

使用数据库和服务容器

如果您的作业需要数据库或缓存服务，您可以使用 services 关键字创建短暂容器来托管服务；生成的容器随后可用于该作业中的所有步骤，并在作业完成后删除。此示例演示了作业如何使用 `services` 创建 `postgres` 容器，然后使用 `node` 连接到服务。

jobs:
  container-job:
    runs-on: ubuntu-latest
    container: node:10.18-jessie
    services:
      postgres:
        image: postgres
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Connect to PostgreSQL
        run: node client.js
        env:
          POSTGRES_HOST: postgres
          POSTGRES_PORT: 5432

有关更多信息，请参阅“使用容器化服务”。

使用标签路由工作流

如果您希望确保特定类型的运行器处理您的作业，您可以使用标签来控制作业的执行位置。除了 `self-hosted` 的默认标签外，您还可以将标签分配给自托管运行器。然后，您可以在 YAML 工作流中引用这些标签，确保作业以可预测的方式路由。GitHub 托管运行器具有预定义的分配标签。

此示例显示了工作流如何使用标签来指定所需的运行器。

jobs:
  example-job:
    runs-on: [self-hosted, linux, x64, gpu]

工作流仅在具有 `runs-on` 数组中所有标签的运行器上运行。作业将优先转到具有指定标签的空闲自托管运行器。如果不可用，并且存在具有指定标签的 GitHub 托管运行器，则作业将转到 GitHub 托管运行器。

要了解有关自托管运行器标签的更多信息，请参阅“使用自托管运行器标签”。

要了解有关 GitHub 托管运行器标签的更多信息，请参阅“使用 GitHub 托管运行器”。

重复使用工作流

您可以在另一个工作流中调用一个工作流。这使您可以重复使用工作流，避免重复并使您的工作流更易于维护。有关更多信息，请参阅“重复使用工作流”。

工作流程安全加固

GitHub 提供安全功能，可用于提高工作流程的安全性。您可以使用 GitHub 的内置功能来确保您收到有关您使用的操作中漏洞的通知，或自动执行更新工作流程中操作的过程。有关更多信息，请参阅“使用 GitHub 的安全功能来保护您对 GitHub Actions 的使用”。

使用环境

您可以使用保护规则和机密配置环境，以控制工作流程中作业的执行。工作流程中的每个作业都可以引用一个环境。在将引用环境的作业发送到运行器之前，必须通过为环境配置的任何保护规则。有关更多信息，请参阅“使用环境进行部署”。

上一页GitHub Actions 的基本功能下一页重复使用工作流程