触发工作流程的事件

About workflow triggers

Workflow triggers are events that cause a workflow to run. These events can be:

• Events that occur in your workflow's repository
• Events that occur outside of GitHub Enterprise Cloud and trigger a repository_dispatch event on GitHub Enterprise Cloud
• Scheduled times
• Manual

For example, you can configure your workflow to run when a push is made to the default branch of your repository, when a release is created, or when an issue is opened.

Workflow triggers are defined with the on key. 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

1. An event occurs on your repository. The event has an associated commit SHA and Git ref.

2. GitHub Enterprise Cloud 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.

3. 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. 当工作流程运行时，GitHub Enterprise Cloud 会在运行器环境中设置 GITHUB_SHA（提交 SHA）和 GITHUB_REF（Git 引用）环境变量。 更多信息请参阅“使用环境变量”。

Triggering a workflow from a workflow

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 验证身份”。

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. 您需要创建个人访问令牌并将其存储为密码。 为了最大限度地降低 GitHub Actions 使用成本，请确保不要创建递归或意外的工作流程。 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 "Available events" below.

Using a single event

For example, a workflow with the following on value will run when a push is made to any branch in the workflow's repository:

on: push

Using multiple events

You can specify a single event or multiple events. For example, a workflow with the following on value will run when a push is made to any branch in the repository or when someone forks the repository:

on: [push, fork]

If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered.

Using activity types

Some events have activity types that give you more control over when your workflow should 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

Using filters

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

Using activity types and filters with multiple events

If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately. You must append a colon (:) to all events, including events without configuration.

For example, a workflow with the following on value will run when:

• A label is created
• A push is made to the main branch in the repository
• A push is made to a GitHub Pages-enabled branch

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

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. 更多信息请参阅“web 挂钩事件和有效负载”。

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

For more information, 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'

Available events

Some events have multiple activity types. For these events, you can specify which activity types will trigger a workflow run. For more information about what each activity type means, see "Webhook events and payloads." Note that not all webhook events trigger workflows.

branch_protection_rule

Runs your workflow when branch protection rules in the workflow repository are changed. For more information about branch protection rules, see "About protected branches." For information about the branch protection rule APIs, see "BranchProtectionRule" in the GraphQL API documentation or "Branches" in the REST API documentation.

For example, you can run a workflow when a branch protection rule has been created or deleted:

on:
  branch_protection_rule:
    types: [created, deleted]

check_run

Runs your workflow when activity related to a check run occurs. 检查运行是检查套件中的单个测试。 For information, see "Getting started with the Checks API." For information about the check run APIs, see "CheckRun" in the GraphQL API documentation or "Checks" in the REST API documentation.

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

on:
  check_run:
    types: [rerequested, completed]

check_suite

Runs your workflow when check suite activity occurs. A check suite is a collection of the check runs created for a specific commit. Check suites summarize the status and conclusion of the check runs that are in the suite. For information, see "Getting started with the Checks API." For information about the check suite APIs, see "CheckSuite" in the GraphQL API documentation or "Checks" in the REST API documentation.

For example, you can run a workflow when a check suite has been completed.

on:
  check_suite:
    types: [completed]

create

Runs your workflow when someone creates a Git reference (Git branch or tag) in the workflow's repository. For information about the APIs to create a Git reference, see "createRef" in the GraphQL API documentation or "Create a reference" in the REST API documentation.

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

on:
  create

delete

Runs your workflow when someone deletes a Git reference (Git branch or tag) in the workflow's repository. For information about the APIs to delete a Git reference, see "deleteRef" in the GraphQL API documentation or "Delete a reference" in the REST API documentation.

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

on:
  delete

deployment

Runs your workflow when someone creates a deployment in the workflow's repository. 使用提交 SHA 创建的部署可能没有 Git 引用。 For information about the APIs to create a deployment, see "createDeployment" in the GraphQL API documentation or "Deployments" in the REST API documentation.

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

on:
  deployment

deployment_status

Runs your workflow when a third party provides a deployment status. 使用提交 SHA 创建的部署可能没有 Git 引用。 For information about the APIs to create a deployment status, see "createDeploymentStatus" in the GraphQL API documentation or "Create a deployment status" in the REST API documentation.

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

