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

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

您可以定义可以触发工作流程的单个或多个事件,或设置时间表。 您还可以将工作流程的执行限于仅针对特定文件、标记或分支更改执行。 以下各节介绍了这些选项。

使用单个事件

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

on: push

使用多个事件

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

on: [push, fork]

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

使用活动类型

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

例如,issue_comment 事件具有 createdediteddeleted 活动类型。 如果您的工作流程在发生 label 事件时触发,则每当创建、编辑或删除标签时,该工作流程都会运行。 如果为 label 事件指定 created 活动类型,则工作流程将在创建标签时运行,但在编辑或删除标签时不会运行。

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 事件由多种活动触发。 例如,label 在标签 createdediteddeleted 时触发。 通过 types 关键词可缩小触发工作流程运行的活动类型的范围。 如果只有一种活动类型可触发 web 挂钩事件,就没有必要使用 types 关键词。

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

on:
  label:
    types: [created, edited]

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

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

如果要包括分支名称模式,或者要同时包含和排除分支名称模式,请使用 branches 筛选器。 只需要排除分支名称模式时,请使用 branches-ignore 过滤器。 不能同时对工作流程中的同一事件使用 branchesbranches-ignore 筛选器。

如果同时定义 branches/branches-ignorepaths,则工作流程仅在同时满足两个筛选器时才会运行。

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

示例:包括分支

branches 中定义的模式根据 Git ref 的名称进行评估。 例如,每当存在针对拉取请求目标的 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 ref 的名称进行评估。 例如,每当存在 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'

示例:包括和排除分支

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

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

您定义模式事项的顺序。

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

