Workflow syntax for GitHub Actions

About YAML syntax for workflows

Workflow files use YAML syntax, and must have either a .yml or .yaml file extension. 如果� 不熟悉 YAML 并且想要了解详细信息，请参阅“在五分钟内了解 YAML”。

You must store workflow files in the .github/workflows directory of your repository.

name

The name of your workflow. GitHub displays the names of your workflows on your repository's "Actions" tab. If you omit name, GitHub sets it to the workflow file path relative to the root of the repository.

on

若要自动触发工作流，请使用 on 定义哪些事件可以触发工作流运行。 有关可用事件的列表，请参阅“触发工作流的事件”。

可以定义单个或多个可以触发工作流的事件，或设置时间计划。 还可以将工作流的执行限制为仅针对特定文件、� �记或分支更改。 后续部分将介绍这些选项。

使用单个事件

例如，当推送到工作流存储库中的任何分支时，将运行具有以下 on 值的工作流：

on: push

使用多个事件

可以指定单个事件或多个事件。 例如，当推送到存储库中的任何分支或有人创建存储库的分支时，将运行具有以下 on 值的工作流：

on: [push, fork]

如果指定多个事件，仅需发生其中一个事件就可触发工作流。 如果触发工作流的多个事件同时发生，将触发多个工作流运行。

使用活动类型

某些事件具有活动类型，可让� 更好地控制工作流的运行时间。 使用 on.<event_name>.types 定义将触发工作流运行的事件活动类型。

例如，issue_comment 事件具有 created、edited 和 deleted 活动类型。 如果工作流在 label 事件上触发，则每当创建、编辑或� 除� �签时，它都会运行。 如果为 created 事件指定 label 活动类型，则工作流将在创建� �签时运行，但不会在编辑或� 除� �签时运行。

on:
  label:
    types:
      - created

如果指定多个活动类型，则只需要发生其中一种事件活动类型就可触发工作流。 如果触发工作流的多个事件活动类型同时发生，则将触发多个工作流运行。 例如，创建或� �记问题时，会触发以下工作流。 如果创建了一个带两个� �签的问题，则将启动三个工作流运行：一个用于创建问题的事件，另外两个用于两个� �记问题的事件。

on:
  issues:
    types:
      - opened
      - labeled

有关每个事件及其活动类型的详细信息，请参阅“触发工作流的事件”。

使用筛选器

某些事件具有筛选器，可让� 更好地控制工作流的运行时间。

例如，push 事件具有 branches 筛选器，该筛选器仅在发生目� �为与 branches 筛选器匹配的分支的推送时（而不是在发生任何推送时）运行工作流。

on:
  push:
    branches:
      - main
      - 'releases/**'

将活动类型和筛选器用于多个事件

如果为事件指定活动类型或筛选器，并且针对多个事件指定工作流触发器，则必须单独配置每个事件。 必须为所有事件附� 冒号 (:)，包括没有配置的事件。

例如，具有以下 on 值的工作流将在以下情况下运行：

• 创建� �签
• 推送到存储库中的 main 分支
• 推送到启用了 GitHub Pages 的分支

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

使用 on.<event_name>.types 定义将触发工作流运行的活动类型。 大多数 GitHub 事件由多种活动触发。 例如，当� �签为 created、edited 或 deleted 时会触发 label。 通过 types 关键词可缩小触发工作流运行的活动类型的范围。 如果只有一种活动类型可触发 Webhook 事件，则不需要 types 关键字。

可以使用事件 types 的数组。 有关每个事件及其活动类型的详细信息，请参阅“触发工作流的事件”。

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

使用 pull_request 和 pull_request_target 事件时，可以将工作流配置为仅针对面向特定分支的拉取请求运行。

如果要包含分支名称模式或同时包含和排除分支名称模式，请使用 branches 筛选器。 只希望排除分支名称时，请使用 branches-ignore 筛选器。 不能对工作流中的同一事件同时使用 branches 和 branches-ignore 筛选器。

如果同时定义 branches/branches-ignore 筛选器和 paths 筛选器，则工作流将只在这两个筛选器都满足条件时运行。

branches 和 branches-ignore 关键词接受使用 *、**、+、? 和 ! 等字符匹配多个路径名称的 glob 模式。 如果名称包含其中任一字符，而� 想要逐字匹配，则需要使用 \ 转义每个特殊字符。 有关 glob 模式的更多信息，请参阅“筛选器模式备忘清单”。

示例：包括分支

在 branches 中定义的模式� �据 Git 引用的名称进行评估。 例如，每当有针对面向以下内容拉取请求的 pull_request 事件时，以下工作流都会运行：