on:
  deployment_status

讨论

Runs your workflow when a discussion in the workflow's repository is created or modified. For activity related to comments on a discussion, use the discussion_comment event. For more information about discussions, see "About discussions." For information about the GraphQL API, see "Discussion."

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

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

discussion_comment

Runs your workflow when a comment on a discussion in the workflow's repository is created or modified. For activity related to a discussion as opposed to comments on the discussion, use the discussion event. For more information about discussions, see "About discussions." For information about the GraphQL API, see "Discussion."

For example, you can run a workflow when a discussion comment has been created or deleted.

on:
  discussion_comment:
    types: [created, deleted]

复刻

Runs your workflow when someone forks a repository. 有关 REST API 的信息，请参阅“创建复刻”。

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

on:
  fork

gollum

Runs your workflow when someone creates or updates a Wiki page. 更多信息请参阅“关于 wiki”。

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

on:
  gollum

issue_comment

Runs your workflow when an issue or pull request comment is created, edited, or deleted. For information about the issue comment APIs, see "IssueComment" in the GraphQL API documentation or "Issue comments" in the REST API documentation.

For example, you can run a workflow when an issue or pull request comment has been created or deleted.

on:
  issue_comment:
    types: [created, deleted]

issue_comment on issues only or pull requests only

issue_comment 事件在评论问题和拉取请求时发生。 You can use the github.event.issue.pull_request property in a conditional to take different action depending on whether the triggering object was an issue or pull request.

For example, this workflow will run the pr_commented job only if the issue_comment event originated from a pull request. It will run the issue_commented job only if the issue_comment event originated from an issue.

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

议题

Runs your workflow when an issue in the workflow's repository is created or modified. For activity related to comments in an issue, use the issue_comment event. 有关议题的更多信息，请参阅“关于议题”。 For information about the issue APIs, see "Issue" in the GraphQL API documentation or "Issues" in the REST API documentation.

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

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

标签

Runs your workflow when a label in your workflow's repository is created or modified. For more information about labels, see "Managing labels." For information about the label APIs, see "Label" in the GraphQL API documentation or "Labels" in the REST API documentation.

If you want to run your workflow when a label is added to or removed from an issue, pull request, or discussion, use the labeled or unlabeled activity types for the issues, pull_request, pull_request_target, or discussion events instead.

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

on:
  label:
    types: [created, deleted]

里程碑

Runs your workflow when a milestone in the workflow's repository is created or modified. For more information about milestones, see "About milestones." For information about the milestone APIs, see "Milestone" in the GraphQL API documentation or "Milestones" in the REST API documentation.

If you want to run your workflow when an issue is added to or removed from a milestone, use the milestoned or demilestoned activity types for the issues event instead.

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

on:
  milestone:
    types: [opened, deleted]

page_build

Runs your workflow when someone pushes to a branch that is the publishing source for GitHub Pages, if GitHub Pages is enabled for the repository. For more information about GitHub Pages publishing sources, see "Configuring a publishing source for your GitHub Pages site." 有关 REST API 的信息，请参阅“页面”。

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

on:
  page_build

project

Runs your workflow when a project board is created or modified. For activity related to cards or columns in a project board, use the project_card or project_column events instead. For more information about project boards, see "About project boards." For information about the project board APIs, see "Project" in the GraphQL API documentation or "Projects" in the REST API documentation.

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

on:
  project:
    types: [created, deleted]

project_card

Runs your workflow when a card on a project board is created or modified. For activity related to project boards or columns in a project board, use the project or project_column event instead. For more information about project boards, see "About project boards." For information about the project card APIs, see "ProjectCard" in the GraphQL API documentation or "Project cards" in the REST API documentation.

For example, you can run a workflow when a project card has been created or deleted.

on:
  project_card:
    types: [created, deleted]

project_column

Runs your workflow when a column on a project board is created or modified. For activity related to project boards or cards in a project board, use the project or project_card event instead. For more information about project boards, see "About project boards." For information about the project column APIs, see "Project Column" in the GraphQL API documentation or "Project columns" in the REST API documentation.

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

