触发工作流的事件

关于触发工作流程的事件

工作流程触发器是导致工作流程运行的事件。 有关如何使用工作流触发器的详细信息，请参阅“触发工作流程”。

某些事件具有多种活动类型。 对于这些事件，您可以指定将触发工作流程运行的活动类型。 有关每个活动类型的含义的详细信息，请参阅“Webhook 事件和有效负载”。

branch_protection_rule

在工作流程存储库中的分支保护规则发生更改时运行工作流程。 有关分支保护规则的详细信息，请参阅“关于受保护分支”。 有关分支保护规则 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“分支”。

例如，可以在分支保护规则状态为 created 或 deleted 时运行工作流：

on:
  branch_protection_rule:
    types: [created, deleted]

check_run

在发生与检查运行相关的活动时运行工作流程。 检查运行是检查套件中的单个测试。 如需相关信息，请参阅“使用 REST API 与检查交互”。 有关检查运行 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“检查”。

例如，可以在检查运行状态为 rerequested 或 completed 时运行工作流。

on:
  check_run:
    types: [rerequested, completed]

check_suite

在发生检查套件活动时运行工作流程。 检查套件是为特定提交创建的检查运行的集合。 检查套件汇总了套件中检查运行的状态和结论。 如需相关信息，请参阅“使用 REST API 与检查交互”。 有关检查套件 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“检查”。

例如，可以在检查运行状态为 completed 时运行工作流。

on:
  check_suite:
    types: [completed]

create

当有人在工作流程的存储库中创建 Git 引用（Git 分支或标记）时运行工作流程。 有关用于创建 Git 引用的 API 的信息，请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“Git 数据库”。

例如，可以在发生 create 事件时运行工作流。

on:
  create

delete

当有人删除工作流程存储库中的 Git 引用（Git 分支或标记）时运行工作流程。 有关用于删除 Git 引用的 API 的信息，请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“Git 数据库”。

例如，可以在发生 delete 事件时运行工作流。

on:
  delete

deployment

当有人在工作流程的存储库中创建部署时运行工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。有关用于创建部署的 API 的信息，请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“存储库”。

例如，可以在发生 deployment 事件时运行工作流。

on:
  deployment

deployment_status

在第三方提供部署状态时运行工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。有关用于创建部署状态的 API 的信息，请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“部署”。

例如，可以在发生 deployment_status 事件时运行工作流。

on:
  deployment_status

discussion

在创建或修改工作流程存储库中的讨论时运行工作流程。 对于与讨论评论相关的活动，请使用 discussion_comment 事件。 有关讨论的详细信息，请参阅“关于讨论”。 有关 GraphQL API 的信息，请参阅“对象”。

例如，可以在讨论状态为 created、edited 或 answered 时运行工作流。

on:
  discussion:
    types: [created, edited, answered]

discussion_comment

在创建或修改工作流程存储库中讨论的评论时运行工作流程。 对于与讨论（而非讨论的评论）相关的活动，请使用 discussion 事件。 有关讨论的详细信息，请参阅“关于讨论”。 有关 GraphQL API 的信息，请参阅“对象”。

例如，可以在讨论评论的状态为 created 或 deleted 时运行工作流。

on:
  discussion_comment:
    types: [created, deleted]

fork

当有人复刻存储库时运行工作流程。 有关 REST API 的信息，请参阅“存储库”。

例如，可以在发生 fork 事件时运行工作流。

on:
  fork

gollum

在有人创建或更新 Wiki 页面时运行工作流程。 有关详细信息，请参阅“关于 wikis”。

例如，可以在发生 gollum 事件时运行工作流。

on:
  gollum

issue_comment

在创建、编辑或删除议题或拉取请求评论时运行工作流程。 有关问题注释 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Webhook 事件和有效负载”。

例如，可以在问题或拉取请求注释的状态为 created 或 deleted 时运行工作流。

on:
  issue_comment:
    types: [created, deleted]

仅问题或仅拉取请求的 issue_comment

对于问题和拉取请求的注释，都会发生 issue_comment 事件。 可以在条件中使用 github.event.issue.pull_request 属性，根据触发对象是问题还是拉取请求来执行不同的操作。

