Skip to main content

此版本的 GitHub Enterprise 已停止服务 2023-01-18. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

触发工作流程

如何自动触发 GitHub Actions 工作流程

注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

关于工作流程触发器

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

  • 工作流程存储库中发生的事件
  • 在 GitHub Enterprise Server 之外发生并在 GitHub Enterprise Server 上触发 repository_dispatch 事件的事件
  • 预定时间
  • 手动

例如,您可以将工作流程配置为在推送到存储库的默认分支、创建发行版或打开议题时运行。

工作流触发器使用 on 键定义。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。

以下步骤将触发工作流程运行:

  1. 存储库上发生事件。 该事件具有关联的提交 SHA 和 Git 引用。

  2. GitHub Enterprise Server 在存储库的 .github/workflows 目录中搜索事件的关联提交 SHA 或 Git 引用中存在的工作流文件。

  3. 对于具有与触发事件匹配的 on: 值的任何工作流,触发工作流运行。 某些事件还要求工作流程文件位于存储库的默认分支上才能运行。

    每个工作流程运行都将使用事件的关联提交 SHA 或 Git ref 中存在的工作流程版本。 当工作流运行时,GitHub Enterprise Server 会在运行器环境中设置 GITHUB_SHA(提交 SHA)和 GITHUB_REF(Git 引用)环境变量。 有关详细信息,请参阅“变量”。

从工作流程触发工作流程

使用存储库的 GITHUB_TOKEN 执行任务时,GITHUB_TOKEN 将不会创建新的工作流运行。 这可以防止意外创建递归工作流程运行。 例如,如果工作流运行使用存储库的 GITHUB_TOKEN 推送代码,则即使存储库包含配置为在 push 事件发生时运行的工作流,新工作流也不会运行。 有关详细信息,请参阅“使用 GITHUB_TOKEN 进行身份验证”。

如果确实要从工作流运行中触发工作流,则可以使用 personal access token(而不是 GITHUB_TOKEN)来触发需要令牌的事件。 你需要创建 personal access token 并将其存储为机密。 为了最大限度地降低 GitHub Actions 使用成本,请确保不要创建递归或意外的工作流程。 有关创建 personal access token 的详细信息,请参阅“创建 personal access token”。 有关将 personal access token 存储为机密的详细信息,请参阅“创建和存储加密机密”。

例如,以下工作流使用 personal access token(存储为称为 MY_TOKEN 的机密)通过 GitHub CLI 向问题添加标签。 添加标签时运行的任何工作流程都将在执行此步骤后运行。

on:
  issues:
    types:
      - opened

jobs:
  label_issue:
    runs-on: ubuntu-latest
    steps:
      - env:
          GITHUB_TOKEN: ${{ secrets.MY_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}
        run: |
          gh issue edit $ISSUE_URL --add-label "triage"

相反,以下工作流使用 GITHUB_TOKEN 向问题添加标签。 它不会触发在添加标签时运行的任何工作流程。

on:
  issues:
    types:
      - opened

jobs:
  label_issue:
    runs-on: ubuntu-latest
    steps:
      - env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}
        run: |
          gh issue edit $ISSUE_URL --add-label "triage"

使用事件触发工作流程

使用 on 键指定触发工作流的事件。 有关可以使用的事件的详细信息,请参阅“触发工作流的事件”。

使用单个事件

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

on: push

使用多个事件

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

on: [push, fork]

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

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

您可以使用活动类型和筛选器进一步控制工作流程的运行时间。 有关详细信息,请参阅使用事件活动类型使用筛选器。 如果为事件指定活动类型或筛选器,并且针对多个事件指定工作流触发器,则必须单独配置每个事件。 必须为所有事件附加冒号 (:),包括没有配置的事件。

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

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

使用事件活动类型

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

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

on:
  label:
    types:
      - created

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

on:
  issues:
    types:
      - opened
      - labeled

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

使用筛选器

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

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

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

使用筛选器定位拉取请求事件的特定分支

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

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

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

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

示例:包括分支

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

  • 名为 main 的分支 (refs/heads/main)
  • 名为 mona/octocat 的分支 (refs/heads/mona/octocat)
  • 名称以 releases/ 开头的分支,如 releases/10 (refs/heads/releases/10)
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'

