diff --git a/content/actions/using-workflows/events-that-trigger-workflows.md b/content/actions/using-workflows/events-that-trigger-workflows.md index 3ff88804ec..aed53bc6fb 100644 --- a/content/actions/using-workflows/events-that-trigger-workflows.md +++ b/content/actions/using-workflows/events-that-trigger-workflows.md @@ -19,11 +19,15 @@ shortTitle: Events that trigger workflows Workflow triggers are events that cause a workflow to run. For more information about how to use workflow triggers, see "[AUTOTITLE](/actions/using-workflows/triggering-a-workflow)." -## 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 "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)." -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 "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)." Note that not all webhook events trigger workflows. +{% note %} -### `branch_protection_rule` +**Note:** Not all webhook events trigger workflows. + +{% endnote %} + +## `branch_protection_rule` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -47,7 +51,7 @@ on: types: [created, deleted] ``` -### `check_run` +## `check_run` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -71,7 +75,7 @@ on: types: [rerequested, completed] ``` -### `check_suite` +## `check_suite` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -101,7 +105,7 @@ on: types: [completed] ``` -### `create` +## `create` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -122,7 +126,7 @@ on: create ``` -### `delete` +## `delete` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -145,7 +149,7 @@ on: delete ``` -### `deployment` +## `deployment` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -160,7 +164,7 @@ on: deployment ``` -### `deployment_status` +## `deployment_status` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -182,7 +186,7 @@ on: ``` {% ifversion discussions %} -### `discussion` +## `discussion` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -208,7 +212,7 @@ on: types: [created, edited, answered] ``` -### `discussion_comment` +## `discussion_comment` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -236,7 +240,7 @@ on: {% endif %} -### `fork` +## `fork` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -253,7 +257,7 @@ on: fork ``` -### `gollum` +## `gollum` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -270,7 +274,7 @@ on: gollum ``` -### `issue_comment` +## `issue_comment` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -294,7 +298,7 @@ on: types: [created, deleted] ``` -#### `issue_comment` on issues only or pull requests only +### `issue_comment` on issues only or pull requests only The `issue_comment` event occurs for comments on both issues and pull requests. 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. @@ -327,7 +331,7 @@ jobs: NUMBER: {% raw %}${{ github.event.issue.number }}{% endraw %} ``` -### `issues` +## `issues` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -351,7 +355,7 @@ on: types: [opened, edited, milestoned] ``` -### `label` +## `label` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -379,7 +383,7 @@ on: {% ifversion fpt or ghec %} -### `merge_group` +## `merge_group` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -405,7 +409,7 @@ on: ``` {% endif %} -### `milestone` +## `milestone` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -431,7 +435,7 @@ on: types: [opened, deleted] ``` -### `page_build` +## `page_build` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -448,7 +452,7 @@ on: page_build ``` -### `project` +## `project` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -486,7 +490,7 @@ on: types: [created, deleted] ``` -### `project_card` +## `project_card` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -524,7 +528,7 @@ on: types: [created, deleted] ``` -### `project_column` +## `project_column` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -562,7 +566,7 @@ on: types: [created, deleted] ``` -### `public` +## `public` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -579,7 +583,7 @@ on: public ``` -### `pull_request` +## `pull_request` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -625,7 +629,7 @@ jobs: - run: echo 'A review from octo-team was requested' ``` -#### Running your `pull_request` workflow based on the head or base branch of a pull request +### Running your `pull_request` 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 "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore)." @@ -672,7 +676,7 @@ jobs: - run: echo "The head of this PR starts with 'releases/'" ``` -#### Running your `pull_request` workflow based on files changed in a pull request +### Running your `pull_request` 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 "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)." @@ -702,7 +706,7 @@ on: {% endnote %} -#### Running your `pull_request` workflow when a pull request merges +### Running your `pull_request` workflow when a pull request merges When a pull request merges, the pull request is automatically closed. To run a workflow when a pull request merges, use the `pull_request` `closed` event type along with a conditional that checks the `merged` value of the event. For example, the following workflow will run whenever a pull request closes. The `if_merged` job will only run if the pull request was also merged. @@ -723,11 +727,11 @@ jobs: {% data reusables.developer-site.pull_request_forked_repos_link %} -### `pull_request_comment` (use `issue_comment`) +## `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`](#issue_comment) event. For activity related to pull request reviews or pull request review comments, use the [`pull_request_review`](#pull_request_review) or [`pull_request_review_comment`](#pull_request_review_comment) events. -### `pull_request_review` +## `pull_request_review` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -749,7 +753,7 @@ on: types: [edited, dismissed] ``` -#### Running a workflow when a pull request is approved +### 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: @@ -768,7 +772,7 @@ jobs: {% data reusables.developer-site.pull_request_forked_repos_link %} -### `pull_request_review_comment` +## `pull_request_review_comment` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -792,7 +796,7 @@ on: {% data reusables.developer-site.pull_request_forked_repos_link %} -### `pull_request_target` +## `pull_request_target` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -824,7 +828,7 @@ on: types: [assigned, opened, synchronize, reopened] ``` -#### Running your `pull_request_target` workflow based on the head or base branch of a pull request +### Running your `pull_request_target` 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 "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore)." @@ -871,7 +875,7 @@ jobs: - run: echo "The head of this PR starts with 'releases/'" ``` -#### Running your `pull_request_target` workflow based on files changed in a pull request +### Running your `pull_request_target` 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 "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)." @@ -901,7 +905,7 @@ on: {% endnote %} -#### Running your `pull_request_target` workflow when a pull request merges +### Running your `pull_request_target` workflow when a pull request merges When a pull request merges, the pull request is automatically closed. To run a workflow when a pull request merges, use the `pull_request_target` `closed` event type along with a conditional that checks the `merged` value of the event. For example, the following workflow will run whenever a pull request closes. The `if_merged` job will only run if the pull request was also merged. @@ -920,7 +924,7 @@ jobs: echo The PR was merged ``` -### `push` +## `push` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -953,7 +957,7 @@ on: {% endnote %} -#### Running your workflow only when a push to specific branches occurs +### 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 "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore)." @@ -982,7 +986,7 @@ on: {% endnote %} -#### Running your workflow only when a push of specific tags occurs +### 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 are pushed. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore)." @@ -995,7 +999,7 @@ on: - v1.** ``` -#### Running your workflow only when a push affects specific files +### 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 "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)." @@ -1023,7 +1027,7 @@ on: {% endnote %} -### `registry_package` +## `registry_package` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -1047,7 +1051,7 @@ on: types: [published] ``` -### `release` +## `release` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -1081,7 +1085,7 @@ on: types: [published] ``` -### `repository_dispatch` +## `repository_dispatch` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | ------------------ | ------------ | ------------ | ------------------| @@ -1134,7 +1138,7 @@ jobs: run: echo $MESSAGE ``` -### `schedule` +## `schedule` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -1179,7 +1183,7 @@ You can use [crontab guru](https://crontab.guru/) to help generate your cron syn Notifications for scheduled workflows are sent to the user who last modified the cron syntax in the workflow file. For more information, see "[AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/notifications-for-workflow-runs)." -### `status` +## `status` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -1214,7 +1218,7 @@ jobs: echo The status is error or failed: $DESCRIPTION ``` -### `watch` +## `watch` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -1238,7 +1242,7 @@ on: types: [started] ``` -### `workflow_call` +## `workflow_call` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | ------------------ | ------------ | ------------ | ------------------| @@ -1252,7 +1256,7 @@ The example below only runs the workflow when it's called from another workflow: on: workflow_call ``` -### `workflow_dispatch` +## `workflow_dispatch` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | ------------------ | ------------ | ------------ | ------------------| @@ -1264,7 +1268,7 @@ To manually trigger a workflow, use the `workflow_dispatch` event. You can manua on: workflow_dispatch ``` -#### Providing inputs +### Providing inputs You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow. When you trigger the event, you can provide the `ref` and any `inputs`. When the workflow runs, you can access the input values in the {% ifversion actions-unified-inputs %}`inputs`{% else %}`github.event.inputs`{% endif %} context. For more information, see "[AUTOTITLE](/actions/learn-github-actions/contexts)." @@ -1320,7 +1324,7 @@ gh workflow run run-tests.yml -f logLevel=warning -f tags=false -f environment=s For more information, see the {% data variables.product.prodname_cli %} information in "[AUTOTITLE](/actions/managing-workflow-runs/manually-running-a-workflow)." -### `workflow_run` +## `workflow_run` | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | --------------------- | -------------- | ------------ | -------------| @@ -1362,7 +1366,7 @@ on: - completed ``` -#### Running a workflow based on the conclusion of another workflow +### 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: @@ -1385,7 +1389,7 @@ jobs: - run: echo 'The triggering workflow failed' ``` -#### Limiting your workflow to run based on branches +### 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. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_runbranchesbranches-ignore)." For example, a workflow with the following trigger will only run when the workflow named `Build` runs on a branch named `canary`. @@ -1397,7 +1401,7 @@ on: branches: [canary] ``` -#### Using data from the triggering workflow +### Using data from the triggering workflow You can access the [`workflow_run` event payload](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_run) 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.