on:
  project_column:
    types: [created, deleted]

public

Runs your workflow when your workflow's repository changes from private to public. 有关 REST API 的信息，请参阅“编辑仓库”。

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

on:
  public

pull_request

Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated. For activity related to pull request reviews, pull request review comments, or pull request comments, use the pull_request_review, pull_request_review_comment, or issue_comment events instead. For information about the pull request APIs, see "PullRequest" in the GraphQL API documentation or "Pull requests" in the REST API documentation.

Note that GITHUB_SHA for this event is the last merge commit of the pull request merge branch. If you want to get the commit ID for the last commit to the head branch of the pull request, use github.event.pull_request.head.sha instead.

For example, you can run a workflow when a pull request has been opened or reopened.

on:
  pull_request:
    types: [opened, reopened]

You can use the event context to further control when jobs in your workflow will run. For example, this workflow will run when a review is requested on a pull request, but the specific_review_requested job will only run when a review by octo-team is requested.

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'

Running your workflow based on the head or base branch of a pull request

You can use the branches or branches-ignore filter to configure your workflow to only run on pull requests that target specific branches. For more information, see "Workflow syntax for GitHub Actions."

For example, this workflow will run when someone opens a pull request that targets a branch whose name starts with releases/:

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

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

To run a job based on the pull request's head branch name (as opposed to the pull request's base branch name), use the github.head_ref context in a conditional. For example, this workflow will run whenever a pull request is opened, but the run_if job will only execute if the head of the pull request is a branch whose name starts with releases/:

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

Running your workflow based on files changed in a pull request

You can also configure your workflow to run when a pull request changes specific files. For more information, see "Workflow syntax for GitHub Actions."

For example, this workflow will run when a pull request includes a change to a JavaScript file (.js):

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

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

Workflows in forked repositories

Workflows don't run in forked repositories by default. 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 The GITHUB_TOKEN has read-only permissions in forked repositories. 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

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

For pull requests from a forked repository to the base repository, GitHub Enterprise Cloud sends the pull_request, issue_comment, pull_request_review_comment, pull_request_review, and pull_request_target events to the base repository. No pull request events occur on the forked repository.

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

pull_request_comment (use issue_comment)

To run your workflow when a comment on a pull request (not on a pull request's diff) is created, edited, or deleted, use the issue_comment event. For activity related to pull request reviews or pull request review comments, use the pull_request_review or pull_request_review_comment events.

pull_request_review

Runs your workflow when a pull request review is submitted, edited, or dismissed. A pull request review is a group of pull request review comments in addition to a body comment and a state. For activity related to pull request review comments or pull request comments, use the pull_request_review_comment or issue_comment events instead. For information about the pull request review APIs, see "PullRequestReview" in the GraphQL API documentation or "Pull request reviews" in the REST API documentation.

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

on:
  pull_request_review:
    types: [edited, dismissed]

Running a workflow when a pull request is approved

To run your workflow when a pull request has been approved, you can trigger your workflow with the submitted type of pull_request_review event, then check the review state with the github.event.review.state property. For example, this workflow will run whenever a pull request review is submitted, but the approved job will only run if the submitted review is an approving review:

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"

Workflows in forked repositories

Workflows don't run in forked repositories by default. 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 The GITHUB_TOKEN has read-only permissions in forked repositories. 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

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

For pull requests from a forked repository to the base repository, GitHub Enterprise Cloud sends the pull_request, issue_comment, pull_request_review_comment, pull_request_review, and pull_request_target events to the base repository. No pull request events occur on the forked repository.

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

pull_request_review_comment

Runs your workflow when a pull request review comment is modified. A pull request review comment is a comment on a pull request's diff. For activity related to pull request reviews or pull request comments, use the pull_request_review or issue_comment events instead. For information about the pull request review comment APIs, see "PullRequestReviewComment" in the GraphQL API documentation or "Review comments" in the REST API documentation.

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

on:
  pull_request_review_comment:
    types: [created, deleted]

Workflows in forked repositories

Workflows don't run in forked repositories by default. 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 The GITHUB_TOKEN has read-only permissions in forked repositories. 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

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

For pull requests from a forked repository to the base repository, GitHub Enterprise Cloud sends the pull_request, issue_comment, pull_request_review_comment, pull_request_review, and pull_request_target events to the base repository. No pull request events occur on the forked repository.

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

pull_request_target

Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated.

This event runs in the context of the base of the pull request, rather than in the context of the merge commit, as the pull_request event does. This prevents execution of unsafe code from the head of the pull request that could alter your repository or steal any secrets you use in your workflow. This event allows your workflow to do things like label or comment on pull requests from forks. Avoid using this event if you need to build or run code from the pull request.

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

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

Running your workflow based on the head or base branch of a pull request

You can use the branches or branches-ignore filter to configure your workflow to only run on pull requests that target specific branches. For more information, see "Workflow syntax for GitHub Actions."

For example, this workflow will run when someone opens a pull request that targets a branch whose name starts with releases/:

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

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

To run a job based on the pull request's head branch name (as opposed to the pull request's base branch name), use the github.head_ref context in a conditional. For example, this workflow will run whenever a pull request is opened, but the run_if job will only execute if the head of the pull request is a branch whose name starts with releases/:

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

