触发工作流程

关于工作流程触发器

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

• 工作流程存储库中发生的事件
• 在 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 引用）环境变量。 更多信息请参阅“使用环境变量”。

从工作流程触发工作流程

When you use the repository's GITHUB_TOKEN to perform tasks, events triggered by the GITHUB_TOKEN will not create a new workflow run. 这可以防止意外创建递归工作流程运行。 例如，如果工作流程运行使用仓库的 GITHUB_TOKEN 推送代� �，则即使仓库包含配置为在 push 事件发生时运行的工作流程，新工作流程也不会运行。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

如果确实要从工作流程运行中触发工作流程，则可以使用个人访问令牌而不是 GITHUB_TOKEN 来触发需要令牌的事件。 您需要创建个人访问令牌并将其存储为密� �。 为了最大限度地降低 GitHub Actions 使用成本，请确保不要创建递归或意外的工作流程。 有关创建个人访问令牌的更多信息，请参阅“创建个人访问令牌”。 有关存储个人访问令牌的更多信息，请参阅“创建和存储� 密密� �”。

例如，以下工作流程使用个人访问令牌（存储为称为 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:

使用事件活动类型

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/**'

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

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

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'

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

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.

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

示例：包括分支和� �记

在 branches 和 tags 中定义的模式� �据 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. 在 branches 和 tags 中定义的模式� �据 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/10 或 releases/beta/mona 的推送上运行，而不会在到 releases/10-alpha 或 releases/beta/3-alpha 的推送上运行，� 为否定模式 !releases/**-alpha 后跟肯定模式。

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

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

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'

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.js 或 sub-project/src/index.js 的推送将会触发工作流程运行，但只更改 sub-project/docs/readme.md 的推送不会触发。

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

Git 差异比较

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

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

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

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

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

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

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

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

例如，仅当名为 Build 的工作流程在名称以 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'

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

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

使用事件信息

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

查看事件的所有属性

有关常见属性和示例负载，请参阅 web 挂钩事件文档。 更多信息请参阅“web 挂钩事件和有效负载”。

您还可以将整个 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) 不是 octobot 或 dependabot[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.'

有关上下文的更多信息，请参阅“上下文”。 有关事件有效负载的详细信息，请参阅“web 挂钩事件和有效负载”。

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

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

使用条件

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

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

例如，如果希望在将特定� �签添� 到议题时运行工作流程，则可以在 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

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

可用事件

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