Skip to main content

GitHub Actions 的工作流程语法

本文内容

工作流程是可配置的自动化过程,由一个或多个作业组成。 您必须创建 YAML 文件来定义工作流程配置。

注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。

关于工作流程的 YAML 语法

工作流程文件使用 YAML 语法,必须有 .yml.yaml 文件扩展名。 如果您是 YAML 的新用户并想要了解更多信息,请参阅“Y 分钟了解 YAML”。

必须将工作流程文件存储在仓库的 .github/workflows 目录中。

name

工作流程的名称。 GitHub 在仓库的操作页面上显示工作流程的名称。 如果省略 name,GitHub 将其设置为相对于仓库根目录的工作流程文件路径。

on

To automatically trigger a workflow, use on to define which events can cause the workflow to run. 有关可用事件的列表,请参阅“触发工作流程的事件”。

You can define single or multiple events that can a trigger workflow, or set a time schedule. You can also restrict the execution of a workflow to only occur for specific files, tags, or branch changes. 以下各节介绍了这些选项。

使用单个事件

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

on: push

使用多个事件

您可以指定单个事件或多个事件。 例如,当向存储库中的任何分支进行推送或有人复刻存储库时,将运行具有以下 on 值的工作流程:

on: [push, fork]

如果指定多个事件,则只需发生其中一个事件即可触发工作流程。 如果工作流程的多个触发事件同时发生,则将触发多个工作流程运行。

Using activity types

Some events have activity types that give you more control over when your workflow should run. Use on.<event_name>.types to define the type of event activity that will trigger a workflow run.

For example, the issue_comment event has the created, edited, and deleted activity types. If your workflow triggers on the label event, it will run whenever a label is created, edited, or deleted. If you specify the created activity type for the label event, your workflow will run when a label is created but not when a label is edited or deleted.

on:
  label:
    types:
      - created

If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events.

on:
  issue:
    types:
      - opened
      - labeled

有关每个事件及其活动类型的更多信息,请参阅“触发工作流程的事件”。

使用筛选器

Some events have filters that give you more control over when your workflow should run.

For example, the push event has a branches filter that causes your workflow to run only when a push to a branch that matches the branches filter occurs, instead of when any push occurs.

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

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

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

例如,使用以下 on 值的工作流程将在以下情况下运行:

  • 创建标签
  • 推送到存储库中的 main 分支
  • 推送到启用了 GitHub Pages 的分支
on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

Use on.<event_name>.types to define the type of activity that will trigger a workflow run. 大多数 GitHub 事件由多种活动触发。 For example, the label is triggered when a label is created, edited, or deleted. 通过 types 关键词可缩小触发工作流程运行的活动类型的范围。 如果只有一种活动类型可触发 web 挂钩事件,就没有必要使用 types 关键词。

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

on:
  label:
    types: [created, edited]

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

When using the pull_request and pull_request_target events, you can configure a workflow to run only for pull requests that target specific branches.

Use the branches filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore filter when you only want to exclude branch name patterns. You cannot use both the branches and branches-ignore filters for the same event in a workflow.

If you define both branches/branches-ignore and paths, the workflow will only run when both filters are satisfied.

The branches and branches-ignore keywords accept glob patterns that use characters like *, **, +, ?, ! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \. 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。

Example: Including branches

The patterns defined in branches are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request event for a pull request targeting:

  • A branch named main (refs/heads/main)
  • A branch named mona/octocat (refs/heads/mona/octocat)
  • A branch whose name starts with releases/, like releases/10 (refs/heads/releases/10)
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'

Example: Excluding branches