Running your workflow based on files changed in a pull request

You can use the paths or paths-ignore filter to configure your workflow to run when a pull request changes specific files. For more information, see "Workflow syntax for GitHub Actions."

For example, this workflow will run when a pull request includes a change to a JavaScript file (.js):

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

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

推送

Runs your workflow when you push a commit or tag.

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

on:
  push

Running your workflow only when a push to specific branches occurs

You can use the branches or branches-ignore filter to configure your workflow to only run when specific branches are pushed. For more information, see "Workflow syntax for GitHub Actions."

For example, this workflow will run when someone pushes to main or to a branch that starts with releases/.

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

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

Running your workflow only when a push of specific tags occurs

You can use the tags or tags-ignore filter to configure your workflow to only run when specific tags or are pushed. For more information, see "Workflow syntax for GitHub Actions."

For example, this workflow will run when someone pushes a tag that starts with v1..

on:
  push:
    tags:        
      - v1.**

Running your workflow only when a push affects specific files

You can use the paths or paths-ignore filter to configure your workflow to run when a push to specific files occurs. For more information, see "Workflow syntax for GitHub Actions."

For example, this workflow will run when someone pushes a change to a JavaScript file (.js):

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

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

registry_package

Runs your workflow when activity related to GitHub Packages occurs in your repository. For more information, see "GitHub Packages Documentation."

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

on:
  registry_package:
    types: [published]

发行版

Runs your workflow when release activity in your repository occurs. For information about the release APIs, see "Release" in the GraphQL API documentation or "Releases" in the REST API documentation.

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

on:
  release:
    types: [published]

repository_dispatch

You can use the GitHub Enterprise Cloud API to trigger a webhook event called repository_dispatch when you want to trigger a workflow for activity that happens outside of GitHub Enterprise Cloud. 更多信息请参阅“创建仓库调度事件”。

When you make a request to create a repository_dispatch event, you must specify an event_type to describe the activity type. By default, all repository_dispatch activity types trigger a workflow to run. You can use the types keyword to limit your workflow to run when a specific event_type value is sent in the repository_dispatch webhook payload.

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

Any data that you send through the client_payload parameter will be available in the github.event context in your workflow. For example, if you send this request body when you create a repository dispatch event:

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

then you can access the payload in a workflow like this:

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 时间运行。 预定的工作流程在默认或基础分支的最新提交上运行。 您可以运行预定工作流程的最短间隔是每 15 分钟一次。

此示例在每天 5:30 和 17:30 UTC 触发工作流程：

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

A single workflow can be triggered by multiple schedule events. You can access the schedule event that triggered the workflow through the github.event.schedule context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the Not on Monday or Wednesday step on Monday and 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 帮助生成计划任务语法并确认它在何时运行。 为帮助您开始，我们还提供了一系列 crontab guru 示例。

计划工作流程的通知将发送给最后修改工作流程文件中的 cron 语法的用户。 For more information, see "Notifications for workflow runs."

状态