示例:排除分支

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

  • 名为 mona/octocat 的分支 (refs/heads/mona/octocat)
  • 名称匹配 releases/**-alpha 的分支,如 releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'

示例:包括和排除分支

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

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

您定义模式事项的顺序。

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

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

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

使用筛选器定位推送事件的特定分支或标记

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

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

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

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

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-ignoretags-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 筛选器以及 ! 字符来指示应排除哪些分支或标记。

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

您定义模式事项的顺序。

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

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

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

使用筛选器定位拉取请求或推送事件的特定路径

使用 pushpull_request 事件时,可以配置工作流以根据更改的文件路径运行。 路径筛选器不会针对标记的推送进行评估。

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

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

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-ignorepaths 列表运行它们来确定是否应运行工作流。 如果没有更改文件,工作流程将不会运行。

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

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

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

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

使用筛选器定位工作流程运行事件的特定分支

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

定义手动触发的工作流程的输入

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

触发的工作流在 github.event.inputs 上下文中接收输入。 有关详细信息,请参阅“上下文。”

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

使用事件信息

有关触发工作流运行的事件的信息可在 github.event 上下文中找到。 上下文中的 github.event 属性取决于触发工作流的事件的类型。 例如,在标记议题时触发的工作流程将包含有关议题和标签的信息。

查看事件的所有属性

有关常见属性和示例负载,请参阅 web 挂钩事件文档。 有关详细信息,请参阅“Webhook 事件和有效负载”。

你还可以将整个 github.event 上下文打印出来,以查看哪些属性可用于触发工作流的事件:

jobs:
  print_context:
    runs-on: ubuntu-latest
    steps:
      - env:
          EVENT_CONTEXT: ${{ toJSON(github.event) }}
        run: |
          echo $EVENT_CONTEXT

访问和使用事件属性

你可以在工作流中使用 github.event 上下文。 例如,以下工作流在打开更改 package*.json.github/CODEOWNERS.github/workflows/** 的拉取请求时运行。 如果拉取请求作者 (github.event.pull_request.user.login) 不是 octobotdependabot[bot],则工作流使用 GitHub CLI 来标记和注释拉取请求 (github.event.pull_request.number)。

on:
  pull_request:
    types:
      - opened
    paths:
      - '.github/workflows/**'
      - '.github/CODEOWNERS'
      - 'package*.json'

jobs:
  triage:
    if: >-
      github.event.pull_request.user.login != 'octobot' &&
      github.event.pull_request.user.login != 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: "Comment about changes we can't accept"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ github.event.pull_request.html_url }}
        run: |
          gh pr edit $PR --add-label 'invalid'
          gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. We do not allow contributions to these files. Please review our [contributing guidelines](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) for what contributions are accepted.'

有关上下文的详细信息,请参阅“上下文”。 有关事件负载的详细信息,请参阅“Webhook 事件和负载”。

进一步控制工作流程的运行方式

如果需要比事件、事件活动类型或事件筛选器更精细的控制,则可以使用条件和环境来控制工作流中的单个作业或步骤是否运行。

使用条件

您可以使用条件进一步控制工作流程中的作业或步骤是否运行。

在事件负载中使用值的示例

例如,如果希望在向问题添加特定标签时运行工作流,则可以在 issues labeled 事件活动类型上触发,并使用条件来检查触发工作流的标签。 将任何标签添加到工作流的存储库中的问题时,将运行以下工作流,但仅当标签命名为 bug 时,才会执行 run_if_label_matches 作业。

on:
  issues:
    types:
      - labeled

jobs:
  run_if_label_matches:
    if: github.event.label.name == 'bug'
    runs-on: ubuntu-latest
    steps:
      - run: echo 'The label was bug'

使用事件类型的示例

例如,如果要根据触发工作流程的事件运行不同的作业或步骤,则可以使用条件来检查事件上下文中是否存在特定的事件类型。 每当议题或拉取请求关闭时,将运行以下工作流程。 如果工作流因问题已关闭而运行,则 github.event 上下文将包含 issue 的值,但不包含 pull_request 的值。 因此,if_issue 步骤将运行,但 if_pr 步骤不会运行。 相反,如果工作流因拉取请求关闭而运行,则 if_pr 步骤将运行,但 if_issue 步骤不会运行。

on:
  issues:
    types:
      - closed
  pull_request:
    types:
      - closed

jobs:
  state_event_type:
    runs-on: ubuntu-latest
    steps:
    - name: if_issue
      if: github.event.issue
      run: |
        echo An issue was closed
    - name: if_pr
      if: github.event.pull_request
      run: |
        echo A pull request was closed

有关事件上下文中可用信息的详细信息,请参阅“使用事件信息”。 有关如何使用条件的详细信息,请参阅“表达式”。

使用环境手动触发工作流程作业

如果要手动触发工作流程中的特定作业,可以使用需要特定团队或用户批准的环境。 首先,使用所需的审阅者配置环境。 有关详细信息,请参阅“使用环境进行部署”。 然后,使用environment: 键在工作流的作业中引用环境名称。 在至少有一个审阅者批准该作业之前,引用环境的任何作业都不会运行。

例如,只要有推送到 main 分支,以下工作流程就会运行。 build 作业将始终运行。 只有在 build 作业成功完成(由于 needs: [build])并且称为 production 的环境的所有规则(包括必需的审阅者)通过(由于 environment: production)之后,publish 作业才会运行。

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: build
        echo 'building'

  publish:
    needs: [build]
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: publish
        echo 'publishing'

所有产品的公共存储库提供环境、环境机密和环境保护规则。 要访问专用存储库或内部存储库中的环境、环境机密和部署分支,必须使用 GitHub Pro、GitHub Team 或 GitHub Enterprise 。 要访问专用存储库或内部存储库中的其他环境保护规则,必须使用 GitHub Enterprise 。

可用事件

有关可用事件的完整列表,请参阅“触发工作流的事件”。