When a pattern matches the branches-ignore pattern, the workflow will not run. The patterns defined in branches are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request event unless the pull request is targeting:

  • A branch named mona/octocat (refs/heads/mona/octocat)
  • A branch whose name matches releases/**-alpha, like beta/3-alpha (refs/releases/beta/3-alpha)
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'

Example: Including and excluding branches

You cannot use branches and branches-ignore to filter the same event in a single workflow. If you want to both include and exclude branch patterns for a single event, use the branches filter along with the ! character to indicate which branches should be excluded.

If you define a branch with the ! character, you must also define at least one branch without the ! character. If you only want to exclude branches, use branches-ignore instead.

您定义模式事项的顺序。

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

The following workflow will run on pull_request events for pull requests that target releases/10 or releases/beta/mona, but not for pull requests that target releases/10-alpha or releases/beta/3-alpha because the negative pattern !releases/**-alpha follows the positive pattern.

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

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

When using the push event, you can configure a workflow to run on specific branches or tags.

Use the branches filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore filter when you only want to exclude branch name patterns. You cannot use both the branches and branches-ignore filters for the same event in a workflow.

Use the tags filter when you want to include tag name patterns or when you want to both include and exclude tag names patterns. Use the tags-ignore filter when you only want to exclude tag name patterns. You cannot use both the tags and tags-ignore filters for the same event in a workflow.

If you define only tags/tags-ignore or only branches/branches-ignore, the workflow won't run for events affecting the undefined Git ref. If you define neither tags/tags-ignore or branches/branches-ignore, the workflow will run for events affecting either branches or tags. If you define both branches/branches-ignore and paths, the workflow will only run when both filters are satisfied.

branchesbranches-ignoretagstags-ignore 关键词接受使用 ***+?! 等字符匹配多个分支或标记名称的 glob 模式。 If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \. 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。

示例:包括分支和标记

branchestags 中定义的模式根据 Git ref 的名称进行评估。 For example, the following workflow would run whenever there is a push event to:

  • A branch named main (refs/heads/main)
  • A branch named mona/octocat (refs/heads/mona/octocat)
  • A branch whose name starts with releases/, like releases/10 (refs/heads/releases/10)
  • A tag named v2 (refs/tags/v2)
  • A tag whose name starts with v1., like 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.*

Example: Excluding branches and tags

When a pattern matches the branches-ignore or tags-ignore pattern, the workflow will not run. 在 branchestags 中定义的模式根据 Git ref 的名称进行评估。 For example, the following workflow would run whenever there is a push event, unless the push event is to:

  • A branch named mona/octocat (refs/heads/mona/octocat)
  • A branch whose name matches releases/**-alpha, like beta/3-alpha (refs/releases/beta/3-alpha)
  • A tag named v2 (refs/tags/v2)
  • A tag whose name starts with v1., like 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.*

Example: Including and excluding branches and tags

You can't use branches and branches-ignore to filter the same event in a single workflow. Similarly, you can't use tags and tags-ignore to filter the same event in a single workflow. If you want to both include and exclude branch or tag patterns for a single event, use the branches or tags filter along with the ! character to indicate which branches or tags should be excluded.

If you define a branch with the ! character, you must also define at least one branch without the ! character. If you only want to exclude branches, use branches-ignore instead. Similarly, if you define a tag with the ! character, you must also define at least one tag without the ! character. If you only want to exclude tags, use tags-ignore instead.

您定义模式事项的顺序。

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

以下工作流程将在到 releases/10releases/beta/mona 的推送上运行,而不会在到 releases/10-alphareleases/beta/3-alpha 的推送上运行,因为否定模式 !releases/**-alpha 后跟肯定模式。

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

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

When using the push and pull_request events, you can configure a workflow to run based on what file paths are changed. Path filters are not evaluated for pushes of tags.

Use the paths filter when you want to include file path patterns or when you want to both include and exclude file path patterns. Use the paths-ignore filter when you only want to exclude file path patterns. You cannot use both the paths and paths-ignore filters for the same event in a workflow.

If you define both branches/branches-ignore and paths, the workflow will only run when both filters are satisfied.

The paths and paths-ignore keywords accept glob patterns that use the * and ** wildcard characters to match more than one path name. 更多信息请参阅“过滤器模式备忘清单”。

示例:包括路径

如果至少有一个路径与 paths 过滤器中的模式匹配,工作流程将会运行。 For example, the following workflow would run anytime you push a JavaScript file (.js).

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

注意:如果由于路径过滤分支过滤提交消息而跳过工作流程,则与该工作流程关联的检查将保持“挂起”状态。 需要这些检查成功的拉取请求将被阻止合并。 For more information, see "Handling skipped but required checks."

Example: Excluding paths

当所有路径名称匹配 paths-ignore 中的模式时,工作流程不会运行。 If any path names do not match patterns in paths-ignore, even if some path names match the patterns, the workflow will run.

具有以下路径过滤器的工作流程仅在 push 事件上运行,这些事件包括至少一个位于仓库根目录的 docs 目录外的文件。

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

Example: Including and excluding paths

You can not use paths and paths-ignore to filter the same event in a single workflow. If you want to both include and exclude path patterns for a single event, use the paths filter along with the ! character to indicate which paths should be excluded.

If you define a path with the ! character, you must also define at least one path without the ! character. If you only want to exclude paths, use paths-ignore instead.

您定义模式事项的顺序:

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

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

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

Git 差异比较

注: 如果您推送超过 1,000 项提交, 或者如果 GitHub 因超时未生成差异,工作流程将始终运行。

过滤器决定是否应通过评估已更改文件,并根据 paths-ignore or paths 列表运行它们,来运行一个工作流程。 如果没有更改文件,工作流程将不会运行。

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

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

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

更多信息请参阅“关于比较拉取请求中的分支”。

on.schedule

You can use on.schedule to define a time schedule for your workflows. 您可以使用 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 * * *'

单个工作流程可由多个计划事件触发。 您可以通过 github.event.schedule 上下文访问触发工作流程的计划事件。 本示例触发工作流在每周一至周四的 5:30 UTC 运行,但在星期一和星期三跳过星期一或星期三不运行步骤。

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"

有关计划任务语法的更多信息请参阅“触发工作流程的事件”。

on.workflow_run.<branches|branches-ignore>

When using the workflow_run event, you can specify what branches the triggering workflow must run on in order to trigger your workflow.

The branches and branches-ignore filters accept glob patterns that use characters like *, **, +, ?, ! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \. 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。

For example, a workflow with the following trigger will only run when the workflow named Build runs on a branch whose name starts with releases/:

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

A workflow with the following trigger will only run when the workflow named Build runs on a branch that is not named canary:

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

You cannot use both the branches and branches-ignore filters for the same event in a workflow. If you want to both include and exclude branch patterns for a single event, use the branches filter along with the ! character to indicate which branches should be excluded.

您定义模式事项的顺序。

  • A matching negative pattern (prefixed with !) after a positive match will exclude the branch.
  • A matching positive pattern after a negative match will include the branch again.

For example, a workflow with the following trigger will run when the workflow named Build runs on a branch that is named releases/10 or releases/beta/mona but will not releases/10-alpha, releases/beta/3-alpha, or 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.

触发的工作流程接收 github.event.input 上下文中的输入。 更多信息请参阅“上下文”。

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 }} 

权限

You can use permissions to modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access. 更多信息请参阅“工作流程中的身份验证

您可以使用 permissions 作为顶级密钥,以应用于工作流程中的所有作业,或特定的作业。 当您在特定作业中添加 permissions 键时,该作业中的所有操作和运行命令使用 GITHUB_TOKEN 获取您指定的访问权限。 更多信息请参阅 jobs.<job_id>.permissions

Available scopes and access values:

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

If you specify the access for any of these scopes, all of those that are not specified are set to none.

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

You can use the following syntax to disable permissions for all of the available scopes:

permissions: {}

您可以使用 permissions 键来添加和删除复刻仓库的读取权限,但通常不能授予写入权限。 此行为的例外情况是,管理员在 GitHub Actions 设置中选择了 Send write tokens to workflows from pull requests(从拉取请求发送写入令牌到工作流程)选项。 更多信息请参阅“管理仓库的 GitHub Actions 设置”。

Example: Assigning permissions to GITHUB_TOKEN

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

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

环境变量的 map 可用于工作流程中所有作业的步骤。 您还可以设置仅适用于单个作业的步骤或单个步骤的环境变量。 更多信息请参阅 jobs.<job_id>.env and jobs.<job_id>.steps[*].env

env 映射中的变量不能根据映射中的其他变量进行定义。

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

示例

env:
  SERVER: production

defaults

Use defaults to create a map of default settings that will apply to all jobs in the workflow. 您也可以设置只可用于作业的默认设置。 更多信息请参阅 jobs.<job_id>.defaults

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

defaults.run

You can use defaults.run to provide default shell and working-directory options for all run steps in a workflow. 您也可以设置只可用于作业的 run 默认设置。 更多信息请参阅 jobs.<job_id>.defaults.run。 您不能在此关键词中使用上下文或表达式。

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

Example: Set the default shell and working directory

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

concurrency

Use concurrency to ensure that only a single job or workflow using the same concurrency group will run at a time. 并发组可以是任何字符串或表达式。 The expression can only use the github context. For more information about expressions, see "Expressions."

您也可以在作业级别指定 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

A workflow run is made up of one or more jobs, which run in parallel by default. 要按顺序运行作业,您可以使用 <job_id>needs 关键词在其他作业上定义依赖项。

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

在工作流程的使用限制之内可运行无限数量的作业。 For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

If you need to find the unique identifier of a job running in a workflow run, you can use the GitHub Enterprise Server API. 更多信息请参阅“工作流程作业”。

jobs.<job_id>

Use jobs.<job_id> to give your job a unique identifier. 键值 job_id 是一个字符串,其值是作业配置数据的映像。 必须将 <job_id> 替换为 jobs 对象唯一的字符串。 <job_id> 必须以字母或 _ 开头,并且只能包含字母数字字符、-_

Example: Creating jobs

In this example, two jobs have been created, and their job_id values are my_first_job and my_second_job.

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

jobs.<job_id>.name

Use jobs.<job_id>.name to a name for the job, which is displayed on GitHub.

jobs.<job_id>.permissions

For a specific job, you can use jobs.<job_id>.permissions to modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access. 更多信息请参阅“工作流程中的身份验证

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

Available scopes and access values:

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

If you specify the access for any of these scopes, all of those that are not specified are set to none.

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

You can use the following syntax to disable permissions for all of the available scopes:

permissions: {}

您可以使用 permissions 键来添加和删除复刻仓库的读取权限,但通常不能授予写入权限。 此行为的例外情况是,管理员在 GitHub Actions 设置中选择了 Send write tokens to workflows from pull requests(从拉取请求发送写入令牌到工作流程)选项。 更多信息请参阅“管理仓库的 GitHub Actions 设置”。

Example: Setting permissions for a specific job

此示例显示为将要应用到作业 staleGITHUB_TOKEN 设置的权限。 对于 issuespull-requests 拉取请求,授予写入访问权限。 所有其他范围将没有访问权限。

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v4

jobs.<job_id>.needs

Use jobs.<job_id>.needs to identify any jobs that must complete successfully before this job will run. 它可以是一个字符串,也可以是字符串数组。 如果某个作业失败,则所有需要它的作业都会被跳过,除非这些作业使用让该作业继续的条件表达式。 If a run contains a series of jobs that need each other, a failure applies to all jobs in the dependency chain from the point of failure onwards.

Example: Requiring successful dependent jobs

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

在此示例中,job1 必须在 job2 开始之前成功完成,而 job3 要等待 job1job2 完成。

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

  1. job1
  2. job2
  3. job3

Example: Not requiring successful dependent jobs

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

在此示例中,job3 使用 always() 条件表达式,因此它始终在 job1job2 完成后运行,不管它们是否成功。 更多信息请参阅“表达式”。

jobs.<job_id>.if

You can use the jobs.<job_id>.if conditional to prevent a job from running unless a condition is met. 您可以使用任何支持上下文和表达式来创建条件。

if 条件下使用表达式时,可以省略表达式语法 (${{ }}),因为 GitHub 会自动将 if 条件作为表达式求值。 更多信息请参阅“表达式”。

Example: Only run job for specific repository

This example uses if to control when the production-deploy job can run. It will only run if the repository is named octo-repo-prod and is within the octo-org organization. Otherwise, the job will be marked as skipped.

YAML
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

Use jobs.<job_id>.runs-on to define the type of machine to run the job on. You can provide runs-on as a single string or as an array of strings. If you specify an array of strings, your workflow will run on a self-hosted runner whose labels match all of the specified runs-on values, if available. If you would like to run your workflow on multiple machines, use jobs.<job_id>.strategy.

注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。

Choosing GitHub-hosted runners

如果使用 GitHub 托管的运行器,每个作业将在 runs-on 指定的虚拟环境的新实例中运行。

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

虚拟环境 YAML 工作流程标签 注:
Windows Server 2022 windows-latestwindows-2022 The windows-latest label currently uses the Windows Server 2022 runner image.
Windows Server 2019 windows-2019
Ubuntu 22.04 ubuntu-22.04 Ubuntu 22.04 is currently in public beta.
Ubuntu 20.04 ubuntu-latestubuntu-20.04
Ubuntu 18.04 ubuntu-18.04
macOS Monterey 12 macos-12 macOS 12 is currently in public beta.
macOS Big Sur 11 macos-latestmacos-11 The macos-latest label currently uses the macOS 11 runner image.
macOS Catalina 10.15 macos-10.15

Note: The -latest virtual environments are the latest stable images that GitHub provides, and might not be the most recent version of the operating system available from the operating system vendor.

Note: Beta and Deprecated Images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta Images may not be covered by customer support.

Example: Specifying an operating system

runs-on: ubuntu-latest

更多信息请参阅“GitHub 托管的运行器的虚拟环境”。

Choosing self-hosted runners

要为工作指定自托管的运行器,请在工作流程文件中使用自托管运行器标签配置 runs-on

所有自托管运行器都有 self-hosted 标签。 仅使用此标签将选择任何自托管运行器。 To select runners that meet certain criteria, such as operating system or architecture, we recommend providing an array of labels that begins with self-hosted (this must be listed first) and then includes additional labels as needed. When you specify an array of labels, jobs will be queued on runners that have all the labels that you specify.

Although the self-hosted label is not required, we strongly recommend specifying it when using self-hosted runners to ensure that your job does not unintentionally specify any current or future GitHub-hosted runners.

Example: Using labels for runner selection

runs-on: [self-hosted, linux]

更多信息请参阅“关于自托管的运行器”和“在工作流程中使用自托管的运行器”。

jobs.<job_id>.environment

Use jobs.<job_id>.environment to define the environment that the job references. 在将引用环境的作业发送到运行器之前,必须通过所有环境保护规则。 更多信息请参阅“使用环境进行部署”。

您可以将环境仅作为环境 name,或作为具有 nameurl 的环境变量。 URL 映射到部署 API 中的 environment_url。 有关部署 API 的更多信息,请参阅“部署”。

Example: Using a single environment name

environment: staging_environment

Example: Using environment name and URL

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

The URL can be an expression and can use any context except for the secrets context. For more information about expressions, see "Expressions."

Example: Using output as URL

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

jobs.<job_id>.concurrency

注意: 在作业级别指定并发时,无法保证在 5 分钟内排队的作业或运行的互相顺序。

You can use jobs.<job_id>.concurrency to ensure that only a single job or workflow using the same concurrency group will run at a time. 并发组可以是任何字符串或表达式。 表达式可以使用除 secrets 上下文以外的任何上下文。 For more information about expressions, see "Expressions."

您也可以在工作流程级别指定 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. 作业输出可用于所有依赖此作业的下游作业。 有关定义作业依赖项的更多信息,请参阅 jobs.<job_id>.needs

Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.

Job outputs containing expressions are evaluated on the runner at the end of each job. 包含密码的输出在运行器上编辑,不会发送至 GitHub Actions。

要在依赖的作业中使用作业输出, 您可以使用 needs 上下文。 更多信息请参阅“上下文”。

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

环境变量的 map 可用于作业中的所有步骤。 您也可以设置整个工作流程或单个步骤的环境变量。 更多信息请参阅 envjobs.<job_id>.steps[*].env

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

示例

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

Use jobs.<job_id>.defaults to create a map of default settings that will apply to all steps in the job. 您也可以设置整个工作流程的默认设置。 For more information, see defaults.

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

jobs.<job_id>.defaults.run

Use jobs.<job_id>.defaults.run to provide default shell and working-directory to all run steps in the job. 此部分不允许上下文和表达式。

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

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

Example: Setting default run step options for a job

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

jobs.<job_id>.steps

作业包含一系列任务,称为 steps。 步骤可以运行命令、运行设置任务,或者运行您的仓库、公共仓库中的操作或 Docker 注册表中发布的操作。 并非所有步骤都会运行操作,但所有操作都会作为步骤运行。 每个步骤在运行器环境中以其自己的进程运行,且可以访问工作区和文件系统。 因为步骤以自己的进程运行,所以步骤之间不会保留环境变量的更改。 GitHub 提供内置的步骤来设置和完成作业。

在工作流程的使用限制之内可运行无限数量的步骤。 For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

示例

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

步骤的唯一标识符。 您可以使用 id 引用上下文中的步骤。 更多信息请参阅“上下文”。

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

您可以使用 if 条件阻止步骤在条件得到满足之前运行。 您可以使用任何支持上下文和表达式来创建条件。

if 条件下使用表达式时,可以省略表达式语法 (${{ }}),因为 GitHub 会自动将 if 条件作为表达式求值。 更多信息请参阅“表达式”。

示例:使用上下文

此步骤仅在事件类型为 pull_request 并且事件操作为 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.

示例:使用状态检查功能

my backup step 仅在作业的上一步失败时运行。 更多信息请参阅“表达式”。

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

示例:使用机密

无法直接在 if: 条件中引用机密。 而应考虑将机密设置为作业级环境变量,然后引用环境变量以有条件地运行作业中的步骤。

如果尚未设置机密,则引用该机密的表达式(例如示例中的 ${{ secrets.SuperSecret }})的返回值将为空字符串。

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.'

更多信息请参阅“上下文可用性”和“加密密码”。

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

步骤显示在 GitHub 上的名称。

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

选择要作为作业中步骤的一部分运行的操作。 操作是一种可重复使用的代码单位。 您可以使用工作流程所在仓库中、公共仓库中或发布 Docker 容器映像中定义的操作。

强烈建议指定 Git ref、SHA 或 Docker 标记编号来包含所用操作的版本。 如果不指定版本,在操作所有者发布更新时可能会中断您的工作流程或造成非预期的行为。

  • 使用已发行操作版本的 SHA 对于稳定性和安全性是最安全的。
  • 使用特定主要操作版本可在保持兼容性的同时接收关键修复和安全补丁。 还可确保您的工作流程继续工作。
  • 使用操作的默认分支可能很方便,但如果有人新发布具有突破性更改的主要版本,您的工作流程可能会中断。

有些操作要求必须通过 with 关键词设置输入。 请查阅操作的自述文件,确定所需的输入。

操作为 JavaScript 文件或 Docker 容器。 如果您使用的操作是 Docker 容器,则必须在 Linux 环境中运行作业。 更多详情请参阅 runs-on

示例:使用版本化操作

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

示例:使用公共操作

{owner}/{repo}@{ref}

您可以指定公共 GitHub 仓库中的分支、引用或 SHA。

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

示例:在子目录中使用公共操作

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

公共 GitHub 仓库中特定分支、引用或 SHA 上的子目录。

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

示例:使用工作流程所在仓库中操作

./path/to/dir

包含工作流程的仓库中操作的目录路径。 在使用操作之前,必须检出仓库。

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

示例:使用 Docker 中枢操作

docker://{image}:{tag}

Docker 中枢上发布的 Docker 映像。

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

示例:使用 Docker 公共注册表操作

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

公共注册表中的 Docker 映像。 此示例在 gcr.io 使用 Google Container Registry。

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

示例:在不同于工作流程的私有仓库中使用操作

您的工作流程必须检出私有仓库,并在本地引用操作。 生成个人访问令牌并将该令牌添加为加密密钥。 更多信息请参阅“创建个人访问令牌”和“加密密码”。

将示例中的 PERSONAL_ACCESS_TOKEN 替换为您的密钥名称。

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

使用操作系统 shell 运行命令行程序。 如果不提供 name,步骤名称将默认为 run 命令中指定的文本。

命令默认使用非登录 shell 运行。 您可以选择不同的 shell,也可以自定义用于运行命令的 shell。 更多信息请参阅 jobs.<job_id>.steps[*].shell

每个 run 关键词代表运行器环境中一个新的进程和 shell。 当您提供多行命令时,每行都在同一个 shell 中运行。 例如:

  • 单行命令:

    - name: Install Dependencies
      run: npm install
    
  • 多行命令:

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

使用 working-directory 关键词,您可以指定运行命令的工作目录位置。

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

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

您可以使用 shell 关键词覆盖运行器操作系统中默认的 shell 设置。 您可以使用内置的 shell 关键词,也可以自定义 shell 选项集。 内部运行的 shell 命令执行一个临时文件,其中包含 run 关键词中指定的命令。

支持的平台shell 参数描述内部运行命令
所有bash非 Windows 平台上回退到 sh 的默认 shell。 指定 Windows 上的 bash shell 时,将使用 Git for Windows 随附的 bash shel。bash --noprofile --norc -eo pipefail {0}
所有pwshPowerShell Core。 GitHub 将扩展名 .ps1 附加到您的脚本名称。pwsh -command ". '{0}'"
所有python执行 python 命令。python {0}
Linux / macOSsh未提供 shell 且 在路径中找不到 bash 时的非 Windows 平台的后退行为。sh -e {0}
WindowscmdGitHub 将扩展名 .cmd 附加到您的脚本名称并替换 {0}%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
Windowspwsh这是 Windows 上使用的默认 shell。 PowerShell Core。 GitHub 将扩展名 .ps1 附加到您的脚本名称。 如果自托管的 Windows 运行器没有安装 PowerShell Core,则使用 PowerShell Desktop 代替。pwsh -command ". '{0}'".
WindowspowershellPowerShell 桌面。 GitHub 将扩展名 .ps1 附加到您的脚本名称。powershell -command ". '{0}'".

示例:使用 bash 运行脚本

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

示例:使用 Windows cmd 运行脚本

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

示例:使用 PowerShell Core 运行脚本

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

示例:使用 PowerShell 桌面运行脚本

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

示例:运行 python 脚本

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

自定义 shell

您可以使用 command […options] {0} [..more_options]shell 值设置为模板字符串。 GitHub 将字符串的第一个用空格分隔的词解释为命令,并在 {0} 处插入临时脚本的文件名。

例如:

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

此示例中使用的命令 perl 必须安装在运行器上。

退出代码和错误操作首选项

至于内置的 shell 关键词,我们提供由 GitHub 托管运行程序执行的以下默认值。 在运行 shell 脚本时,您应该使用这些指南。

  • bash/sh

    • 使用 set -eo pipefail 的快速失败行为:bash 和内置 shell 的默认值。 它还是未在非 Windows 平台上提供选项时的默认值。
    • 您可以向 shell 选项提供模板字符串,以退出快速失败并接管全面控制权。 例如 bash {0}
    • sh 类 shell 使用脚本中最后执行的命令的退出代码退出,也是操作的默认行为。 运行程序将根据此退出代码将步骤的状态报告为失败/成功。
  • powershell/pwsh

    • 可能时的快速失败行为。 对于 pwshpowershell 内置 shell,我们将 $ErrorActionPreference = 'stop' 附加到脚本内容。
    • 我们将 if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } 附加到 powershell 脚本,以使操作状态反映脚本的最后一个退出代码。
    • 用户可随时通过不使用内置 shell 并提供类似如下的自定义 shell 选项来退出:pwsh -File {0}powershell -Command "& '{0}'",具体取决于需求。
  • cmd

    • 除了编写脚本来检查每个错误代码并相应地响应之外,似乎没有办法完全选择快速失败行为。 由于我们默认不能实际提供该行为,因此您需要将此行为写入脚本。
    • cmd.exe 在退出时带有其执行的最后一个程序的错误等级,并且会将错误代码返回到运行程序。 此行为在内部与上一个 shpwsh 默认行为一致,是 cmd.exe 的默认值,所以此行为保持不变。

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

输入参数的 map 由操作定义。 每个输入参数都是一个键/值对。 输入参数被设置为环境变量。 该变量的前缀为 INPUT_,并转换为大写。

示例

定义 hello_world 操作所定义的三个输入参数(first_namemiddle_namelast_name)。 这些输入变量将被 hello-world 操作作为 INPUT_FIRST_NAMEINPUT_MIDDLE_NAMEINPUT_LAST_NAME 环境变量使用。

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

string 定义 Docker 容器的输入。 GitHub 在容器启动时将 args 传递到容器的 ENTRYPOINT。 此参数不支持 array of strings

示例

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.

args 用来代替 Dockerfile 中的 CMD 指令。 如果在 Dockerfile 中使用 CMD,请遵循按偏好顺序排序的指导方针:

  1. 在操作的自述文件中记录必要的参数,并在 CMD 指令的中忽略它们。
  2. 使用默认值,允许不指定任何 args 即可使用操作。
  3. 如果操作显示 --help 标记或类似项,请将其用作默认值,以便操作自行记录。

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

覆盖 Dockerfile 中的 Docker ENTRYPOINT,或在未指定时设置它。 与包含 shell 和 exec 表单的 Docker ENTRYPOINT 指令不同,entrypoint 关键词只接受定义要运行的可执行文件的单个字符串。

示例

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

entrypoint 关键词旨在用于 Docker 容器操作,但您也可以将其用于未定义任何输入的 JavaScript 操作。

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

设置供步骤用于运行器环境的环境变量。 您也可以设置整个工作流程或某个作业的环境变量。 更多信息请参阅 envjobs.<job_id>.env

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

公共操作可在自述文件中指定预期的环境变量。 如果要在环境变量中设置密码,必须使用 secrets 上下文进行设置。 更多信息请参阅“使用环境变量”和“上下文”。

示例

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

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

防止步骤失败时作业也会失败。 设置为 true 以允许在此步骤失败时作业能够通过。

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

终止进程之前运行该步骤的最大分钟数。

jobs.<job_id>.timeout-minutes

在 GitHub 自动取消运行之前可让作业运行的最大分钟数。 默认值:360

如果超时超过运行器的作业执行时限,作业将在达到执行时限时取消。 有关作业执行时间限制的更多信息,请参阅 “使用限制和计费”(对于 GitHub 托管的运行器)和 “关于自托管的运行器”(对于自托管运行器使用限制)。

注意: The GITHUB_TOKEN expires when a job finishes or after a maximum of 24 hours. 对于自托管运行器,如果作业超时大于 24 小时,则令牌可能是限制因素。 有关 GITHUB_TOKEN 的更多信息,请参阅“关于 GITHUB_TOKEN 机密”。

jobs.<job_id>.strategy

使用 jobs.<job_id>.strategy 为您的任务使用矩阵策略。 A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems. 更多信息请参阅“对作业使用矩阵”。

jobs.<job_id>.strategy.matrix

Use jobs.<job_id>.strategy.matrix to define a matrix of different job configurations. Within your matrix, define one or more variables followed by an array of values. For example, the following matrix has a variable called version with the value [10, 12, 14] and a variable called os with the value [ubuntu-latest, windows-latest]:

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

A job will run for each possible combination of the variables. In this example, the workflow will run six jobs, one for each combination of the os and version variables.

By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. The order of the variables in the matrix determines the order in which the jobs are created. The first variable you define will be the first job that is created in your workflow run. For example, the above matrix will create the jobs in the following order:

  • {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}

A matrix will generate a maximum of 256 jobs per workflow run. This limit applies to both GitHub Enterprise Server-hosted and self-hosted runners.

The variables that you define become properties in the matrix context, and you can reference the property in other areas of your workflow file. In this example, you can use matrix.version and matrix.os to access the current value of version and os that the job is using. 更多信息请参阅“上下文”。

示例:使用单维矩阵

You can specify a single variable to create a single-dimension matrix.

For example, the following workflow defines the variable version with the values [10, 12, 14]. The workflow will run three jobs, one for each value in the variable. Each job will access the version value through the matrix.version context and pass the value as node-version to the actions/setup-node action.

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

示例:使用多维矩阵

You can specify multiple variables to create a multi-dimensional matrix. A job will run for each possible combination of the variables.

For example, the following workflow specifies two variables:

  • Two operating systems specified in the os variable
  • Three Node.js versions specified in the version variable

The workflow will run six jobs, one for each combination of the os and version variables. Each job will set the runs-on value to the current os value and will pass the current version value to the actions/setup-node action.

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

示例:使用上下文创建矩阵

You can use contexts to create matrices. 有关上下文的更多信息,请参阅“上下文”。

For example, the following workflow triggers on the repository_dispatch event and uses information from the event payload to build the matrix. When a repository dispatch event is created with a payload like the one below, the matrix version variable will have a value of [12, 14, 16]. For more information about the repository_dispatch trigger, see "Events that trigger workflows."

{
  "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

Use jobs.<job_id>.strategy.matrix.include to expand existing matrix configurations or to add new configurations. The value of include is a list of objects.

For each object in the include list, the key:value pairs in the object will be added to each of the matrix combinations if none of the key:value pairs overwrite any of the original matrix values. If the object cannot be added to any of the matrix combinations, a new matrix combination will be created instead. Note that the original matrix values will not be overwritten, but added matrix values can be overwritten.

For example, this matrix:

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

will result in six jobs with the following matrix combinations:

  • {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}

following this logic:

  • {color: green} is added to all of the original matrix combinations because it can be added without overwriting any part of the original combinations.
  • {color: pink, animal: cat} adds color:pink only to the original matrix combinations that include animal: cat. This overwrites the color: green that was added by the previous include entry.
  • {fruit: apple, shape: circle} adds shape: circle only to the original matrix combinations that include fruit: apple.
  • {fruit: banana} cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination.
  • {fruit: banana, animal: cat} cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination. It does not add to the {fruit: banana} matrix combination because that combination was not one of the original matrix combinations.

示例:展开配置

For example, the following workflow will run six jobs, one for each combination of os and node. When the job for the os value of windows-latest and node value of 16 runs, an additional variable called npm with the value of 6 will be included in the job.

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

示例:添加配置

For example, this matrix will run 10 jobs, one for each combination of os and version in the matrix, plus a job for the os value of windows-latest and version value of 17.

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

If you don't specify any matrix variables, all configurations under include will run. For example, the following workflow would run two jobs, one for each include entry. This lets you take advantage of the matrix strategy without having a fully populated matrix.

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

To remove specific configurations defined in the matrix, use jobs.<job_id>.strategy.matrix.exclude. An excluded configuration only has to be a partial match for it to be excluded. For example, the following workflow will run nine jobs: one job for each of the 12 configurations, minus the one excluded job that matches {os: macos-latest, version: 12, environment: production}, and the two excluded jobs that match {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 }}

注意:所有 include 组合在 exclude 后处理。 这允许您使用 include 添加回以前排除的组合。

jobs.<job_id>.strategy.fail-fast

You can control how job failures are handled with jobs.<job_id>.strategy.fail-fast and jobs.<job_id>.continue-on-error.

jobs.<job_id>.strategy.fail-fast applies to the entire matrix. If jobs.<job_id>.strategy.fail-fast is set to true, GitHub Enterprise Server will cancel all in-progress and queued jobs in the matrix if any job in the matrix fails. This property defaults to true.

jobs.<job_id>.continue-on-error applies to a single job. If jobs.<job_id>.continue-on-error is true, other jobs in the matrix will continue running even if the job with jobs.<job_id>.continue-on-error: true fails.

You can use jobs.<job_id>.strategy.fail-fast and jobs.<job_id>.continue-on-error together. For example, the following workflow will start four jobs. For each job, continue-on-error is determined by the value of matrix.experimental. If any of the jobs with continue-on-error: false fail, all jobs that are in progress or queued will be cancelled. If the job with continue-on-error: true fails, the other jobs will not be affected.

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

By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. To set the maximum number of jobs that can run simultaneously when using a matrix job strategy, use jobs.<job_id>.strategy.max-parallel.

For example, the following workflow will run a maximum of two jobs at a time, even if there are runners available to run all six jobs at once.

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

jobs.<job_id>.continue-on-error

防止工作流程运行在作业失败时失败。 设置为 true 以允许工作流程运行在此作业失败时通过。

示例:防止特定失败的矩阵作业无法运行工作流程

您可以允许作业矩阵中的特定任务失败,但工作流程运行不失败。 例如, 只允许 node 设置为 15 的实验性作业失败,而不允许工作流程运行失败。

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

jobs.<job_id>.container

Note: If your workflows use Docker container actions, job containers, or service containers, then you must use a Linux runner:

  • 如果您要使用 GitHub 托管的运行器,则必须使用 Ubuntu 运行器。
  • 如果您要使用自托管运行器,则必须使用 Linux 机器作为运行器,并且必须安装 Docker。

Use jobs.<job_id>.container to create a container to run any steps in a job that don't already specify a container. 如有步骤同时使用脚本和容器操作,则容器操作将运行为同一网络上使用相同卷挂载的同级容器。

若不设置 container,所有步骤将直接在 runs-on 指定的主机上运行,除非步骤引用已配置为在容器中运行的操作。

Example: Running a job within a container

jobs:
  my_job:
    container:
      image: node:14.16
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1

只指定容器映像时,可以忽略 image 关键词。

jobs:
  my_job:
    container: node:14.16

jobs.<job_id>.container.image

Use jobs.<job_id>.container.image to define the Docker image to use as the container to run the action. The value can be the Docker Hub image name or a registry name.

jobs.<job_id>.container.credentials

如果映像的容器注册表需要身份验证才能拉取映像,可以使用 jobs.<job_id>.container.credentials 设置 usernamepasswordmap。 凭据与您提供给 Docker 登录 命令的值相同。

Example: Defining credentials for a container registry

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

jobs.<job_id>.container.env

Use jobs.<job_id>.container.env to set a map of environment variables in the container.

jobs.<job_id>.container.ports

Use jobs.<job_id>.container.ports to set an array of ports to expose on the container.

jobs.<job_id>.container.volumes

Use jobs.<job_id>.container.volumes to set an array of volumes for the container to use. 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。

要指定卷,需指定来源和目标路径:

<source>:<destinationPath>.

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

Example: Mounting volumes in a container

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

jobs.<job_id>.container.options

Use jobs.<job_id>.container.options to configure additional Docker container resource options. 有关选项列表,请参阅“docker create options”。

警告:不支持 --network 选项。

jobs.<job_id>.services

Note: If your workflows use Docker container actions, job containers, or service containers, then you must use a Linux runner:

  • 如果您要使用 GitHub 托管的运行器,则必须使用 Ubuntu 运行器。
  • 如果您要使用自托管运行器,则必须使用 Linux 机器作为运行器,并且必须安装 Docker。

用于为工作流程中的作业托管服务容器。 服务容器可用于创建数据库或缓存服务(如 Redis)。 运行器自动创建 Docker 网络并管理服务容器的生命周期。

如果将作业配置为在容器中运行,或者步骤使用容器操作,则无需映射端口来访问服务或操作。 Docker 会自动在同一个 Docker 用户定义的桥接网络上的容器之间显示所有端口。 您可以直接引用服务容器的主机名。 主机名自动映射到为工作流程中的服务配置的标签名称。

如果配置作业直接在运行器机器上运行,且您的步骤不使用容器操作,则必须将任何必需的 Docker 服务容器端口映射到 Docker 主机(运行器机器)。 您可以使用 localhost 和映射的端口访问服务容器。

有关网络服务容器之间差异的更多信息,请参阅“关于服务容器”。

示例:使用 localhost

此示例创建分别用于 nginx 和 redis 的两项服务。 指定 Docker 主机端口但不指定容器端口时,容器端口将随机分配给空闲端口。 GitHub 在 ${{job.services.<service_name>.ports}} 上下文中设置分配的容器端口。 在此示例中,可以使用 ${{ job.services.nginx.ports['8080'] }}${{ job.services.redis.ports['6379'] }} 上下文访问服务容器端口。

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

要用作运行操作的服务容器的 Docker 图像。 值可以是 Docker Hub 映像名称或注册表名称。

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

如果映像的容器注册表需要身份验证才能拉取映像,可以使用 jobs.<job_id>.container.credentials 设置 usernamepasswordmap。 凭据与您提供给 Docker 登录 命令的值相同。

示例

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

在服务容器中设置环境变量的 map

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

设置要在服务容器上显示的端口 array

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

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

要指定卷,需指定来源和目标路径:

<source>:<destinationPath>.

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

示例

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

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

附加 Docker 容器资源选项。 有关选项列表,请参阅“docker create options”。

警告:不支持 --network 选项。

过滤器模式备忘清单

您可以在路径、分支和标记过滤器中使用特殊字符。

  • *: 匹配零个或多个字符,但不匹配 / 字符。 例如,Octo* 匹配 Octocat
  • **: 匹配零个或多个任何字符。
  • ?:匹配零个或一个前缀字符。
  • +: 匹配一个或多个前置字符。
  • [] 匹配列在括号中或包含在范围内的一个字符。 范围只能包含 a-zA-Z0-9。 例如,范围 [0-9a-z] 匹配任何数字或小写字母。 例如,[CB]at 匹配 CatBat[1-2]00 匹配 100200
  • !:在模式开始时,它将否定以前的正模式。 如果不是第一个字符,它就没有特殊的意义。

字符 *[! 是 YAML 中的特殊字符。 如果模式以 *[! 开头,必须用引号括住模式。

# Valid
- '**/README.md'

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