• 名为 main 的分支 (refs/heads/main)
• 名为 mona/octocat 的分支 (refs/heads/mona/octocat)
• 名称以 releases/ 开头的分支，如 releases/10 (refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'

示例：排除分支

当模式与 branches-ignore 模式匹配时，工作流将不会运行。 在 branches 中定义的模式� �据 Git 引用的名称进行评估。 例如，除非拉取请求面向以下内容，否则每当有 pull_request 事件时，以下工作流都会运行：

• 名为 mona/octocat 的分支 (refs/heads/mona/octocat)
• 名称匹配 releases/**-alpha 的分支，如 releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'

示例：包括和排除分支

不能在单个工作流中使用 branches 和 branches-ignore 筛选同一事件。 如果要同时包括和排除单个事件的分支模式，请使用 branches 筛选器以及 ! 字符来指示应排除哪些分支或� �记。

如果使用字符 ! 定义分支，则还必须至少定义一个没有 ! 字符的分支。 如果只想排除分支，请改用 branches-ignore。

您定义模式事项的顺序。

• 肯定匹配后的匹配否定模式（前缀为 !）将排除 Git 引用。
• 否定匹配后的匹配肯定模式将再次包含 Git 引用。

以下工作流将在针对面向 releases/10 或 releases/beta/mona 的拉取请求的 pull_request 事件上运行，但不针对面向 releases/10-alpha 或 releases/beta/3-alpha 的拉取请求，由于负模式，!releases/**-alpha 将遵循正模式。

on:
  pull_request:
    branches:    
      - 'releases/**'
      - '!releases/**-alpha'

on.push.<branches|tags|branches-ignore|tags-ignore>

使用 push 事件时，可以将工作流配置为在特定分支或� �记上运行。

如果要包含分支名称模式或要同时包含和排除分支名称模式，请使用 branches 筛选器。 只希望排除分支名称时，请使用 branches-ignore 筛选器。 不能对工作流中的同一事件同时使用 branches 和 branches-ignore 筛选器。

如果要包含� �记名称模式或要同时包含和排除� �记名称模式，请使用 tags 筛选器。 只需要排除� �记名称模式时，请使用 tags-ignore 筛选器。 不能对工作流中的同一事件同时使用 tags 和 tags-ignore 筛选器。

如果仅定义 tags/tags-ignore 或 branches/branches-ignore，则工作流不会针对影响未定义的 Git ref 的事件运行。如果两者 tags/tags-ignore 或 branches/branches-ignore 均未定义，则工作流将针对影响分支或� �记的事件运行。 如果� 同时定义 branches/branches-ignore 筛选器和 paths 筛选器，则工作流将只在这两个筛选器都满足条件时运行。

branches、branches-ignore、tags 和 tags-ignore 关键词接受使用 *、**、+、? 和 ! 等字符匹配多个分支或� �记名称的 glob 模式。 如果名称包含其中任一字符，而� 想要逐字匹配，则需要使用 \ 转义每个特殊字符。 有关 glob 模式的更多信息，请参阅“筛选器模式速查表”。

示例：包括分支和� �记

在 branches 和 tags 中定义的模式� �据 Git ref 的名称进行评估。 例如，当以下项出现 push 事件时，将运行以下工作流：

• 名为 main 的分支 (refs/heads/main)
• 名为 mona/octocat 的分支 (refs/heads/mona/octocat)
• 名称以 releases/ 开头的分支，如 releases/10 (refs/heads/releases/10)
• 名为 v2 的� �记 (refs/tags/v2)
• 名称以 v1. 开头的� �记，如 v1.9.1 (refs/tags/v1.9.1)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:        
      - v2
      - v1.*

示例：排除分支和� �记

当某个模式与 branches-ignore 或 tags-ignore 模式匹配时，工作流将不会运行。 在 branches 和 tags 中定义的模式� �据 Git ref 的名称进行评估。 例如，只要出现 push 事件，就会运行以下工作流，除非以下项出现 push 事件：

• 名为 mona/octocat 的分支 (refs/heads/mona/octocat)
• 名称与 releases/**-alpha 匹配的分支，如 beta/3-alpha (refs/releases/beta/3-alpha)
• 名为 v2 的� �记 (refs/tags/v2)
• 名称以 v1. 开头的� �记，如 v1.9 (refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:        
      - v2
      - v1.*

示例：包括和排除分支和� �记

不能在一个工作流中使用 branches 和 branches-ignore 筛选同一事件。 同� �，不能在一个工作流中使用 tags 和 tags-ignore 筛选同一事件。 如果要同时包括和排除一个事件的分支或� �记模式，请使用 branches 或 tags 筛选器以及 ! 字符来指示应排除哪些分支或� �记。

如果使用字符 ! 定义分支，则还必须至少定义一个没有 ! 字符的分支。 如果只想排除分支，请改用 branches-ignore。 同� �，如果使用字符 ! 定义� �记，则还必须至少定义一个没有 ! 字符的� �记。 如果只想排除� �记，请改用 tags-ignore。

您定义模式事项的顺序。

• 肯定匹配后的匹配否定模式（前缀为 !）将排除 Git 引用。
• 否定匹配后的匹配肯定模式将再次包含 Git 引用。

以下工作流将在推送到 releases/10 或 releases/beta/mona 时运行，但不在推送到 releases/10-alpha 或 releases/beta/3-alpha 时运行，� 为否定模式 !releases/**-alpha 遵循肯定模式。

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

使用 push 和 pull_request 事件时，可以配置工作流以� �据更改的文件路径运行。 路径筛选器不会针对� �记的推送进行评估。

如果想要包括文件路径模式或想要同时包括和排除文件路径模式，请使用 paths 筛选器。 如果只想排除文件路径模式，请使用 paths-ignore 筛选器。 不能对工作流中的同一事件同时使用 paths 和 paths-ignore 筛选器。

如果同时定义 branches/branches-ignore 筛选器和 paths 筛选器，则工作流将只在这两个筛选器都满足条件时运行。

paths 和 paths-ignore 关键字接受使用 * 和 ** 通配符匹配多个路径名的 glob 模式。 有关详细信息，请参阅“筛选器模式备忘单”。

示例：包括路径

如果至少一个路径与 paths 筛选器中的模式匹配，则工作流将运行。 例如，只要推送 JavaScript 文件 (.js)，就会运行以下工作流。

on:
  push:
    paths:
      - '**.js'

示例：排除路径

当所有路径名称匹配 paths-ignore 中的模式时，工作流不会运行。 如果任何路径名与 paths-ignore 中的模式不匹配，即使某些路径名与模式匹配，工作流也会运行。

具有以下路径筛选器的工作流将仅在 push 事件上运行，这些事件包括至少一个位于存储库� �目录的 docs 目录外的文件。

on:
  push:
    paths-ignore:
      - 'docs/**'

示例：包括和排除路径

不能在单个工作流中使用 paths 和 paths-ignore 筛选同一事件。 如果要同时包括和排除单个事件的路径模式，请使用 paths 筛选器和 ! 字符来指示应排除哪些路径。

如果使用 ! 字符定义路径，则还必须定义至少一个不带 ! 字符的路径。 如果只想排除路径，请改用 paths-ignore。

您定义模式事项的顺序：

• 肯定匹配后的匹配否定模式（前缀为 !）将排除路径。
• 否定匹配后的匹配肯定模式将再次包含路径。

只要 push 事件包括 sub-project 目录或其子目录中的文件，此示例就会运行，除非该文件在 sub-project/docs 目录中。 例如，更改了 sub-project/index.js 或 sub-project/src/index.js 的推送将会触发工作流运行，但只更改 sub-project/docs/readme.md 的推送不会触发。

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Git 差异比较

筛选器通过评估更改的文件并针对 paths-ignore 或 paths 列表运行它们来确定是否应运行工作流。 如果没有更改文件，工作流程将不会运行。

GitHub 会针对推送使用双点差异，针对拉取请求使用三点差异，生成已更改文件列表：

• 拉取请求： 三点差异比较主题分支的最近版本与其中使用基本分支最新同步主题分支的提交。
• 推送到现有分支： 双点差异直接相互比较头部和基础 SHA。
• 推送到新分支： � �据已推送最深提交的上级父项的两点差异。

差异限制为 300 个文件。 如果更改的文件与过滤器返回的前 300 个文件不匹配，工作流程将不会运行。 您可能需要创建更多的特定过滤器，以便工作流程自动运行。

有关详细信息，请参阅“关于比较拉取请求中的分支”。

on.schedule

可以使用 on.schedule 定义工作流的时间计划。 可使用 POSIX cron 语法将工作流计划为在特定的 UTC 时间运行。 预定的工作流程在默认或基础分支的最新提交上运行。 您可以运行预定工作流程的最短间隔是每 5 分钟一次。

此示例在每天 5:30 和 17:30 UTC 触发工作流程：

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

多个 schedule 事件可以触发单个工作流。 � 可以通过 github.event.schedule 上下文访问触发工作流的计划事件。 此示例触发工作流在每周一至周四 5:30 UTC 运行，但在周一和周三跳过 Not on Monday or Wednesday 步骤。

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

有关 cron 语法的详细信息，请参阅“触发工作流的事件”。

on.workflow_run.<branches|branches-ignore>

使用 workflow_run 事件时，可以指定触发工作流必须在哪些分支上运行才能触发工作流。

branches 和 branches-ignore 筛选器接受使用 *、**、+、? 和 ! 等字符匹配多个分支名称的 glob 模式。 如果名称包含其中任一字符，而� 想要逐字匹配，则需要使用 \ 转义每个特殊字符。 有关 glob 模式的更多信息，请参阅“筛选器模式备忘清单”。

例如，仅当名为 Build 的工作流在名称以 releases/ 开头的分支上运行时，具有以下触发器的工作流才会运行：

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

仅当名为 Build 的工作流不在名为 canary 的分支上运行时，具有以下触发器的工作流才会运行：

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

不能对工作流中的同一事件同时使用 branches 和 branches-ignore 筛选器。 如果要同时包括和排除单个事件的分支模式，请使用 branches 筛选器以及 ! 字符来指示应排除哪些分支。

您定义模式事项的顺序。

• 肯定匹配后的匹配否定模式（前缀为 !）将排除分支。
• 否定匹配后的匹配肯定模式将再次包含分支。

例如，当名为 Build 的工作流在名为 releases/10 或 releases/beta/mona 但不在名为 releases/10-alpha、releases/beta/3-alpha 或 main 的分支上运行时，具有以下触发器的工作流将运行。

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.workflow_dispatch.inputs

When using the workflow_dispatch event, you can optionally specify inputs that are passed to the workflow.

The triggered workflow receives the inputs in the github.event.inputs context. For more information, see "Contexts."

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning' 
      print_tags:
        description: 'True to print to STDOUT'
        required: true 
      tags:
        description: 'Test scenario tags'
        required: true 

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if:  ${{ github.event.inputs.print_tags == 'true' }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ github.event.inputs.tags }} 

permissions

可以使用 permissions 修改授予 GITHUB_TOKEN 的默认权限，� �据需要添� 或� 除访问权限，以便只授予所需的最低访问权限。 有关的详细信息，请参阅“工作流中的身份验证”。

可以使用 permissions 作为顶级密钥，以应用于工作流中的所有作业或特定作业。 当� 在特定作业中添�  permissions 密钥时，该作业中使用 GITHUB_TOKEN 的所有操作和运行命令都将获得� 指定的访问权限。 有关详细信息，请参阅 jobs.<job_id>.permissions。

可用的作用域和访问权限值：

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

如果� 指定其中任何作用域的访问权限，则所有未指定的作用域都被设置为 none。

您可以使用以下语法来定义所有可用作用域的读取或写入权限：

permissions: read-all|write-all

可以使用以下语法禁用所有可用作用域的权限：

permissions: {}
``` 可以使用 `permissions` 密钥添� 和� 除分叉存储库的读取权限，但通常不能授予其写入权限。 此行为的例外情况是，管理员用户已在 GitHub Actions 设置中选择了“通过拉取请求向工作流发送写入令牌”选项。 有关详细信息，请参阅“[管理存储库的 GitHub Actions 设置](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)”。

### 示例：为 GITHUB_TOKEN 分配权限

此示例显示为将要应用到工作流中所有作业的 `GITHUB_TOKEN` 设置的权限。 所有权限都被授予读取权限。

```yaml
name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

A map of environment variables that are available to the steps of all jobs in the workflow. You can also set environment variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env and jobs.<job_id>.steps[*].env.

Variables in the env map cannot be defined in terms of other variables in the map.

当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的环境变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。

Example

env:
  SERVER: production

defaults

使用 defaults 创建将应用于工作流中所有作业的默认设置的 map。 您也可以设置只可用于作业的默认设置。 有关详细信息，请参阅 jobs.<job_id>.defaults。

使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。

defaults.run

� 可以使用 defaults.run 为工作流中的所有 run 步骤提供默认的 shell 和 working-directory 选项。 � 也可以为只可用于作业的 run 设定默认设置。 有关详细信息，请参阅 jobs.<job_id>.defaults.run。 您不能在此关键词中使用上下文或表达式。

使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。

示例：设置默认 shell 和工作目录

defaults:
  run:
    shell: bash
    working-directory: scripts

concurrency

使用 concurrency 以确保只有使用相同并发组的单一作业或工作流才会同时运行。 并发组可以是任何字符串或表达式。 表达式只能使用 github 上下文。 有关表达式的详细信息，请参阅“表达式”。

� 还可以在作业级别指定 concurrency。 有关详细信息，请参阅 jobs.<job_id>.concurrency。

当并发作业或工作流排队时，如果存储库中使用同一并发组的其他作业或工作流正在运行，则排队的作业或工作流将为 pending。 在并发组中任何先前挂起的作业或工作流程都将被取消。 若还要取消同一并发组中任何当前正在运行的作业或工作流，请指定 cancel-in-progress: true。

示例：使用并发和默认行为

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

示例：使用并发取消任何当前作业或运行

concurrency: 
  group: ${{ github.ref }}
  cancel-in-progress: true

示例：使用回退值

如果使用仅为特定事件定义的属性生成组名称，则可以使用回退值。 例如，github.head_ref 仅对 pull_request 事件定义。 如果工作流响应除了 pull_request 事件之外的其他事件，� 将需要提供回退以避免语法错误。 以下并发组仅取消针对 pull_request 事件正在进行的作业或运行；如果 github.head_ref 未定义，并发组将回退到运行 ID，该 ID 保证是唯一的，并且是为该运行定义的。

concurrency: 
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

示例：仅取消针对当前工作流正在进行的作业或运行

如果在同一个存储库中有多个工作流，则并发组名称在工作流中必须是唯一的，以避免从其他工作流取消正在进行的作业或运行。 否则，� 论工作流如何，任何先前进行中或挂起的作业都将被取消。

要仅取消同一工作流的正在进行的运行，可以使用 github.workflow 属性来生成并发组：

concurrency: 
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs

工作流运行由一个或多个 jobs 组成，默认情况下并行运行。 若要按顺序运行作业，可以使用 jobs.<job_id>.needs 关键字定义对其他作业的依赖关系。

每个作业在 runs-on 指定的运行器环境中运行。

在工作流程的使用限制之内可运行� 限数量的作业。 有关详细信息，请参阅 “使用情况限制和计费，了解 GitHub 托管的运行程序，以及参阅 “关于自托管运行程序”了解自托管运行程序使用限制。

如果需要查找在工作流运行中运行的作业的唯一� �识符，可以使用 GitHub Enterprise Server API。 有关详细信息，请参阅“工作流作业”。

jobs.<job_id>

使用 jobs.<job_id> 为作业提供唯一� �识符。 键 job_id 是一个字符串，其值是作业配置数据的� 射。 必须将 <job_id> 替换为对于 jobs 对象的唯一字符串。 <job_id> 必须以字母或 _ 开头，并且只能包含字母数字字符、- 或 _。

示例：创建作业

在此示例中，已创建两个作业，其 job_id 值为 my_first_job 和 my_second_job。

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

使用 jobs.<job_id>.name 设置作业名称，该名称显示在 GitHub UI 中。

jobs.<job_id>.permissions

在特定的作业中，� 可以使用 jobs.<job_id>.permissions 修改授予 GITHUB_TOKEN 的默认权限，� �据需要添� 或� 除访问权限，以便只授予所需的最低访问权限。 有关的详细信息，请参阅“工作流中的身份验证”。

通过在作业定义中指定权限，可� �据需要为每个作业的 GITHUB_TOKEN 配置一组不同的权限。 或者，您也可以为工作流程中的所有作业指定权限。 有关在工作流级别定义权限的信息，请参阅 permissions。

可用的作用域和访问权限值：

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

如果� 指定其中任何作用域的访问权限，则所有未指定的作用域都被设置为 none。

您可以使用以下语法来定义所有可用作用域的读取或写入权限：

permissions: read-all|write-all

可以使用以下语法禁用所有可用作用域的权限：

permissions: {}
``` 可以使用 `permissions` 密钥添� 和� 除分叉存储库的读取权限，但通常不能授予其写入权限。 此行为的例外情况是，管理员用户已在 GitHub Actions 设置中选择了“通过拉取请求向工作流发送写入令牌”选项。 有关详细信息，请参阅“[管理存储库的 GitHub Actions 设置](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)”。

#### 示例：为特定作业设置权限

本示例显示为将仅应用到作业 `stale` 的 `GITHUB_TOKEN` 设置的权限。 为 `issues` 和 `pull-requests` 范围授予写入权限。 所有其他范围将没有访问权限。

```yaml
jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v4

jobs.<job_id>.needs

使用 jobs.<job_id>.needs � �识运行此作业之前必须成功完成的所有作业。 它可以是一个字符串，也可以是字符串数组。 如果某个作业失败，则所有需要它的作业都会被跳过，除非这些作业使用让该作业继续的条件表达式。 如果运行包含一系列相互需要的作业，则故障将从故障点开始，应用于依赖项链中的所有作业。

示例：要求成功的依赖项作业

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

在此示例中，job1 必须在 job2 开始之前成功完成，并且 job3 等待 job1 和 job2 完成。

此示例中的作业按顺序运行：

1. job1
2. job2
3. job3

示例：不要求成功的依赖项作业

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

在此示例中，job3 使用 always() 条件表达式，确保始终在 job1 和 job2 完成（� 论是否成功）后运行。 有关详细信息，请参阅“表达式”。

jobs.<job_id>.if

可以使用 jobs.<job_id>.if 条件来阻止步骤运行，除非满足条件。 您可以使用任何支持上下文和表达式来创建条件。

在 if 条件下使用表达式时，可以省略表达式语法 (${{ }})，� 为 GitHub 会自动将 if 条件作为表达式求值。 有关详细信息，请参阅“表达式”。

示例：仅针对特定存储库运行作业

此示例使用 if 控制 production-deploy 作业何时可以运行。 仅当存储库名为 octo-repo-prod 且位于 octo-org 组织内时，它才会运行。 否则，作业将被� �记为“跳过”。

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

使用 jobs.<job_id>.runs-on 定义要运行作业的计算机类型。 可以将 runs-on 作为单个字符串或字符串数组提供。 如果指定字符串数组，则工作流将在自托管运行器上运行，其� �签与所有指定的 runs-on 值匹配（如果可用）。 如果要在多台计算机上运行工作流，请使用 jobs.<job_id>.strategy。

选择 GitHub 托管的运行器

如果使用 GitHub 托管的运行器，每个作业将在 runs-on 指定的运行器� 像的新实例中运行。

可用的 GitHub 托管的运行器类型包括：

示例：指定操作系统

runs-on: ubuntu-latest

有关详细信息，请参阅“关于 GitHub 托管的运行器”。

选择自托管运行器

要为作业指定自托管运行器，请在工作流文件中使用自托管运行器� �签配置 runs-on。

所有自托管运行器都有 self-hosted � �签。 仅使用此� �签将选择任何自托管运行器。 选择符合特定条件的运行器，例如操作系统或体系结构，建议提供以 self-hosted 开头的� �签数组（必须首先列出），然后� �据需要包含其他� �签。 指定� �签数组时，作业将在具有� 指定的所有� �签的运行器上排队。

尽管 self-hosted � �签不是必需的，但强烈建议在使用自托管运行器时指定它，以确保作业不会� 意中指定任何当前或将来的 GitHub 托管运行器。

示例：使用� �签进行运行器选择

runs-on: [self-hosted, linux]

有关详细信息，请参阅“关于自托管运行器”和“在工作流中使用自托管运行器”。

jobs.<job_id>.environment

使用 jobs.<job_id>.environment 定义作业引用的环境。 在将引用环境的作业发送到运行器之前，必须通过所有环境保护规则。 有关详细信息，请参阅“使用环境进行部署”。

可以将环境仅作为环境 name 提供，也可以作为具有 name 和 url 的环境对象提供。 URL 将� 射到部署 API 中的 environment_url。 有关部署 API 的详细信息，请参阅“部署”。

使用单一环境名称的示例

environment: staging_environment

使用环境名称和 URL 的示例

environment:
  name: production_environment
  url: https://github.com

URL 可以是表达式，并且可以使用除 secrets 上下文以外的任何上下文。 有关表达式的更多信息，请参阅“表达式”。

将输出用作 URL 的示例

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

jobs.<job_id>.concurrency

可以使用 jobs.<job_id>.concurrency 确保只有使用相同并发组的单一作业或工作流才会同时运行。 并发组可以是任何字符串或表达式。 表达式可以使用除 secrets 上下文以外的任何上下文。 有关表达式的更多信息，请参阅“表达式”。

还可以在工作流级别指定 concurrency。 有关详细信息，请参阅 concurrency。

当并发作业或工作流排队时，如果存储库中使用同一并发组的其他作业或工作流正在运行，则排队的作业或工作流将为 pending。 在并发组中任何先前挂起的作业或工作流程都将被取消。 若还要取消同一并发组中任何当前正在运行的作业或工作流，请指定 cancel-in-progress: true。

示例：使用并发和默认行为

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

示例：使用并发取消任何当前作业或运行

concurrency: 
  group: ${{ github.ref }}
  cancel-in-progress: true

示例：使用回退值

如果使用仅为特定事件定义的属性生成组名称，则可以使用回退值。 例如，github.head_ref 仅对 pull_request 事件定义。 如果工作流响应除了 pull_request 事件之外的其他事件，� 将需要提供回退以避免语法错误。 以下并发组仅取消针对 pull_request 事件正在进行的作业或运行；如果 github.head_ref 未定义，并发组将回退到运行 ID，该 ID 保证是唯一的，并且是为该运行定义的。

concurrency: 
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

示例：仅取消针对当前工作流正在进行的作业或运行

如果在同一个存储库中有多个工作流，则并发组名称在工作流中必须是唯一的，以避免从其他工作流取消正在进行的作业或运行。 否则，� 论工作流如何，任何先前进行中或挂起的作业都将被取消。

要仅取消同一工作流的正在进行的运行，可以使用 github.workflow 属性来生成并发组：

concurrency: 
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs.<job_id>.outputs

You can use jobs.<job_id>.outputs to create a map of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see jobs.<job_id>.needs.

输出是 Unicode 字符串，最大为 1 MB。 工作流运行中所有输出的总和最大为 50 MB。

Job outputs containing expressions are evaluated on the runner at the end of each job. Outputs containing secrets are redacted on the runner and not sent to GitHub Actions.

To use job outputs in a dependent job, you can use the needs context. For more information, see "Contexts."

Example: Defining outputs for a job

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}

jobs.<job_id>.env

A map of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see env and jobs.<job_id>.steps[*].env.

当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的环境变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。

Example

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

使用 jobs.<job_id>.defaults 创建将应用于作业中所有步骤的默认设置的 map。 您也可以设置整个工作流程的默认设置。 有关详细信息，请参阅 defaults。

使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。

jobs.<job_id>.defaults.run

使用 jobs.<job_id>.defaults.run 为作业中的所有 run 步骤提供默认的 shell 和 working-directory。 此部分不允许上下文和表达式。

� 可以为作业中的所有 run 步骤提供默认的 shell 和 working-directory 选项。 � 也可以为整个工作流的 run 设置默认设置。 有关详细信息，请参阅 jobs.defaults.run。 您不能在此关键词中使用上下文或表达式。

使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。

示例：为作业设置默认 run 步骤选项

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: scripts

jobs.<job_id>.steps

A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Example

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

A unique identifier for the step. You can use the id to reference the step in contexts. For more information, see "Contexts."

jobs.<job_id>.steps[*].if

You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.

在 if 条件下使用表达式时，可以省略表达式语法 (${{ }})，� 为 GitHub 会自动将 if 条件作为表达式求值。 For more information, see "Expressions."

Example: Using contexts

This step only runs when the event type is a pull_request and the event action is unassigned.

steps:
 - name: My first step
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
   run: echo This event is a pull request that had an assignee removed.

Example: Using status check functions

The my backup step only runs when the previous step of a job fails. For more information, see "Expressions."

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

Example: Using secrets

Secrets cannot be directly referenced in if: conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.

If a secret has not been set, the return value of an expression referencing the secret (such as ${{ secrets.SuperSecret }} in the example) will be an empty string.

name: Run a step if a secret has been set
on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
      super_secret: ${{ secrets.SuperSecret }}
    steps:
      - if: ${{ env.super_secret != '' }}
        run: echo 'This step will only run if the secret has a value set.'
      - if: ${{ env.super_secret == '' }}
        run: echo 'This step will only run if the secret does not have a value set.'

For more information, see "Context availability" and "Encrypted secrets."

jobs.<job_id>.steps[*].name

A name for your step to display on GitHub.

jobs.<job_id>.steps[*].uses

Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.

We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.

• Using the commit SHA of a released action version is the safest for stability and security.
• If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author.
• Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

Some actions require inputs that you must set using the with keyword. Review the action's README file to determine the inputs required.

Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see runs-on.

Example: Using versioned actions

steps:
  # Reference a specific commit
  - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
  # Reference the major version of a release
  - uses: actions/checkout@v2
  # Reference a specific version
  - uses: actions/checkout@v2.2.0
  # Reference a branch
  - uses: actions/checkout@main

Example: Using a public action

{owner}/{repo}@{ref}

You can specify a branch, ref, or SHA in a public GitHub repository.

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

Example: Using a public action in a subdirectory

{owner}/{repo}/{path}@{ref}

A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

Example: Using an action in the same repository as the workflow

./path/to/dir

The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Use local my-action
        uses: ./.github/actions/my-action

Example: Using a Docker Hub action

docker://{image}:{tag}

A Docker image published on Docker Hub.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Example: Using a Docker public registry action

docker://{host}/{image}:{tag}

A Docker image in a public registry. This example uses the Google Container Registry at gcr.io.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

Example: Using an action inside a different private repository than the workflow

Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as an encrypted secret. For more information, see "Creating a personal access token" and "Encrypted secrets."

Replace PERSONAL_ACCESS_TOKEN in the example with the name of your secret.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

jobs.<job_id>.steps[*].run

Runs command-line programs using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run command.

Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see jobs.<job_id>.steps[*].shell.

Each run keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example:

• A single-line command:

  - name: Install Dependencies
    run: npm install
  

• A multi-line command:

  - name: Clean install dependencies and build
    run: |
      npm ci
      npm run build
  

Using the working-directory keyword, you can specify the working directory of where to run the command.

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

jobs.<job_id>.steps[*].shell

You can override the default shell settings in the runner's operating system using the shell keyword. You can use built-in shell keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the run keyword.

Example: Running a script using bash

steps:
  - name: Display the path
    run: echo $PATH
    shell: bash

Example: Running a script using Windows cmd

steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd

Example: Running a script using PowerShell Core

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh

Example: Using PowerShell Desktop to run a script

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: powershell

Example: Running a python script

steps:
  - name: Display the path
    run: |
      import os
      print(os.environ['PATH'])
    shell: python

Custom shell

You can set the shell value to a template string using command […options] {0} [..more_options]. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}.

For example:

steps:
  - name: Display the environment variables and their values
    run: |
      print %ENV
    shell: perl {0}

The command used, perl in this example, must be installed on the runner.

Exit codes and error action preference

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

• bash/sh:

  • Fail-fast behavior using set -eo pipefail: This option is set when shell: bash is explicitly specified. It is not applied by default.
  • You can take full control over shell parameters by providing a template string to the shell options. For example, bash {0}.
  • sh-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code.

• powershell/pwsh

  • Fail-fast behavior when possible. For pwsh and powershell built-in shell, we will prepend $ErrorActionPreference = 'stop' to script contents.
  • We append if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } to powershell scripts so action statuses reflect the script's last exit code.
  • Users can always opt out by not using the built-in shell, and providing a custom shell option like: pwsh -File {0}, or powershell -Command "& '{0}'", depending on need.

• cmd

  • There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
  • cmd.exe will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previous sh and pwsh default behavior and is the cmd.exe default, so this behavior remains intact.

jobs.<job_id>.steps[*].with

A map of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

Example

Defines the three input parameters (first_name, middle_name, and last_name) defined by the hello_world action. These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

A string that defines the inputs for a Docker container. GitHub passes the args to the container's ENTRYPOINT when the container starts up. An array of strings is not supported by this parameter.

Example

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

1. Document required arguments in the action's README and omit them from the CMD instruction.
2. Use defaults that allow using the action without specifying any args.
3. If the action exposes a --help flag, or something similar, use that as the default to make your action self-documenting.

jobs.<job_id>.steps[*].with.entrypoint

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

Example

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

The entrypoint keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

jobs.<job_id>.steps[*].env

Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see env and jobs.<job_id>.env.

当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的环境变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。

Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets context. For more information, see "Using environment variables" and "Contexts."

Example

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

jobs.<job_id>.steps[*].timeout-minutes

The maximum number of minutes to run the step before killing the process.

jobs.<job_id>.timeout-minutes

The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360

If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

jobs.<job_id>.strategy

Use jobs.<job_id>.strategy to use a matrix strategy for your jobs. 使用矩阵策略，可以在单个作业定义中使用变量自动创建基于变量组合的多个作业运行。 例如，可以使用矩阵策略在某个语言的多个版本或多个操作系统上测试代� �。 For more information, see "Using a matrix for your jobs."

jobs.<job_id>.strategy.matrix

使用 jobs.<job_id>.strategy.matrix 定义不同作业配置的矩阵。 在矩阵中，定义一个或多个变量，后跟一个值数组。 例如，以下矩阵有一个称为 version 的变量，其值为 [10, 12, 14] ，以及一个称为 os 的变量，其值为 [ubuntu-latest, windows-latest]：

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

将针对变量的每个可能组合运行作业。 在此示例中，工作流将运行六个作业，其中一个作业用于每个 os 和 version 变量组合。

默认情况下，GitHub Enterprise Server 将� �据运行器的可用性最大程度地增� 并行运行的作业数量。 矩阵中变量的顺序决定了作业的创建顺序。 定义的第一个变量将是在工作流运行中创建的第一个作业。 例如，上述矩阵将按以下顺序创建作业：

• {version: 10, os: ubuntu-latest}
• {version: 10, os: windows-latest}
• {version: 12, os: ubuntu-latest}
• {version: 12, os: windows-latest}
• {version: 14, os: ubuntu-latest}
• {version: 14, os: windows-latest}

矩阵在每次工作流运行时最多将生成 256 个作业。 此限制适用于 GitHub Enterprise Server 托管和自托管运行器。

定义的变量将成为 matrix 上下文中的属性，� 可以在工作流文件的其他区域中引用该属性。 在此示例中，可以使用 matrix.version 和 matrix.os 来访问作业正在使用的 version 和 os 的当前值。 有关详细信息，请参阅“上下文”。

Example: Using a single-dimension matrix

可以指定单个变量来创建单维矩阵。

例如，以下工作流使用值 [10, 12, 14] 定义变量 version。 工作流将运行三个作业，其中针对变量中的每个值提供一个作业。 每个作业都会通过 matrix.version 上下文访问 version 值，并此值作为 node-version � 递给 actions/setup-node 操作。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

Example: Using a multi-dimension matrix

可以指定多个变量来创建多维矩阵。 将针对变量的每个可能组合运行作业。

例如，以下工作流指定两个变量：

• os 变量中指定的两个操作系统
• version 变量中指定的三个 Node.js 版本

工作流将运行六个作业，其中针对每个 os 和 version 变量组合提供一个作业。 每个作业都会将 runs-on 值设置为当前的 os 值，并将当前的 version 值� 递给 actions/setup-node 操作。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

Example: Using contexts to create matrices

可以使用上下文来创建矩阵。 有关上下文的详细信息，请参阅“上下文”。

例如，以下工作流触发事件 repository_dispatch，并使用事件有效负载中的信息来生成矩阵。 使用如下所示的有效负载创建存储库调度事件时，矩阵 version 变量的值为 [12, 14, 16]。 有关 repository_dispatch 触发器的详细信息，请参阅“触发工作流的事件”。

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}

on:
  repository_dispatch:
    types:
      - test
 
jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

jobs.<job_id>.strategy.matrix.include

使用 jobs.<job_id>.strategy.matrix.include 扩展现有矩阵配置或添� 新配置。 include 值是一个对象列表。

对于 include 列表中的每个对象，如果对象中的键:值对均未覆盖任何原始矩阵值，则会将键:值对添� 到每个矩阵组合中。 如果对象不能添� 到任何矩阵组合中，将改为创建新的矩阵组合。 请注意，不会覆盖原始矩阵值，但可以覆盖添� 的矩阵值。

例如，此矩阵：

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

将生成具有以下矩阵组合的六个作业：

• {fruit: apple, animal: cat, color: pink, shape: circle}
• {fruit: apple, animal: dog, color: green, shape: circle}
• {fruit: pear, animal: cat, color: pink}
• {fruit: pear, animal: dog, color: green}
• {fruit: banana}
• {fruit: banana, animal: cat}

遵循以下逻辑：

• {color: green} 添� 到所有原始矩阵组合，� 为它可以添� ，而不会覆盖原始组合的任何部分。
• {color: pink, animal: cat} 仅将 color:pink 添� 到包含 animal: cat 的原始矩阵组合中。 这会覆盖上一个 include 条目添� 的 color: green。
• {fruit: apple, shape: circle} 仅将 shape: circle 添� 到包含 fruit: apple 的原始矩阵组合中。
• {fruit: banana} 添� 到任何原始矩阵组合时都会覆盖值，� 此会将其作为其他矩阵组合进行添� 。
• {fruit: banana, animal: cat} 添� 到任何原始矩阵组合时都会覆盖值，� 此会将其作为其他矩阵组合进行添� 。 它不会添� 到 {fruit: banana} 矩阵组合中，� 为该组合不是原始矩阵组合之一。

Example: Expanding configurations

例如，以下工作流将运行六个作业，其中针对每个 os 和 node 变量组合提供一个作业。 当对应于 windows-latest 的 os 值和 16 的 node 值的作业运行时，作业中将包含一个被称为 npm 且值为 6 的其他变量。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Example: Adding configurations

例如，此矩阵将运行 10 个作业，矩阵中每个 os 和 version 的组合一个作业，再� 上一个用于 windows-latest 的 os 值和 17 的 version 值的作业。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

如果未指定任何矩阵变量，则运行 include 下的所有配置。 例如，以下工作流将运行两个作业，每个 include 一个作业。 这� �� 可以利用矩阵策略，而� 需完全填充矩阵。

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

jobs.<job_id>.strategy.matrix.exclude

若要移除矩阵中定义的特定配置，请使用 jobs.<job_id>.strategy.matrix.exclude。 排除的配置必须是部分匹配项，才能将其排除。 例如，以下工作流将运行 9 个作业：每 12 个配置一个作业，再减去一个与 {os: macos-latest, version: 12, environment: production} 匹配的排除作业，以及两个与 {os: windows-latest, version: 16} 匹配的排除作业。

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

jobs.<job_id>.strategy.fail-fast

� 可以使用 jobs.<job_id>.strategy.fail-fast 和 jobs.<job_id>.continue-on-error 来控制如何处理作业失败。

jobs.<job_id>.strategy.fail-fast 适用于整个矩阵。 如果 jobs.<job_id>.strategy.fail-fast 设置为 true，则在矩阵中的任何作业失败的情况下，GitHub Enterprise Server 将取消矩阵中所有正在进行和� 入队列的作业。 此属性的默认值为 true。

jobs.<job_id>.continue-on-error 适用于单个作业。 如果 jobs.<job_id>.continue-on-error 为 true，即使具有 jobs.<job_id>.continue-on-error: true 的作业失败，矩阵中的其他作业也将继续运行。

可以同时使用 jobs.<job_id>.strategy.fail-fast 和 jobs.<job_id>.continue-on-error。 例如，以下工作流将启动四个作业。 对于每个作业，continue-on-error 都由 matrix.experimental 的值确定。 如果任何具有 continue-on-error: false 的作业失败，所有正在进行或� 入队列的作业都将被取消。 如果具有 continue-on-error: true 的作业失败，则其他作业将不会受到影响。

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

jobs.<job_id>.strategy.max-parallel

默认情况下，GitHub Enterprise Server 将� �据运行器的可用性将并行运行的作业数最大化。 若要设置使用 matrix 作业策略时可以同时运行的最大作业数，请使用 jobs.<job_id>.strategy.max-parallel。

例如，以下工作流一次最多运行两个作业，即使运行器可同时运行六个作业。

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

jobs.<job_id>.continue-on-error

Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.

Example: Preventing a specific failing matrix job from failing a workflow run

You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job with node set to 15 to fail without failing the workflow run.

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [13, 14]
    os: [macos-latest, ubuntu-latest]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-latest
        experimental: true

jobs.<job_id>.container

Use jobs.<job_id>.container to create a container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts.

If you do not set a container, all steps will run directly on the host specified by runs-on unless a step refers to an action configured to run in a container.

Example: Running a job within a container

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:14.16
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

When you only specify a container image, you can omit the image keyword.

jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container: node:14.16

jobs.<job_id>.container.image

使用 jobs.<job_id>.container.image 定义要用作运行操作的容器的 Docker � 像。 值可以是 Docker Hub � 像名称或注册表名称。

jobs.<job_id>.container.credentials

如果� 像的容器注册表需要身份验证才能拉取� 像，可以使用 jobs.<job_id>.container.credentials 设置 username 和 password 的 map。 凭据是� 将提供给 docker login 命令的相同值。

示例：定义容器注册表的凭据

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.github_token }}

jobs.<job_id>.container.env

使用 jobs.<job_id>.container.env 以在容器中设置环境变量的 map。

jobs.<job_id>.container.ports

使用 jobs.<job_id>.container.ports 设置要在容器上显示的 array 个端口。

jobs.<job_id>.container.volumes

使用 jobs.<job_id>.container.volumes 设置容器要使用的卷 array。 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。

要指定卷，需指定来源和目� �路径：

<source>:<destinationPath>.

<source> 是主机上的卷名称或绝对路径，<destinationPath> 是容器中的绝对路径。

示例：在容器中装载卷

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

使用 jobs.<job_id>.container.options 配置其他 Docker 容器资源选项。 有关选项列表，请参阅“docker create 选项”。

jobs.<job_id>.services

Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.

If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.

For more information about the differences between networking service containers, see "About service containers."

Example: Using localhost

This example creates two services: nginx and redis. When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. GitHub sets the assigned container port in the ${{job.services.<service_name>.ports}} context. In this example, you can access the service container ports using the ${{ job.services.nginx.ports['8080'] }} and ${{ job.services.redis.ports['6379'] }} contexts.

services:
  nginx:
    image: nginx
    # Map port 8080 on the Docker host to port 80 on the nginx container
    ports:
      - 8080:80
  redis:
    image: redis
    # Map TCP port 6379 on Docker host to a random free port on the Redis container
    ports:
      - 6379/tcp

jobs.<job_id>.services.<service_id>.image

The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.

jobs.<job_id>.services.<service_id>.credentials

如果� 像的容器注册表需要身份验证才能拉取� 像，可以使用 jobs.<job_id>.container.credentials 设置 username 和 password 的 map。 凭据是� 将提供给 docker login 命令的相同值。

Example

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

Sets a map of environment variables in the service container.

jobs.<job_id>.services.<service_id>.ports

Sets an array of ports to expose on the service container.

jobs.<job_id>.services.<service_id>.volumes

Sets an array of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.

To specify a volume, you specify the source and destination path:

<source>:<destinationPath>.

The <source> is a volume name or an absolute path on the host machine, and <destinationPath> is an absolute path in the container.

Example

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

Additional Docker container resource options. For a list of options, see "docker create options."

Filter pattern cheat sheet

You can use special characters in path, branch, and tag filters.

• *: Matches zero or more characters, but does not match the / character. For example, Octo* matches Octocat.
• **: Matches zero or more of any character.
• ?: Matches zero or one of the preceding character.
• +: Matches one or more of the preceding character.
• [] Matches one character listed in the brackets or included in ranges. Ranges can only include a-z, A-Z, and 0-9. For example, the range[0-9a-z] matches any digit or lowercase letter. For example, [CB]at matches Cat or Bat and [1-2]00 matches 100 and 200.
• !: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character.

The characters *, [, and ! are special characters in YAML. If you start a pattern with *, [, or !, you must enclose the pattern in quotes. Also, if you use a flow sequence with a pattern containing [ and/or ], the pattern must be enclosed in quotes.

# Valid
branches:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
branches:
  - **/README.md

# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]

# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]

For more information about branch, tag, and path filter syntax, see "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>", and "on.<push|pull_request>.paths."

Patterns to match branches and tags

Patterns to match file paths

Path patterns must match the whole path, and start from the repository's root.