触发工作流程的事件

关于触发工作流程的事件

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

可用事件

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

branch_protection_rule

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

例如，您可以在分支保护规则为 created 或 deleted 时运行工作流程。

on:
  branch_protection_rule:
    types: [created, deleted]

check_run

在发生与检查运行相关的活动时运行工作流程。 检查运行是检查套件中的单个测试。 有关信息，请参阅“检查 API 入门”。 有关检查运行 API 的信息，请参阅 GraphQL API 文档中的“CheckRun”或 REST API 文档中的“检查”。

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

on:
  check_run:
    types: [rerequested, completed]

check_suite

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

例如，您可以在检查套件为 completed 时运行工作流程。

on:
  check_suite:
    types: [completed]

create

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

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

on:
  create

delete

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

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

on:
  delete

deployment

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

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

on:
  deployment

deployment_status

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

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

on:
  deployment_status

讨论

在创建或修改工作流程存储库中的讨论时运行工作流程。 对于与讨论评论相关的活动，请使用 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]

复刻

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

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

on:
  fork

gollum

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

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

on:
  gollum

issue_comment

在创建、编辑或删除议题或拉取请求评论时运行工作流程。 有关议题评论 API 的信息，请参阅 GraphQL API 文档中的“IssueComment”或 REST API 文档中的“议题评论”。

例如，您可以在议题或拉取请求评论为 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 }}

议题

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

例如，您可以在议题为 opened、edited 或 milestoned 时运行工作流程。

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

标签

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

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

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

on:
  label:
    types: [created, deleted]

里程碑

在创建或修改工作流程存储库中的里程碑时运行工作流程。 有关里程碑的更多信息，请参阅“关于里程碑”。 有关里程碑 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 事件。 有关项目板的更多信息，请参阅“关于项目板”。 有关项目板 API 的信息，请参阅 GraphQL API 文档中的“项目”或 REST API 文档中的“项目”。

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

on:
  project:
    types: [created, deleted]

project_card

在创建或修改项目板上的卡片时运行工作流程。 对于与项目板或项目板中的列相关的活动，请改用 project 或 project_column 事件。 有关项目板的更多信息，请参阅“关于项目板”。 有关项目卡 API 的信息，请参阅 GraphQL API 文档中的“ProjectCard”或 REST API 文档中的“项目卡”。

例如，您可以在项目卡为 created 或 deleted 时运行工作流程。

on:
  project_card:
    types: [created, deleted]

project_column

在创建或修改项目板上的列时运行工作流程。 对于与项目板或项目板中的卡相关的活动，请改用 project 或 project_card 事件。 有关项目板的更多信息，请参阅“关于项目板”。 有关项目列 API 的信息，请参阅 GraphQL API 文档中的“项目列”或 REST API 文档中的“项目列”。

例如，您可以在项目列为 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 文档中的“PullRequest”或 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'

基于拉取请求的头部分支或基本分支运行工作流程

您可以使用 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/'"

根据拉取请求中更改的文件运行工作流程

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

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

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

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

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

当拉取请求合并时，拉取请求将自动关闭。 要在拉取请求合并时运行工作流程，请使用 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

复刻的存储库中的工作流程

默认情况下，工作流程不在复刻仓库上运行。 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 GITHUB_TOKEN 拥有复刻的仓库的只读权限。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

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

对于从复刻的存储库到基本存储库的拉取请求，GitHub Enterprise Cloud 将 pull_request、issue_comment、pull_request_review_comment、pull_request_review 和 pull_request_target 事件发送到基本存储库。 复刻的存储库上不会发生任何拉取请求事件。

当贡献者第一次向公共仓库提交拉取请求时，拥有写入权限的维护者可能需要批准拉取请求上运行的工作流程。 更多信息请参阅“批准公共复刻中的工作流程运行”。

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 文档中的“PullRequestReview”或 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"

复刻的存储库中的工作流程

默认情况下，工作流程不在复刻仓库上运行。 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 GITHUB_TOKEN 拥有复刻的仓库的只读权限。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

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

对于从复刻的存储库到基本存储库的拉取请求，GitHub Enterprise Cloud 将 pull_request、issue_comment、pull_request_review_comment、pull_request_review 和 pull_request_target 事件发送到基本存储库。 复刻的存储库上不会发生任何拉取请求事件。

当贡献者第一次向公共仓库提交拉取请求时，拥有写入权限的维护者可能需要批准拉取请求上运行的工作流程。 更多信息请参阅“批准公共复刻中的工作流程运行”。

pull_request_review_comment

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

例如，您可以在拉取请求审查评论为 created 或 deleted 时运行工作流程。

on:
  pull_request_review_comment:
    types: [created, deleted]

复刻的存储库中的工作流程

默认情况下，工作流程不在复刻仓库上运行。 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 GITHUB_TOKEN 拥有复刻的仓库的只读权限。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

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

对于从复刻的存储库到基本存储库的拉取请求，GitHub Enterprise Cloud 将 pull_request、issue_comment、pull_request_review_comment、pull_request_review 和 pull_request_target 事件发送到基本存储库。 复刻的存储库上不会发生任何拉取请求事件。

当贡献者第一次向公共仓库提交拉取请求时，拥有写入权限的维护者可能需要批准拉取请求上运行的工作流程。 更多信息请参阅“批准公共复刻中的工作流程运行”。

pull_request_target

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

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

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

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

基于拉取请求的头部分支或基本分支运行工作流程

您可以使用 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:
    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/'"

根据拉取请求中更改的文件运行工作流程

您可以使用 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 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 事件时运行工作流程。

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

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

例如，您可以在软件包为 published 时运行工作流程。

on:
  registry_package:
    types: [published]

发行版

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

例如，您可以在版本发布为 published 时运行工作流程。

on:
  release:
    types: [published]

repository_dispatch

当您想要触发在 GitHub Enterprise Cloud 外发生的活动的工作流程时，可以使用 GitHub Enterprise Cloud API 触发名为 repository_dispatch 的 web 挂钩事件。 更多信息请参阅“创建仓库调度事件”。

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

on:
  repository_dispatch:
    types: [on-demand-test]

通过 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 事件允许您在计划的时间触发工作流程。

您可以使用 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"

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

┌───────────── 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 帮助生成计划任务语法并确认它在何时运行。 为帮助您开始，我们还提供了一系列 crontab guru 示例。

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

状态

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

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

on:
  status

如果要基于新的提交状态在工作流程中运行作业，可以使用 github.event.state 上下文。 例如，以下工作流程在提交状态更改时触发，但仅当新的提交状态为 error 或 failure 时， if_error_or_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

查看

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

例如，您可以在某人为仓库加星标时（即关注事件的 started 活动类型）运行工作流程。

on:
  watch:
    types: [started]

workflow_call

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

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

on: workflow_call

workflow_dispatch

要手动触发工作流程，请使用 workflow_dispatch 事件。 您可以使用 GitHub Enterprise Cloud API、GitHub CLI或 GitHub Enterprise Cloud 浏览器界面手动触发工作流程运行。 更多信息请参阅“手动配置工作流程。

on: workflow_dispatch

提供输入

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

此示例定义了称为 logLevel、tags 和 environment 的输入。 在运行工作流程时，可以将这些输入的值传递给工作流程。 然后，此工作流程使用 github.event.inputs.logLevel、github.event.inputs.tags 和 github.event.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: ${{ github.event.inputs.logLevel }}
          TAGS: ${{ github.event.inputs.tags }}
          ENVIRONMENT: ${{ github.event.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 的工作流程在名为 <0>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 Enterprise Cloud 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!'
            });