例如，仅当 issue_comment 事件源自拉取请求时，此工作流才会运行 pr_commented 作业。 仅当 issue_comment 事件源自问题时，才会运行 issue_commented 作业。

on: issue_comment

jobs:
  pr_commented:
    # This job only runs for pull request comments
    name: PR comment
    if: ${{ github.event.issue.pull_request }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo A comment on PR $NUMBER
        env:
          NUMBER: ${{ github.event.issue.number }}

  issue_commented:
    # This job only runs for issue comments
    name: Issue comment
    if: ${{ !github.event.issue.pull_request }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo A comment on issue $NUMBER
        env:
          NUMBER: ${{ github.event.issue.number }}

issues

在创建或修改工作流程存储库中的议题时运行工作流程。 对于与问题中的注释相关的活动，请使用 issue_comment 事件。 有关问题的详细信息，请参阅“关于议题”。 有关问题 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“问题”。

例如，可以在问题状态为 opened、edited 或 milestoned 时运行工作流。

on:
  issues:
    types: [opened, edited, milestoned]

label

在创建或修改工作流程存储库中的标签时运行工作流程。 有关标签的详细信息，请参阅“管理标签”。 有关标签 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“问题”。

如果要在问题、拉取请求或讨论中添加或删除标签时运行工作流，请针对 issues、pull_request、pull_request_target 或 discussion 事件改用 labeled 或 unlabeled 活动类型。

例如，可以在标签状态为 created 或 deleted 时运行工作流。

on:
  label:
    types: [created, deleted]

merge_group

将拉取请求添加到合并队列时运行工作流，将拉取请求添加到合并组。 有关详细信息，请参阅“将拉取请求与合并队列合并”。

例如，可以在发生 checks_requested 活动时运行工作流。

on:
  merge_group:
    types: [checks_requested]

milestone

在创建或修改工作流程存储库中的里程碑时运行工作流程。 有关里程碑的详细信息，请参阅“关于里程碑”。 有关里程碑 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“问题”。

若想要在将问题添加到里程碑或从里程碑中删除问题时运行工作流，请针对 issues 事件改用 milestoned 或 demilestoned 活动类型。

例如，可以在里程碑状态为 opened 或 deleted 时运行工作流。

on:
  milestone:
    types: [opened, deleted]

page_build

当有人推送到作为 GitHub Pages 的发布源的分支时，如果为存储库启用了 GitHub Pages ，则运行工作流程。 有关 GitHub Pages 发布源的详细信息，请参阅“配置 GitHub Pages 站点的发布源”。 有关 REST API 的信息，请参阅“存储库”。

例如，可以在发生 page_build 事件时运行工作流。

on:
  page_build

project

在创建或修改项目板时运行工作流程。 对于与项目板中的卡片或列相关的活动，请改用 project_card 或 project_column 事件。 有关项目版块的详细信息，请参阅“关于 projects (classic)”。 有关项目版块 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Projects (classic)”。

例如，可以在项目状态为 created 或 deleted 时运行工作流。

on:
  project:
    types: [created, deleted]

project_card

在创建或修改项目板上的卡片时运行工作流程。 对于与项目板或项目板中的列相关的活动，请改用 project 或 project_column 事件。 有关项目版块的详细信息，请参阅“关于 projects (classic)”。 有关项目卡 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Projects (classic)”。

例如，可以在项目卡片的状态为 created 或 deleted 时运行工作流。

on:
  project_card:
    types: [created, deleted]

project_column

在创建或修改项目板上的列时运行工作流程。 对于与项目板或项目板中的卡片相关的活动，请改用 project 或 project_card 事件。 有关项目版块的详细信息，请参阅“关于 projects (classic)”。 有关项目列 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Projects (classic)”。

例如，可以在项目列的状态为 created 或 deleted 时运行工作流。

on:
  project_column:
    types: [created, deleted]

public

当工作流程的存储库从私有变为公共时运行工作流程。 有关 REST API 的信息，请参阅“存储库”。

例如，可以在发生 public 事件时运行工作流。

on:
  public

pull_request

在工作流程存储库中发生有关拉取请求的活动时运行工作流程。 例如，如果未指定任何活动类型，则工作流程将在打开或重新打开拉取请求时运行，或者在更新拉取请求的头部分支时运行。 对于与拉取请求审查、拉取请求审查注释或拉取请求注释相关的活动，请改用 pull_request_review、pull_request_review_comment 或 issue_comment 事件。 有关拉取请求 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“拉取”。

请注意，此事件的 GITHUB_SHA 是拉取请求合并分支的最后一个合并提交。 如果要获取最后一次提交到拉取请求的头部分支的提交 ID，请改用 github.event.pull_request.head.sha。

例如，您可以在打开或重新打开拉取请求时运行工作流程。

on:
  pull_request:
    types: [opened, reopened]

您可以使用事件上下文进一步控制工作流程中作业的运行时间。 例如，当请求对拉取请求进行审查时，将运行此工作流，但 specific_review_requested 作业仅在请求 octo-team 审查时运行。

on:
  pull_request:
    types: [review_requested]
jobs:
  specific_review_requested:
    runs-on: ubuntu-latest
    if: ${{ github.event.requested_team.name == 'octo-team'}}
    steps:
      - run: echo 'A review from octo-team was requested'

基于拉取请求的主要分支或基础分支运行 pull_request 工作流

可以使用 branches 或 branches-ignore 筛选器配置工作流，使其仅在面向特定分支的拉取请求上运行。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

例如，当有人打开面向名称以 releases/ 开头的分支的拉取请求时，此工作流将运行：

on:
  pull_request:
    types:
      - opened
    branches:
      - 'releases/**'

on:
  pull_request:
    types:
      - opened
    branches:
      - 'releases/**'
    paths:
      - '**.js'

要基于拉取请求的头部分支名称（而不是拉取请求的基本分支名称）运行作业，请在条件中使用 github.head_ref 上下文。 例如，每当打开拉取请求时，此工作流都会运行，但仅当拉取请求的头部是名称以 releases/ 开头的分支时，才会执行 run_if 作业：

on:
  pull_request:
    types:
      - opened
jobs:
  run_if:
    if:  startsWith(github.head_ref, 'releases/')
    runs-on: ubuntu-latest
    steps:
      - run: echo "The head of this PR starts with 'releases/'"

基于拉取请求中更改的文件运行 pull_request 工作流

您还可以将工作流程配置为在拉取请求更改特定文件时运行。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

例如，当拉取请求包含对 JavaScript 文件 (.js) 的更改时，此工作流将运行：

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

on:
  pull_request:
    types:
      - opened
    branches:
      - 'releases/**'
    paths:
      - '**.js'

在拉取请求合并时运行 pull_request 工作流

当拉取请求合并时，拉取请求将自动关闭。 要在拉取请求合并时运行工作流，请使用 pull_request closed 事件类型以及检查事件 merged 值的条件。 例如，每当拉取请求关闭时，将运行以下工作流程。 仅当拉取请求也合并时，if_merged 作业才会运行。

on:
  pull_request:
    types:
      - closed

jobs:
  if_merged:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
    - run: |
        echo The PR was merged

存储库分支中的工作流

默认情况下，工作流不在存储库分支中运行。 必须在存储库分支的“操作”选项卡中启用 GitHub Actions。

除 GITHUB_TOKEN 外，当从分支存储库触发工作流时，机密不会传递给运行器。 GITHUB_TOKEN 在存储库分支的拉取请求中具有只读权限。 有关详细信息，请参阅“自动令牌身份验证”。

复刻的仓库的拉取请求事件

对于从存储库分支到基础存储库的拉取请求，GitHub 会将 pull_request、issue_comment、pull_request_review_comment、pull_request_review 和 pull_request_target 事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时，拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息，请参阅“批准复刻中的工作流程运行”。

对于从分支存储库到专用存储库的拉取请求，工作流仅在启用时运行，请参阅“管理存储库的 GitHub Actions 设置”。

pull_request_comment（使用 issue_comment）

要在创建、编辑或删除对拉取请求（而不是拉取请求的差异）的注释时运行工作流，请使用 issue_comment 事件。 对于与拉取请求审查或拉取请求审查注释相关的活动，请使用 pull_request_review 或 pull_request_review_comment 事件。

pull_request_review

在提交、编辑或关闭拉取请求审阅时运行工作流程。 拉取请求审查是除正文评论和状态之外的一组拉取请求审查评论。 对于与拉取请求审查注释或拉取请求注释相关的活动，请改用 pull_request_review_comment 或 issue_comment 事件。 有关拉取请求审查 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“拉取”。

例如，可以在拉取请求审查的状态为 edited 或 dismissed 时运行工作流。

on:
  pull_request_review:
    types: [edited, dismissed]

在批准拉取请求时运行工作流程

若要在拉取请求获得批准后运行工作流，可以使用 submitted 类型的 pull_request_review 事件触发工作流，然后使用 github.event.review.state 属性检查审查状态。 例如，每当提交拉取请求审查时，此工作流都将运行，但仅当提交的审查是批准审查时，approved 作业才会运行：

on:
  pull_request_review:
    types: [submitted]

jobs:
  approved:
    if: github.event.review.state == 'APPROVED'
    runs-on: ubuntu-latest
    steps:
      - run: echo "This PR was approved"

存储库分支中的工作流

默认情况下，工作流不在存储库分支中运行。 必须在存储库分支的“操作”选项卡中启用 GitHub Actions。

除 GITHUB_TOKEN 外，当从分支存储库触发工作流时，机密不会传递给运行器。 GITHUB_TOKEN 在存储库分支的拉取请求中具有只读权限。 有关详细信息，请参阅“自动令牌身份验证”。

复刻的仓库的拉取请求事件

对于从存储库分支到基础存储库的拉取请求，GitHub 会将 pull_request、issue_comment、pull_request_review_comment、pull_request_review 和 pull_request_target 事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时，拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息，请参阅“批准复刻中的工作流程运行”。

对于从分支存储库到专用存储库的拉取请求，工作流仅在启用时运行，请参阅“管理存储库的 GitHub Actions 设置”。

pull_request_review_comment

在修改拉取请求审查评论时运行工作流程。 拉取请求审查评论是对拉取请求差异的评论。 对于与拉取请求审查或拉取请求注释相关的活动，请改用 pull_request_review 或 issue_comment 事件。 有关拉取请求审查注释 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“拉取”。

例如，可以在拉取请求审查注释的状态为 created 或 deleted 时运行工作流。

on:
  pull_request_review_comment:
    types: [created, deleted]

存储库分支中的工作流

默认情况下，工作流不在存储库分支中运行。 必须在存储库分支的“操作”选项卡中启用 GitHub Actions。

除 GITHUB_TOKEN 外，当从分支存储库触发工作流时，机密不会传递给运行器。 GITHUB_TOKEN 在存储库分支的拉取请求中具有只读权限。 有关详细信息，请参阅“自动令牌身份验证”。

复刻的仓库的拉取请求事件

对于从存储库分支到基础存储库的拉取请求，GitHub 会将 pull_request、issue_comment、pull_request_review_comment、pull_request_review 和 pull_request_target 事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时，拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息，请参阅“批准复刻中的工作流程运行”。

对于从分支存储库到专用存储库的拉取请求，工作流仅在启用时运行，请参阅“管理存储库的 GitHub Actions 设置”。

pull_request_target

在工作流程存储库中发生有关拉取请求的活动时运行工作流程。 例如，如果未指定任何活动类型，则工作流程将在打开或重新打开拉取请求时运行，或者在更新拉取请求的头部分支时运行。

此事件在拉取请求基础的上下文中运行，而不是像 pull_request 事件一样在合并提交上下文中运行。 这样可以防止从拉取请求的头部执行不安全的代码，以免更改您的仓库或窃取您在工作流程中使用的任何机密。 此事件允许您的工作流程对来自复刻的拉取请求执行标记或评论等操作。 如果需要从拉取请求构建或运行代码，请避免使用此事件。

为了确保存储库安全性，名称与特定模式匹配（例如类似于 SHA）的分支可能无法使用 pull_request_target 事件触发工作流。

例如，可以在拉取请求的状态为 assigned、opened、synchronize 或 reopened 时运行工作流。

on:
  pull_request_target:
    types: [assigned, opened, synchronize, reopened]

基于拉取请求的主要分支或基础分支运行 pull_request_target 工作流

可以使用 branches 或 branches-ignore 筛选器配置工作流，使其仅在面向特定分支的拉取请求上运行。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

例如，当有人打开面向名称以 releases/ 开头的分支的拉取请求时，此工作流将运行：

on:
  pull_request_target:
    types:
      - opened
    branches:
      - 'releases/**'

on:
  pull_request_target:
    types:
      - opened
    branches:
      - 'releases/**'
    paths:
      - '**.js'

要基于拉取请求的头部分支名称（而不是拉取请求的基本分支名称）运行作业，请在条件中使用 github.head_ref 上下文。 例如，每当打开拉取请求时，此工作流都会运行，但仅当拉取请求的头部是名称以 releases/ 开头的分支时，才会执行 run_if 作业：

on:
  pull_request_target:
    types:
      - opened
jobs:
  run_if:
    if:  startsWith(github.head_ref, 'releases/')
    runs-on: ubuntu-latest
    steps:
      - run: echo "The head of this PR starts with 'releases/'"

基于拉取请求中更改的文件运行 pull_request_target 工作流

可以使用 paths 或 paths-ignore 筛选器配置工作流，使其在拉取请求更改特定文件时运行。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

例如，当拉取请求包含对 JavaScript 文件 (.js) 的更改时，此工作流将运行：

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

on:
  pull_request_target:
    types:
      - opened
    branches:
      - 'releases/**'
    paths:
      - '**.js'

在拉取请求合并时运行 pull_request_target 工作流

当拉取请求合并时，拉取请求将自动关闭。 要在拉取请求合并时运行工作流，请使用 pull_request_target closed 事件类型以及检查事件 merged 值的条件。 例如，每当拉取请求关闭时，将运行以下工作流程。 仅当拉取请求也合并时，if_merged 作业才会运行。

on:
  pull_request_target:
    types:
      - closed

jobs:
  if_merged:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
    - run: |
        echo The PR was merged

push

在推送提交或标记或使用模板创建存储库时运行工作流。

例如，可以在发生 push 事件时运行工作流。

on:
  push

仅在推送到特定分支时运行工作流程

可以使用 branches 或 branches-ignore 筛选器配置工作流，使其仅在推送特定分支时运行。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

例如，当有人推送到 main 或推送到以 releases/ 开头的分支时，此工作流将运行。

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

on:
  push:
    branches:
      - 'releases/**'
    paths:
      - '**.js'

仅在发生特定标记的推送时运行工作流程

可以使用 tags 或 tags-ignore 筛选器配置工作流，使其仅在推送特定标记时运行。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

例如，当有人推送以 v1. 开头的标记时，此工作流将运行。

on:
  push:
    tags:
      - v1.**

仅当推送影响特定文件时才运行工作流程

可以使用 paths 或 paths-ignore 筛选器配置工作流，使其在推送到特定文件时运行。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

例如，当有人将更改推送到 JavaScript 文件 (.js) 时，此工作流将运行：

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

on:
  push:
    branches:
      - 'releases/**'
    paths:
      - '**.js'

registry_package

jobs:
    job_name:
        if: ${{ github.event.registry_package.package_version.container_metadata.tag.name != '' }}

当存储库中发生与 GitHub Packages 相关的活动时运行工作流程。 有关详细信息，请参阅“GitHub Packages 文档”。

例如，可以在新包版本状态为 published 时运行工作流。

on:
  registry_package:
    types: [published]

release

在存储库中发生发布活动时运行工作流程。 有关版本 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“发行版本”。

例如，可以在版本状态为 published 时运行工作流。

on:
  release:
    types: [published]

repository_dispatch

若想要触发 GitHub 外部发生的活动的工作流，可以使用 GitHub API 触发名为 repository_dispatch 的 Webhook 事件。 有关详细信息，请参阅“存储库”。

发出创建 repository_dispatch 事件的请求时，必须指定 event_type 来描述活动类型。 默认情况下，所有 repository_dispatch 活动类型都会触发一个工作流运行。 可以使用 types 关键字限制工作流，使其在 repository_dispatch Webhook 有效负载中发送特定 event_type 值时运行。

on:
  repository_dispatch:
    types: [test_result]

通过 client_payload 参数发送的任何数据都将在工作流的 github.event 上下文中可用。 例如，如果在创建存储库调度事件时发送此请求正文：

{
  "event_type": "test_result",
  "client_payload": {
    "passed": false,
    "message": "Error: timeout"
  }
}

则您可以在如下工作流程中访问有效负载：

on:
  repository_dispatch:
    types: [test_result]

jobs:
  run_if_failure:
    if: ${{ !github.event.client_payload.passed }}
    runs-on: ubuntu-latest
    steps:
      - env:
          MESSAGE: ${{ github.event.client_payload.message }}
        run: echo $MESSAGE

schedule

通过 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 * * *'

多个 schedule 事件可以触发单个工作流。 你可以通过 github.event.schedule 上下文访问触发工作流的计划事件。 此示例触发工作流在每周一至周四 5:30 UTC 运行，但在周一和周三跳过 Not on Monday or Wednesday 步骤。

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"

计划任务语法有五个字段，中间用空格分隔，每个字段代表一个时间单位。

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
* * * * *

您可在这五个字段中使用以下运算符：

可以使用 crontab guru 帮助生成 cron 语法并确认其运行时间。 为了帮助入门，我们还提供了 crontab guru 示例列表。

计划工作流程的通知将发送给最后修改工作流程文件中的 cron 语法的用户。 有关详细信息，请参阅“工作流程运行通知”。

status

在 Git 提交状态更改时运行工作流程。 例如，可以将提交标记为 error、failure、pending 或 success。 如果要提供有关状态更改的更多详细信息，可能需要使用 check_run 事件。 有关提交状态 API 的信息，请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“提交”。

例如，可以在发生 status 事件时运行工作流。

on:
  status

如果要基于新的提交状态在工作流中运行作业，可以使用 github.event.state 上下文。 例如，以下工作流在提交状态发生更改时触发，但 if_error_or_failure 作业仅在新的提交状态为 error 或 failure 时才运行。

on:
  status
jobs:
  if_error_or_failure:
    runs-on: ubuntu-latest
    if: >-
      github.event.state == 'error' ||
      github.event.state == 'failure'
    steps:
      - env:
          DESCRIPTION: ${{ github.event.description }}
        run: |
          echo The status is error or failed: $DESCRIPTION

watch

在工作流程的存储库加星标时运行工作流程。 有关拉取请求 API 的信息，请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“活动”。

例如，可以在某人为存储库加星标时（即监视事件的 started 活动类型）运行工作流。

on:
  watch:
    types: [started]

workflow_call

workflow_call 用于指示一个工作流可以由另一个工作流调用。 当使用 workflow_call 事件触发工作流时，被调用工作流中的事件负载与调用工作流中的事件负载相同。 有关详细信息，请参阅“重新使用工作流”。

以下示例仅在从另一个工作流程调用时运行工作流程：

on: workflow_call

workflow_dispatch

若要启用手动触发工作流，需要配置 workflow_dispatch 事件。 您可以使用 GitHub API、GitHub CLI或 GitHub 浏览器界面手动触发工作流程运行。 有关详细信息，请参阅“手动运行工作流程”。

on: workflow_dispatch

提供输入

您可以直接在工作流程中配置事件的自定义输入属性、默认输入值和必要输入。 触发事件时，可以提供 ref 和任何 inputs。 当工作流运行时，可以访问 inputs 上下文中的输入值。 有关详细信息，请参阅“上下文”。

此示例定义了名为 logLevel、tags 和 environment 的输入。 在运行工作流程时，可以将这些输入的值传递给工作流程。 然后，此工作流使用 inputs.logLevel、inputs.tags 和 inputs.environment 上下文属性。

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
        - info
        - warning
        - debug
      tags:
        description: 'Test scenario tags'
        required: false
        type: boolean
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  log-the-inputs:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "Log level: $LEVEL"
          echo "Tags: $TAGS"
          echo "Environment: $ENVIRONMENT"
        env:
          LEVEL: ${{ inputs.logLevel }}
          TAGS: ${{ inputs.tags }}
          ENVIRONMENT: ${{ inputs.environment }}

如果从浏览器运行此工作流程，则必须在工作流程运行之前手动输入所需输入的值。

还可以在从脚本运行工作流程时传递输入，或者使用 GitHub CLI。 例如：

gh workflow run run-tests.yml -f logLevel=warning -f tags=false -f environment=staging

有关详细信息，请参阅“手动运行工作流程”中的 GitHub CLI 信息。

workflow_run

此事件在请求或完成工作流程运行时发生。 它允许您基于另一个工作流程的执行或完成来执行工作流程。 由 workflow_run 事件启动的工作流能够访问机密和写入令牌，即使以前的工作流不能访问也是如此。 这在以前的工作流程有意未获权限的情况下很有用，但您需要在以后的工作流程中采取特权行动。

在此示例中，工作流程配置为在单独的“运行测试”工作流程完成后运行。

on:
  workflow_run:
    workflows: [Run Tests]
    types:
      - completed

如果为 workflow_run 事件指定多个 workflows，则只需要运行其中一个工作流。 例如，具有以下触发器的工作流程将在 "Staging" 工作流程或 "Lab" 工作流程完成时运行。

on:
  workflow_run:
    workflows: [Staging, Lab]
    types:
      - completed

基于另一个工作流程的结果运行工作流程

无论上一个工作流程的结果如何，工作流程运行都会被触发。 如果要基于触发工作流的结果运行作业或步骤，则可以使用带有 github.event.workflow_run.conclusion 属性的条件。 例如，每当名为“Build”的工作流完成时，此工作流就会运行，但 on-success 作业仅在“Build”工作流成功时才会运行，而 on-failure 作业仅在“Build”工作流失败时才会运行：

on:
  workflow_run:
    workflows: [Build]
    types: [completed]

jobs:
  on-success:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - run: echo 'The triggering workflow passed'
  on-failure:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    steps:
      - run: echo 'The triggering workflow failed'

将工作流限于基于分支的运行

可以使用 branches 或 branches-ignore 筛选器，指定触发工作流必须在哪些分支上运行才能触发工作流。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。 例如，仅当名为 Build 的工作流在名为 canary 的分支上运行时，具有以下触发器的工作流才会运行。

on:
  workflow_run:
    workflows: [Build]
    types: [requested]
    branches: [canary]

使用触发工作流程中的数据

可以访问与触发工作流的工作流对应的 workflow_run 事件负载。 例如，如果触发工作流生成工件，则使用 workflow_run 事件触发的工作流可以访问这些工件。

以下工作流程将数据作为构件上传。 （在此简化的示例中，数据是拉取请求编号。）

name: Upload data

on:
  pull_request:

jobs:
  upload:
    runs-on: ubuntu-latest

    steps:
      - name: Save PR number
        env:
          PR_NUMBER: ${{ github.event.number }}
        run: |
          mkdir -p ./pr
          echo $PR_NUMBER > ./pr/pr_number
      - uses: actions/upload-artifact@v3
        with:
          name: pr_number
          path: pr/

当上述工作流程的运行完成时，它将触发以下工作流程的运行。 以下工作流使用 github.event.workflow_run 上下文和 GitHub REST API 下载由上述工作流上传的工件，解压缩下载的工件，并对其编号作为工件上传的拉取请求进行注释。

name: Use the data

on:
  workflow_run:
    workflows: [Upload data]
    types:
      - completed

jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - name: 'Download artifact'
        uses: actions/github-script@v6
        with:
          script: |
            let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
               owner: context.repo.owner,
               repo: context.repo.repo,
               run_id: context.payload.workflow_run.id,
            });
            let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
              return artifact.name == "pr_number"
            })[0];
            let download = await github.rest.actions.downloadArtifact({
               owner: context.repo.owner,
               repo: context.repo.repo,
               artifact_id: matchArtifact.id,
               archive_format: 'zip',
            });
            let fs = require('fs');
            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/pr_number.zip`, Buffer.from(download.data));

      - name: 'Unzip artifact'
        run: unzip pr_number.zip

      - name: 'Comment on PR'
        uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            let fs = require('fs');
            let issue_number = Number(fs.readFileSync('./pr_number'));
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: issue_number,
              body: 'Thank you for the PR!'
            });