有关分支、标记和路径筛选器语法的更多信息,请参阅“on.<push>.<branches|tags>”、“on.<pull_request>.<branches|tags>”和“on.<push|pull_request>.paths”。

匹配分支和标记的模式

模式描述示例匹配
feature/** 通配符匹配任何字符,但不匹配斜杠 (/)。feature/my-branch

feature/your-branch
feature/**** 通配符匹配任何字符,包括分支和标记名称中的斜杠 (/)。feature/beta-a/my-branch

feature/your-branch

feature/mona/the/octocat
main

releases/mona-the-octocat
匹配分支或标记名称的确切名称。main

releases/mona-the-octocat
'*'匹配所有不包含斜杠 (/) 的分支和标记名称。 * 字符是 YAML 中的特殊字符。 当模式以 * 开头时,您必须使用引号。main

releases
'**'匹配所有分支和标记名称。 这是不使用 branches or tags 过滤器时的默认行为。all/the/branches

every/tag
'*feature'* 字符是 YAML 中的特殊字符。 当模式以 * 开头时,您必须使用引号。mona-feature

feature

ver-10-feature
v2*匹配以 v2 开头的分支和标记名称。v2

v2.0

v2.9
v[12].[0-9]+.[0-9]+将所有语义版本控制分支和标记与主要版本 1 或 2 匹配.v1.10.1

v2.0.0

匹配文件路径的模式

路径模式必须匹配整个路径,并从仓库根开始。

模式匹配描述示例匹配
'*'* 通配符匹配任何字符,但不匹配斜杠 (/)。 * 字符是 YAML 中的特殊字符。 当模式以 * 开头时,您必须使用引号。README.md

server.rb
'*.jsx?'? 个字符匹配零个或一个前缀字符。page.js

page.jsx
'**'The ** 通配符匹配任何字符,包括斜杠 (/)。 这是不使用 path 过滤器时的默认行为。all/the/files.md
'*.js'* 通配符匹配任何字符,但不匹配斜杠 (/)。 匹配仓库根目录上的所有 .js 文件。app.js

index.js
'**.js'匹配仓库中的所有 .js 文件。index.js

js/index.js

src/js/app.js
docs/*仓库根目录下 docs 根目录中的所有文件。docs/README.md

docs/file.txt
docs/**仓库根目录下 /docs 目录中的任何文件。docs/README.md

docs/mona/octocat.txt
docs/**/*.mddocs 目录中任意位置具有 .md 后缀的文件。docs/README.md

docs/mona/hello-world.md

docs/a/markdown/file.md
'**/docs/**'仓库中任意位置 docs 目录下的任何文件。docs/hello.md

dir/docs/my-file.txt

space/docs/plan/space.doc
'**/README.md'仓库中任意位置的 README.md 文件。README.md

js/README.md
'**/*src/**'仓库中任意位置具有 src 后缀的文件夹中的任何文件。a/src/app.js

my-src/code/js/app.js
'**/*-post.md'仓库中任意位置具有后缀 -post.md 的文件。my-post.md

path/their-post.md
'**/migrate-*.sql'仓库中任意位置具有前缀 migrate- 和后缀 .sql 的文件。migrate-10909.sql

db/migrate-v1.0.sql

db/sept/migrate-v1.sql
*.md

!README.md
模式前使用感叹号 (!) 对其进行否定。 当文件与模式匹配并且也匹配文件后面定义的否定模式时,则不包括该文件。hello.md

Does not match

README.md

docs/hello.md
*.md

!README.md

README*
按顺序检查模式。 否定前一个模式的模式将重新包含文件路径。hello.md

README.md

README.doc