对于针对 releases/10releases/beta/mona 的拉取请求,以下工作流程将在发生 pull_request 事件时运行,但对于针对 releases/10-alphareleases/beta/3-alpha 的拉取请求不会运行,因为否定模式 !releases/**-alpha 后跟肯定模式。

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

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

使用 push 事件时,您可以将工作流程配置为在特定分支或标签上运行。

如果要包括分支名称模式,或者要同时包含和排除分支名称模式,请使用 branches 筛选器。 只需要排除分支名称模式时,请使用 branches-ignore 过滤器。 不能同时对工作流程中的同一事件使用 branchesbranches-ignore 筛选器。

如果要包括分支名称模式,或者要同时包含和排除分支名称模式,请使用 tags 筛选器。 当您只想排除标记名称模式时,请使用 tags-ignore 筛选器。 不能同时对工作流程中的同一事件使用 tagstags-ignore 筛选器。

如果只定义 tags/tags-ignore 或只定义 branches/branches-ignore,则影响未定义 Git ref 的事件不会触发工作流程运行。 如果未定义 tags/tags-ignorebranches/branches-ignore,则工作流程将针对影响分支或标记的事件运行。 如果同时定义 branches/branches-ignorepaths,则工作流程仅在同时满足两个筛选器时才会运行。

branchesbranches-ignoretagstags-ignore 关键词接受使用 ***+?! 等字符匹配多个分支或标记名称的 glob 模式。 如果名称包含其中任一字符,而您想要逐字匹配,则需要使用 \ 转义每个特殊字符。 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。

示例:包括分支和标记

branchestags 中定义的模式根据 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 or tags-ignore 模式匹配时,工作流程不会运行。 在 branchestags 中定义的模式根据 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.*

示例:包括和排除分支和标记

不能使用 branchesbranches-ignore 来筛选单个工作流程中的同一事件。 同样,您不能使用 tagstags-ignore 在单个工作流程中筛选同一事件。 如果要同时包含和排除单个事件的分支模式,请使用 branchestags 筛选器与 ! 字符指示应排除哪些分支或标记。

如果使用 ! 字符定义分支,还必须定义至少一个不带 ! 字符的分支。 如果只想排除分支,请改用 paths-ignore。 类似地,如果使用 ! 字符定义标记,还必须定义至少一个不带 ! 字符的标记。 如果只想排除标记,请改用 paths-ignore

您定义模式事项的顺序。

  • 肯定匹配后的匹配否定模式(前缀为 !)将排除 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>

使用 pushpull_request 事件时,可以将工作流程配置为根据更改的文件路径运行。 路径过滤器不评估标签的推送。

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

如果同时定义 branches/branches-ignorepaths,则工作流程仅在同时满足两个筛选器时才会运行。

pathspaths-ignore 关键词接受使用 *** 通配符匹配多个路径名称的 glob 模式。 更多信息请参阅“过滤器模式备忘清单”。

示例:包括路径

如果至少有一个路径与 paths 过滤器中的模式匹配,工作流程将会运行。 例如,以下工作流程将在推送 JavaScript 文件 (.js) 时运行。

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

注意:如果由于路径过滤分支过滤提交消息而跳过工作流程,则与该工作流程关联的检查将保持“挂起”状态。 需要这些检查成功的拉取请求将被阻止合并。 更多信息请参阅“处理已跳过但必要的检查”。

示例:排除路径

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

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

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

示例:包括和排除路径

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

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

您定义模式事项的顺序:

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

只要 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

可以使用 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 * * *'

单个工作流程可由多个计划事件触发。 您可以通过 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_call

注意:可重用工作流程目前处于测试阶段,可能会发生变化。

使用 on.workflow_call 定义可重用工作流程的输入和输出。 您还可以映射可用于被调用工作流程的机密。 有关可重用工作流程的详细信息,请参阅“重用工作流程”。

on.workflow_call.inputs

使用 workflow_call 关键字时,可以选择指定从调用方工作流程传递到被调用工作流程的输入。 有关 workflow_call 关键字的更多信息,请参阅“触发工作流程的事件”。

除了可用的标准输入参数外,on.workflow_call.inputs 还需要 type 参数。 更多信息请参阅 on.workflow_call.inputs.<input_id>.type

如果未设置 default 参数,则输入的默认值对于布尔值为 false ,对于数字为 0,对于字符串为 ""

在被调用的工作流程中,可以使用 inputs 上下文来引用输入。

如果调用方工作流程传递的输入未在被调用工作流程中指定,则会导致错误。

示例

on:
  workflow_call:
    inputs:
      username:
        description: 'A username passed from the caller workflow'
        default: 'john-doe'
        required: false
        type: string

jobs:
  print-username:
    runs-on: ubuntu-latest

    steps:
      - name: Print the input name to STDOUT
        run: echo The username is ${{ inputs.username }}

更多信息请参阅“重用工作流程”。

on.workflow_call.inputs.<input_id>.type

在为 on.workflow_call 关键字定义了输入时必需。 此参数的值是指定输入的数据类型的字符串。 这必须是以下之一:booleannumberstring

on.workflow_call.outputs

被调用工作流程的输出映射。 调用的工作流程输出可用于调用方工作流程中的所有下游作业。 每个输出都有标识符、可选的 descriptionvalue。必须将 value 设置为被调用工作流程中作业的输出值。

在下面的示例中,为此可重用工作流定义了两个输出:workflow_output1workflow_output2。 它们映射到名为 job_output1job_output2 的输出,两者都来自名为 my_job 的作业。

示例

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      workflow_output1:
        description: "The first job output"
        value: ${{ jobs.my_job.outputs.job_output1 }}
      workflow_output2:
        description: "The second job output"
        value: ${{ jobs.my_job.outputs.job_output2 }}

有关如何引用作业输出的信息,请参阅 jobs.<job_id>.outputs。 更多信息请参阅“重用工作流程”。

on.workflow_call.secrets

可在被调用工作流程中使用的机密的映射。

在被调用的工作流程中,可以使用 secrets 上下文来引用机密。

如果调用方工作流程传递的机密未在被调用的工作流程中指定,则会导致错误。

示例

on:
  workflow_call:
    secrets:
      access-token:
        description: 'A token passed from the caller workflow'
        required: false

jobs:
  pass-secret-to-action:
    runs-on: ubuntu-latest

    steps:
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

on.workflow_call.secrets.<secret_id>

要与机密关联的字符串标识符。

on.workflow_call.secrets.<secret_id>.required

指定是否必须提供机密的布尔值。

on.workflow_run.<branches|branches-ignore>

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

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

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

您定义模式事项的顺序。

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

例如,当名为 Build 的工作流程在名为 releases/10releases/beta/mona(而不是 releases/10-alphareleases/beta/3-alphamain)的分支上运行时,将运行具有以下触发器的工作流程。

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

on.workflow_dispatch.inputs

使用 workflow_dispatch 事件时,您可以选择性指定传递到工作流程的输入。

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

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning' 
        type: choice
        options:
        - info
        - warning
        - debug 
      print_tags:
        description: 'True to print to STDOUT'
        required: true 
        type: boolean 
      tags:
        description: 'Test scenario tags'
        required: true 
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        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 修改授予 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 设置中选择了 Send write tokens to workflows from pull requests(从拉取请求发送写入令牌到工作流程)选项。 更多信息请参阅“管理仓库的 GitHub Actions 设置”。

示例:为 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

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

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

defaults.run

可以使用 defaults.run 为工作流程中的所有 run 步骤提供默认 shellworking-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组成,这些作业在默认情况下并行运行。 要按顺序运行作业,您可以使用 <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_jobmy_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 设置中选择了 Send write tokens to workflows from pull requests(从拉取请求发送写入令牌到工作流程)选项。 更多信息请参阅“管理仓库的 GitHub Actions 设置”。

示例:为特定作业设置权限

此示例显示为将要应用到作业 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

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

示例:需要成功的依赖作业

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

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

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

  1. job1
  2. job2
  3. job3

示例:不需要成功的依赖作业

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

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

jobs.<job_id>.if

您可以使用 jobs.<job_id>.if 条件阻止作业在条件得到满足之前运行。 您可以使用任何支持上下文和表达式来创建条件。

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

示例:仅运行特定存储库的作业

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

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

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

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

选择 GitHub 托管的运行器

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

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

虚拟环境 YAML 工作流程标签 注:
Windows Server 2022 windows-latestwindows-2022 windows-latest 标签目前使用 Windows Server 2022 运行器映像。
Windows Server 2019 windows-2019
Ubuntu 22.04 ubuntu-22.04 Ubuntu 22.04 目前处于公开测试阶段。
Ubuntu 20.04 ubuntu-latestubuntu-20.04
Ubuntu 18.04 ubuntu-18.04
macOS Monterey 12 macos-12
macOS Big Sur 11 macos-latestmacos-11 macos-latest 标签目前使用 macOS 11 运行器映像。
macOS Catalina 10.15 [deprecated] macos-10.15 Migrate to macOS-11 or macOS-12. For more information, see this GitHub blog post.

注意: -latest 虚拟环境是 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,或作为具有 nameurl 的环境变量。 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

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

使用 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

您可以使用 jobs.<job_id>.outputs 为作业创建输出 map。 作业输出可用于所有依赖此作业的下游作业。 有关定义作业依赖项的更多信息,请参阅 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.

当每个作业结束时,在运行器上评估包含表达式的作业输出。 包含密码的输出在运行器上编辑,不会发送至 GitHub Actions。

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

示例:定义作业的输出

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

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

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

jobs.<job_id>.defaults.run

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

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

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

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

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

jobs.<job_id>.steps

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

在工作流程的使用限制之内可运行无限数量的步骤。 更多信息请参阅 “使用限制和计费”(对于 GitHub 托管的运行器)和 “关于自托管的运行器”(对于自托管运行器使用限制)。

示例

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 的快速失败行为:在显式指定 shell: bash 时设置此选项。 默认情况下不应用。
    • 您可以通过向 shell 选项提供模板字符串来完全控制 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 托管的运行器)和 “关于自托管的运行器”(对于自托管运行器使用限制)。

注意: GITHUB_TOKEN 在作业完成时或最多 24 小时后过期。 对于自托管运行器,如果作业超时大于 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 on the combinations of the variables. 例如,可以使用矩阵策略在一种语言的多个版本或多个操作系统上测试代码。 更多信息请参阅“对作业使用矩阵”。

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]

将为每个可能的变量组合运行一个作业。 在此示例中,工作流程将运行六个作业,每个作业对应于 osversion 变量的组合。

默认情况下,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.versionmatrix.os 来访问作业所用 versionos 的当前值。 更多信息请参阅“上下文”。

示例:使用单维矩阵

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

例如,以下工作流程使用值 [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 }}

示例:使用多维矩阵

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

例如,以下工作流程指定了两个变量:

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

工作流程将运行六个作业,每个作业对应于 osversion 变量的组合。 每个作业都会将 runs-on 值设置为当前 os 值,并将当前 version 值传递给 actions/setup-node 操作。

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

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

您可以使用上下文来创建矩阵。 有关上下文的更多信息,请参阅“上下文”。

例如,以下工作流程在发生 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} 矩阵组合中,因为该组合不是原始矩阵组合之一。

示例:展开配置

例如,以下工作流程将运行六个作业,每个作业对应于 osnode 的组合。 当 windows-latest 值为 os16 值为 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

示例:添加配置

例如,此矩阵将运行 10 个作业,矩阵中 osversion 的每个组合各一个作业,再加上一个 windows-latest 值为 os17 值为 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 }}

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

jobs.<job_id>.strategy.fail-fast

您可以使用 jobs.<job_id>.strategy.fail-fast and 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-errortrue,则矩阵中的其他作业将继续运行,即使具有 jobs.<job_id>.continue-on-error: true 的作业失败也一样。

您可以同时使用 jobs.<job_id>.strategy.fail-fastjobs.<job_id>.continue-on-error。 例如,以下工作流程将启动四个作业。 对于每个作业,continue-on-errormatrix.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

防止工作流程运行在作业失败时失败。 设置为 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

注:如果您的工作流程使用 Docker 容器操作、作业容器或服务容器,则必须使用 Linux 运行器:

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

使用 jobs.<job_id>.container 创建一个容器,以在尚未指定容器的作业中运行任何步骤。 如有步骤同时使用脚本和容器操作,则容器操作将运行为同一网络上使用相同卷挂载的同级容器。

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

示例:在容器中运行作业

YAML
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)

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

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 设置 usernamepasswordmap。 凭据与您提供给 Docker 登录 命令的值相同。

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

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 options”。

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

jobs.<job_id>.services

注:如果您的工作流程使用 Docker 容器操作、作业容器或服务容器,则必须使用 Linux 运行器:

  • 如果您要使用 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 选项。

jobs.<job_id>.uses

注意:可重用工作流程目前处于测试阶段,可能会发生变化。

要作为作业运行的可重用工作流程文件的位置和版本。

  • {owner}/{repo}/.github/workflows/{filename}@{ref}

{ref} 可以是 SHA、发布标记或分支名称。 使用提交 SHA 对于稳定性和安全性是最安全的。 更多信息请参阅“GitHub Actions 的安全性增强”。

示例

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

更多信息请参阅“重用工作流程”。

jobs.<job_id>.with

当作业用于调用可重用工作流程时,可以使用 with 来提供传递到被调用工作流程的输入的映射。

传递的任何输入都必须与被调用工作流程中定义的输入规范匹配。

jobs.<job_id>.steps[*].with不同,通过 jobs.<job_id>.with 传递的输入不能作为被调用工作流程中的环境变量使用。 但您可以通过使用 inputs 上下文来引用输入。

示例

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    with:
      username: mona

jobs.<job_id>.with.<input_id>

由输入的字符串标识符和输入的值组成的对。 标识符必须与被调用工作流程中的 on.workflow_call.inputs.<inputs_id> 定义的输入名称匹配。 该值的数据类型必须与被调用工作流程中的 on.workflow_call.inputs.<input_id>.type 定义的类型匹配。

允许的表达式上下文: githubneeds

jobs.<job_id>.secrets

当作业用于调用可重用工作流程时,可以使用 secrets 来提供传递给被调用工作流程的机密映射。

传递的任何机密都必须与被调用工作流程中定义的名称匹配。

示例

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    secrets:
      access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

jobs.<job_id>.secrets.<secret_id>

由机密的字符串标识符和机密的值组成的对。 标识符必须与被调用工作流程中的 on.workflow_call.secrets.<secret_id> 定义的机密名称匹配。

允许的表达式上下文:githubneedssecrets

过滤器模式备忘清单

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

  • *: 匹配零个或多个字符,但不匹配 / 字符。 例如,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