Triggering a workflow

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

About workflow triggers

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

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

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

Workflow triggers are defined with the on key. For more information, see "Workflow syntax for GitHub Actions."

The following steps occur to trigger a workflow run:

An event occurs on your repository. The event has an associated commit SHA and Git ref.
GitHub Enterprise Server searches the .github/workflows directory in your repository for workflow files that are present in the associated commit SHA or Git ref of the event.
A workflow run is triggered for any workflows that have on: values that match the triggering event. Some events also require the workflow file to be present on the default branch of the repository in order to run.

Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, GitHub Enterprise Server sets the GITHUB_SHA (commit SHA) and GITHUB_REF (Git ref) environment variables in the runner environment. For more information, see "Using environment variables."

Triggering a workflow from a workflow

使用存储库的 GITHUB_TOKEN 执行任务时，GITHUB_TOKEN 将不会创建新的工作流运行。这可以防止意外创建递归工作流程运行。例如，如果工作流运行使用存储库的 GITHUB_TOKEN 推送代� �，则即使存储库包含配置为在 push 事件发生时运行的工作流，新工作流也不会运行。 For more information, see "Authenticating with the GITHUB_TOKEN."

If you do want to trigger a workflow from within a workflow run, you can use a personal access token instead of GITHUB_TOKEN to trigger events that require a token. You'll need to create a personal access token and store it as a secret. To minimize your GitHub Actions usage costs, ensure that you don't create recursive or unintended workflow runs. For more information about creating a personal access token, see "Creating a personal access token." For more information about storing a personal access token as a secret, see "Creating and storing encrypted secrets."

For example, the following workflow uses a personal access token (stored as a secret called MY_TOKEN) to add a label to an issue via GitHub CLI. Any workflows that run when a label is added will run once this step is performed.

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"

Conversely, the following workflow uses GITHUB_TOKEN to add a label to an issue. It will not trigger any workflows that run when a label is added.

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"

Using events to trigger workflows

Use the on key to specify what events trigger your workflow. For more information about events you can use, see "Events that trigger workflows."

Using a single event

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

on: push

Using multiple events

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

on: [push, fork]

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

Using activity types and filters with multiple events

You can use activity types and filters to further control when your workflow will run. For more information, see Using event activity types and Using filters. 如果为事件指定活动类型或筛选器，并且针对多个事件指定工作流触发器，则必须单独配置每个事件。必须为所有事件附� 冒号 (:)，包括没有配置的事件。

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

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

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

Using event activity types

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

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

on:
  label:
    types:
      - created

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

on:
  issues:
    types:
      - opened
      - labeled

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

Using filters

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

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

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

Using filters to target specific branches for pull request events

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

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

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

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

示例：包括分支

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

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

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

示例：排除分支

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

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

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

示例：包括和排除分支

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

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

您定义模式事项的顺序。

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

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

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

Using filters to target specific branches or tags for push events

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

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

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

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

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

示例：包括分支和� �记

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

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

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

示例：排除分支和� �记

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

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

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

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

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

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

您定义模式事项的顺序。

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

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

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

Using filters to target specific paths for pull request or push events

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

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

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

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

示例：包括路径

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

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

注意：如果� 路径筛选、分支筛选或提交消息而跳过某工作流，则与该工作流关联的检查将保持为“挂起”状态。要求这些检查成功的拉取请求将被阻止合并。有关详细信息，请参阅“处理已跳过但需要检查”。

示例：排除路径

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

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

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

示例：包括和排除路径

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

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

您定义模式事项的顺序：

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

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

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

Git 差异比较

注意： 如果推送超过 1,000 项提交，或者如果 GitHub � 超时未生成差异，则工作流将始终运行。

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

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

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

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

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

Using filters to target specific branches for workflow run events

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

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

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

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

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

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

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

您定义模式事项的顺序。

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

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

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

Defining inputs for manually triggered workflows

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

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

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

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

Using event information

Information about the event that triggered a workflow run is available in the github.event context. The properties in the github.event context depend on the type of event that triggered the workflow. For example, a workflow triggered when an issue is labeled would have information about the issue and label.

Viewing all properties of an event

Reference the webhook event documentation for common properties and example payloads. For more information, see "Webhook events and payloads."

You can also print the entire github.event context to see what properties are available for the event that triggered your workflow:

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

Accessing and using event properties

You can use the github.event context in your workflow. For example, the following workflow runs when a pull request that changes package*.json, .github/CODEOWNERS, or .github/workflows/** is opened. If the pull request author (github.event.pull_request.user.login) is not octobot or dependabot[bot], then the workflow uses the GitHub CLI to label and comment on the pull request (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.'

For more information about contexts, see "Contexts." For more information about event payloads, see "Webhook events and payloads."

Further controlling how your workflow will run

If you want more granular control than events, event activity types, or event filters provide, you can use conditionals and environments to control whether individual jobs or steps in your workflow will run.

Using conditionals

You can use conditionals to further control whether jobs or steps in your workflow will run.

Example using a value in the event payload

For example, if you want the workflow to run when a specific label is added to an issue, you can trigger on the issues labeled event activity type and use a conditional to check what label triggered the workflow. The following workflow will run when any label is added to an issue in the workflow's repository, but the run_if_label_matches job will only execute if the label is named bug.

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'

Example using event type

For example, if you want to run different jobs or steps depending on what event triggered the workflow, you can use a conditional to check whether a specific event type exists in the event context. The following workflow will run whenever an issue or pull request is closed. If the workflow ran because an issue was closed, the github.event context will contain a value for issue but not for pull_request. Therefore, the if_issue step will run but the if_pr step will not run. Conversely, if the workflow ran because a pull request was closed, the if_pr step will run but the if_issue step will not run.

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

For more information about what information is available in the event context, see "Using event information." For more information about how to use conditionals, see "Expressions."

Using environments to manually trigger workflow jobs

If you want to manually trigger a specific job in a workflow, you can use an environment that requires approval from a specific team or user. First, configure an environment with required reviewers. For more information, see "Using environments for deployment." Then, reference the environment name in a job in your workflow using the environment: key. Any job referencing the environment will not run until at least one reviewer approves the job.

For example, the following workflow will run whenever there is a push to main. The build job will always run. The publish job will only run after the build job successfully completes (due to needs: [build]) and after all of the rules (including required reviewers) for the environment called production pass (due to environment: production).

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 。

Available events

For a full list of available events, see "Events that trigger workflows."

Triggering a workflow

本文内容

About workflow triggers

Triggering a workflow from a workflow

Using events to trigger workflows

Using a single event

Using multiple events

Using activity types and filters with multiple events

Using event activity types

Using filters

Using filters to target specific branches for pull request events

示例：包括分支

示例：排除分支

示例：包括和排除分支

Using filters to target specific branches or tags for push events

示例：包括分支和� �记

示例：排除分支和� �记

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

Using filters to target specific paths for pull request or push events

示例：包括路径

示例：排除路径

示例：包括和排除路径

Git 差异比较

Using filters to target specific branches for workflow run events

Defining inputs for manually triggered workflows

Using event information

Viewing all properties of an event

Accessing and using event properties

Further controlling how your workflow will run

Using conditionals

Example using a value in the event payload

Example using event type

Using environments to manually trigger workflow jobs

Available events