Runs your workflow when the status of a Git commit changes. For example, commits can be marked as error, failure, pending, or success. If you want to provide more details about the status change, you may want to use the check_run event. For information about the commit status APIs, see "Status" in the GraphQL API documentation or "Statuses" in the REST API documentation.

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

on:
  status

If you want to run a job in your workflow based on the new commit state, you can use the github.event.state context. For example, the following workflow triggers when a commit status changes, but the if_error_or_failure job only runs if the new commit state is 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

查看

Runs your workflow when the workflow's repository is starred. For information about the pull request APIs, see "addStar" in the GraphQL API documentation or "Starring" in the REST API documentation.

For example, you can run a workflow when someone stars a repository, which is the started activity type for a watch event.

on:
  watch:
    types: [started]

workflow_call

workflow_call is used to indicate that a workflow can be called by another workflow. When a workflow is triggered with the workflow_call event, the event playload in the called workflow is the same event payload from the calling workflow. For more information see, "Reusing workflows."

The example below only runs the workflow when it's called from another workflow:

on: workflow_call

workflow_dispatch

To manually trigger a workflow, use the workflow_dispatch event. You can manually trigger a workflow run using the GitHub Enterprise Cloud API, GitHub CLI, or GitHub Enterprise Cloud browser interface. 更多信息请参阅“手动配置工作流程。

on: workflow_dispatch

Providing inputs

您可以直接在工作流程中配置事件的自定义输入属性、默认输入值和必要输入。 When you trigger the event, you can provide the ref and any inputs. 当工作流程运行时，您可以访问 github.event.inputs 上下文中的输入值。 更多信息请参阅“上下文”。

此示例定义了 name 和 home 输入，并使用 github.event.inputs.name 和 github.event.inputs.home 上下文打印。 如果未提供 home ，则打印默认值“The Octoverse”。

name: Manually triggered workflow
on:
  workflow_dispatch:
    inputs:
      name:
        description: 'Person to greet'
        required: true
        default: 'Mona the Octocat'
      home:
        description: 'location'
        required: false
        default: 'The Octoverse'

jobs:
  say_hello:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo Hello $NAME!
          echo -in $HOME
        env:
          NAME: ${{ github.event.inputs.name }}
          HOME: ${{ github.event.inputs.home }}

workflow_run

This event occurs when a workflow run is requested or completed. It allows you to execute a workflow based on execution or completion of another workflow. 由 workflow_run 事件启动的工作流程能够访问密钥和写入令牌，即使以前的工作流程不能访问也一样。 这在以前的工作流程有意未获权限的情况下很有用，但您需要在以后的工作流程中采取特权行动。

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

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

If you specify multiple workflows for the workflow_run event, only one of the workflows needs to run. For example, a workflow with the following trigger will run whenever the "Staging" workflow or the "Lab" workflow completes.

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

Running a workflow based on the conclusion of another workflow

A workflow run is triggered regardless of the conclusion of the previous workflow. If you want to run a job or step based on the result of the triggering workflow, you can use a conditional with the github.event.workflow_run.conclusion property. For example, this workflow will run whenever a workflow named "Build" completes, but the on-success job will only run if the "Build" workflow succeeded, and the on-failure job will only run if the "Build" workflow failed:

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'

Limiting your workflow to run based on branches

You can use the branches or branches-ignore filter to specify what branches the triggering workflow must run on in order to trigger your workflow. 更多信息请参阅“GitHub Actions 的工作流程语法”。 For example, a workflow with the following trigger will only run when the workflow named Build runs on a branch named canary.

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

Using data from the triggering workflow

You can access the workflow_run event payload that corresponds to the workflow that triggered your workflow. For example, if your triggering workflow generates artifacts, a workflow triggered with the workflow_run event can access these artifacts.

The following workflow uploads data as an artifact. (In this simplified example, the data is the pull request number.)

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@v2
        with:
          name: pr_number
          path: pr/

When a run of the above workflow completes, it triggers a run of the following workflow. The following workflow uses the github.event.workflow_run context and the GitHub Enterprise Cloud REST API to download the artifact that was uploaded by the above workflow, unzips the downloaded artifact, and comments on the pull request whose number was uploaded as an artifact.

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@v5
        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@v5
        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!'
            });