关于工作流

一个**工作流**是一个可配置的自动化流程，它将运行一个或多个作业。工作流由签入到存储库的 YAML 文件定义，并在存储库中发生事件时触发运行，也可以手动触发或按定义的计划触发。

工作流在存储库的.github/workflows目录中定义。一个存储库可以有多个工作流，每个工作流都可以执行不同的任务集，例如

构建和测试拉取请求。
每次创建发行版时部署您的应用程序。
每当打开新问题时添加标签。

工作流基础

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

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

有关这些基本组件的更多信息，请参阅“了解 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 提供预配置的工作流模板，您可以按原样使用这些模板或对其进行自定义以创建自己的工作流。GitHub 会分析您的代码并向您显示可能对您的存储库有用的工作流模板。例如，如果您的存储库包含 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:20-bookworm-slim
    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 Actions

本文内容