This page was generated based on Github’s Documentation. See our welcome page for context and details.
Github Event workflow_run
#
Github Action Trigger #
Webhook event payload | Activity types | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
workflow_run | - completed - requested - in_progress | Last commit on default branch | Default branch |
Note: More than one activity type triggers this event. The requested
activity type does not occur when a workflow is re-run. For information about each activity type, see “Webhook events and payloads.” By default, all activity types trigger workflows that run on this event. You can limit your workflow runs to specific activity types using the types
keyword. For more information, see “Workflow syntax for GitHub Actions.”
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
Note: You can’t use workflow_run
to chain together more than three levels of workflows. For example, if you attempt to trigger five workflows (named B
to F
) to run sequentially after an initial workflow A
has run (that is: A
→ B
→ C
→ D
→ E
→ F
), workflows E
and F
will not be 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. The workflow started by the workflow_run
event is able to access secrets and write tokens, even if the previous workflow was not. This is useful in cases where the previous workflow is intentionally not privileged, but you need to take a privileged action in a later workflow.
In this example, a workflow is configured to run after the separate “Run Tests” workflow completes.
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. For more information, see “Workflow syntax for 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@v4
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 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@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!'
});
Press alt+up to activate
Event Payload #
Activities: completed
, in_progress
, requested
Common Fields #
These fields are common to every event types available with this trigger.
field | type | required | description |
---|---|---|---|
github.event.enterprise | object | optional | An enterprise on GitHub. Webhook payloads contain the |
github.event.installation | object | optional | The GitHub App installation. Webhook payloads contain the |
github.event.organization | object | optional | A GitHub organization. Webhook payloads contain the |
github.event.repository | object | required | The repository on GitHub where the event occurred. Webhook payloads contain the |
github.event.sender | object | required | The GitHub user that triggered the event. This property is included in every webhook payload. |
github.event.workflow | object or null | required | |
github.event.workflow.badge_url | string | required | |
github.event.workflow.created_at | string | required | |
github.event.workflow.html_url | string | required | |
github.event.workflow.id | integer | required | |
github.event.workflow.name | string | required | |
github.event.workflow.node_id | string | required | |
github.event.workflow.path | string | required | |
github.event.workflow.state | string | required | |
github.event.workflow.updated_at | string | required | |
github.event.workflow.url | string | required | |
github.event.workflow_run | object | required | |
github.event.workflow_run.actor | object or null | required | |
github.event.workflow_run.actor.avatar_url | string | optional | |
github.event.workflow_run.actor.deleted | boolean | optional | |
github.event.workflow_run.actor.email | string or null | optional | |
github.event.workflow_run.actor.events_url | string | optional | |
github.event.workflow_run.actor.followers_url | string | optional | |
github.event.workflow_run.actor.following_url | string | optional | |
github.event.workflow_run.actor.gists_url | string | optional | |
github.event.workflow_run.actor.gravatar_id | string | optional | |
github.event.workflow_run.actor.html_url | string | optional | |
github.event.workflow_run.actor.id | integer | required | |
github.event.workflow_run.actor.login | string | required | |
github.event.workflow_run.actor.name | string | optional | |
github.event.workflow_run.actor.node_id | string | optional | |
github.event.workflow_run.actor.organizations_url | string | optional | |
github.event.workflow_run.actor.received_events_url | string | optional | |
github.event.workflow_run.actor.repos_url | string | optional | |
github.event.workflow_run.actor.site_admin | boolean | optional | |
github.event.workflow_run.actor.starred_url | string | optional | |
github.event.workflow_run.actor.subscriptions_url | string | optional | |
github.event.workflow_run.actor.type | Bot , User , Organization | optional | |
github.event.workflow_run.actor.url | string | optional | |
github.event.workflow_run.artifacts_url | string | required | |
github.event.workflow_run.cancel_url | string | required | |
github.event.workflow_run.check_suite_id | integer | required | |
github.event.workflow_run.check_suite_node_id | string | required | |
github.event.workflow_run.check_suite_url | string | required | |
github.event.workflow_run.created_at | string | required | |
github.event.workflow_run.event | string | required | |
github.event.workflow_run.head_branch | string or null | required | |
github.event.workflow_run.head_commit | object | required | |
github.event.workflow_run.head_commit.author | object | required | Metaproperties for Git author/committer information. |
github.event.workflow_run.head_commit.author.date | string | optional | |
github.event.workflow_run.head_commit.author.email | string or null | required | |
github.event.workflow_run.head_commit.author.name | string | required | The git author’s name. |
github.event.workflow_run.head_commit.author.username | string | optional | |
github.event.workflow_run.head_commit.committer | object | required | Metaproperties for Git author/committer information. |
github.event.workflow_run.head_commit.committer.date | string | optional | |
github.event.workflow_run.head_commit.committer.email | string or null | required | |
github.event.workflow_run.head_commit.committer.name | string | required | The git author’s name. |
github.event.workflow_run.head_commit.committer.username | string | optional | |
github.event.workflow_run.head_commit.id | string | required | |
github.event.workflow_run.head_commit.message | string | required | |
github.event.workflow_run.head_commit.timestamp | string | required | |
github.event.workflow_run.head_commit.tree_id | string | required | |
github.event.workflow_run.head_repository | object | required | |
github.event.workflow_run.head_repository.archive_url | string | required | |
github.event.workflow_run.head_repository.assignees_url | string | required | |
github.event.workflow_run.head_repository.blobs_url | string | required | |
github.event.workflow_run.head_repository.branches_url | string | required | |
github.event.workflow_run.head_repository.collaborators_url | string | required | |
github.event.workflow_run.head_repository.comments_url | string | required | |
github.event.workflow_run.head_repository.commits_url | string | required | |
github.event.workflow_run.head_repository.compare_url | string | required | |
github.event.workflow_run.head_repository.contents_url | string | required | |
github.event.workflow_run.head_repository.contributors_url | string | required | |
github.event.workflow_run.head_repository.deployments_url | string | required | |
github.event.workflow_run.head_repository.description | string or null | required | |
github.event.workflow_run.head_repository.downloads_url | string | required | |
github.event.workflow_run.head_repository.events_url | string | required | |
github.event.workflow_run.head_repository.fork | boolean | required | |
github.event.workflow_run.head_repository.forks_url | string | required | |
github.event.workflow_run.head_repository.full_name | string | required | |
github.event.workflow_run.head_repository.git_commits_url | string | required | |
github.event.workflow_run.head_repository.git_refs_url | string | required | |
github.event.workflow_run.head_repository.git_tags_url | string | required | |
github.event.workflow_run.head_repository.hooks_url | string | required | |
github.event.workflow_run.head_repository.html_url | string | required | |
github.event.workflow_run.head_repository.id | integer | required | Unique identifier of the repository |
github.event.workflow_run.head_repository.issue_comment_url | string | required | |
github.event.workflow_run.head_repository.issue_events_url | string | required | |
github.event.workflow_run.head_repository.issues_url | string | required | |
github.event.workflow_run.head_repository.keys_url | string | required | |
github.event.workflow_run.head_repository.labels_url | string | required | |
github.event.workflow_run.head_repository.languages_url | string | required | |
github.event.workflow_run.head_repository.merges_url | string | required | |
github.event.workflow_run.head_repository.milestones_url | string | required | |
github.event.workflow_run.head_repository.name | string | required | The name of the repository. |
github.event.workflow_run.head_repository.node_id | string | required | |
github.event.workflow_run.head_repository.notifications_url | string | required | |
github.event.workflow_run.head_repository.owner | object or null | required | |
github.event.workflow_run.head_repository.owner.avatar_url | string | optional | |
github.event.workflow_run.head_repository.owner.deleted | boolean | optional | |
github.event.workflow_run.head_repository.owner.email | string or null | optional | |
github.event.workflow_run.head_repository.owner.events_url | string | optional | |
github.event.workflow_run.head_repository.owner.followers_url | string | optional | |
github.event.workflow_run.head_repository.owner.following_url | string | optional | |
github.event.workflow_run.head_repository.owner.gists_url | string | optional | |
github.event.workflow_run.head_repository.owner.gravatar_id | string | optional | |
github.event.workflow_run.head_repository.owner.html_url | string | optional | |
github.event.workflow_run.head_repository.owner.id | integer | required | |
github.event.workflow_run.head_repository.owner.login | string | required | |
github.event.workflow_run.head_repository.owner.name | string | optional | |
github.event.workflow_run.head_repository.owner.node_id | string | optional | |
github.event.workflow_run.head_repository.owner.organizations_url | string | optional | |
github.event.workflow_run.head_repository.owner.received_events_url | string | optional | |
github.event.workflow_run.head_repository.owner.repos_url | string | optional | |
github.event.workflow_run.head_repository.owner.site_admin | boolean | optional | |
github.event.workflow_run.head_repository.owner.starred_url | string | optional | |
github.event.workflow_run.head_repository.owner.subscriptions_url | string | optional | |
github.event.workflow_run.head_repository.owner.type | Bot , User , Organization | optional | |
github.event.workflow_run.head_repository.owner.url | string | optional | |
github.event.workflow_run.head_repository.private | boolean | required | Whether the repository is private or public. |
github.event.workflow_run.head_repository.pulls_url | string | required | |
github.event.workflow_run.head_repository.releases_url | string | required | |
github.event.workflow_run.head_repository.stargazers_url | string | required | |
github.event.workflow_run.head_repository.statuses_url | string | required | |
github.event.workflow_run.head_repository.subscribers_url | string | required | |
github.event.workflow_run.head_repository.subscription_url | string | required | |
github.event.workflow_run.head_repository.tags_url | string | required | |
github.event.workflow_run.head_repository.teams_url | string | required | |
github.event.workflow_run.head_repository.trees_url | string | required | |
github.event.workflow_run.head_repository.url | string | required | |
github.event.workflow_run.head_sha | string | required | |
github.event.workflow_run.html_url | string | required | |
github.event.workflow_run.id | integer | required | |
github.event.workflow_run.jobs_url | string | required | |
github.event.workflow_run.logs_url | string | required | |
github.event.workflow_run.name | string or null | required | |
github.event.workflow_run.node_id | string | required | |
github.event.workflow_run.path | string | required | |
github.event.workflow_run.previous_attempt_url | string or null | required | |
github.event.workflow_run.pull_requests | array of objects | required | |
github.event.workflow_run.pull_requests.base | object | required | |
github.event.workflow_run.pull_requests.base.ref | string | required | |
github.event.workflow_run.pull_requests.base.repo | object | required | |
github.event.workflow_run.pull_requests.base.repo.id | integer | required | |
github.event.workflow_run.pull_requests.base.repo.name | string | required | |
github.event.workflow_run.pull_requests.base.repo.url | string | required | |
github.event.workflow_run.pull_requests.base.sha | string | required | |
github.event.workflow_run.pull_requests.head | object | required | |
github.event.workflow_run.pull_requests.head.ref | string | required | |
github.event.workflow_run.pull_requests.head.repo | object | required | |
github.event.workflow_run.pull_requests.head.repo.id | integer | required | |
github.event.workflow_run.pull_requests.head.repo.name | string | required | |
github.event.workflow_run.pull_requests.head.repo.url | string | required | |
github.event.workflow_run.pull_requests.head.sha | string | required | |
github.event.workflow_run.pull_requests.id | number | required | |
github.event.workflow_run.pull_requests.number | number | required | |
github.event.workflow_run.pull_requests.url | string | required | |
github.event.workflow_run.referenced_workflows | array of objects or null | optional | |
github.event.workflow_run.referenced_workflows.path | string | required | |
github.event.workflow_run.referenced_workflows.ref | string | optional | |
github.event.workflow_run.referenced_workflows.sha | string | required | |
github.event.workflow_run.repository | object | required | |
github.event.workflow_run.repository.archive_url | string | required | |
github.event.workflow_run.repository.assignees_url | string | required | |
github.event.workflow_run.repository.blobs_url | string | required | |
github.event.workflow_run.repository.branches_url | string | required | |
github.event.workflow_run.repository.collaborators_url | string | required | |
github.event.workflow_run.repository.comments_url | string | required | |
github.event.workflow_run.repository.commits_url | string | required | |
github.event.workflow_run.repository.compare_url | string | required | |
github.event.workflow_run.repository.contents_url | string | required | |
github.event.workflow_run.repository.contributors_url | string | required | |
github.event.workflow_run.repository.deployments_url | string | required | |
github.event.workflow_run.repository.description | string or null | required | |
github.event.workflow_run.repository.downloads_url | string | required | |
github.event.workflow_run.repository.events_url | string | required | |
github.event.workflow_run.repository.fork | boolean | required | |
github.event.workflow_run.repository.forks_url | string | required | |
github.event.workflow_run.repository.full_name | string | required | |
github.event.workflow_run.repository.git_commits_url | string | required | |
github.event.workflow_run.repository.git_refs_url | string | required | |
github.event.workflow_run.repository.git_tags_url | string | required | |
github.event.workflow_run.repository.hooks_url | string | required | |
github.event.workflow_run.repository.html_url | string | required | |
github.event.workflow_run.repository.id | integer | required | Unique identifier of the repository |
github.event.workflow_run.repository.issue_comment_url | string | required | |
github.event.workflow_run.repository.issue_events_url | string | required | |
github.event.workflow_run.repository.issues_url | string | required | |
github.event.workflow_run.repository.keys_url | string | required | |
github.event.workflow_run.repository.labels_url | string | required | |
github.event.workflow_run.repository.languages_url | string | required | |
github.event.workflow_run.repository.merges_url | string | required | |
github.event.workflow_run.repository.milestones_url | string | required | |
github.event.workflow_run.repository.name | string | required | The name of the repository. |
github.event.workflow_run.repository.node_id | string | required | |
github.event.workflow_run.repository.notifications_url | string | required | |
github.event.workflow_run.repository.owner | object or null | required | |
github.event.workflow_run.repository.owner.avatar_url | string | optional | |
github.event.workflow_run.repository.owner.deleted | boolean | optional | |
github.event.workflow_run.repository.owner.email | string or null | optional | |
github.event.workflow_run.repository.owner.events_url | string | optional | |
github.event.workflow_run.repository.owner.followers_url | string | optional | |
github.event.workflow_run.repository.owner.following_url | string | optional | |
github.event.workflow_run.repository.owner.gists_url | string | optional | |
github.event.workflow_run.repository.owner.gravatar_id | string | optional | |
github.event.workflow_run.repository.owner.html_url | string | optional | |
github.event.workflow_run.repository.owner.id | integer | required | |
github.event.workflow_run.repository.owner.login | string | required | |
github.event.workflow_run.repository.owner.name | string | optional | |
github.event.workflow_run.repository.owner.node_id | string | optional | |
github.event.workflow_run.repository.owner.organizations_url | string | optional | |
github.event.workflow_run.repository.owner.received_events_url | string | optional | |
github.event.workflow_run.repository.owner.repos_url | string | optional | |
github.event.workflow_run.repository.owner.site_admin | boolean | optional | |
github.event.workflow_run.repository.owner.starred_url | string | optional | |
github.event.workflow_run.repository.owner.subscriptions_url | string | optional | |
github.event.workflow_run.repository.owner.type | Bot , User , Organization | optional | |
github.event.workflow_run.repository.owner.url | string | optional | |
github.event.workflow_run.repository.private | boolean | required | Whether the repository is private or public. |
github.event.workflow_run.repository.pulls_url | string | required | |
github.event.workflow_run.repository.releases_url | string | required | |
github.event.workflow_run.repository.stargazers_url | string | required | |
github.event.workflow_run.repository.statuses_url | string | required | |
github.event.workflow_run.repository.subscribers_url | string | required | |
github.event.workflow_run.repository.subscription_url | string | required | |
github.event.workflow_run.repository.tags_url | string | required | |
github.event.workflow_run.repository.teams_url | string | required | |
github.event.workflow_run.repository.trees_url | string | required | |
github.event.workflow_run.repository.url | string | required | |
github.event.workflow_run.rerun_url | string | required | |
github.event.workflow_run.run_attempt | integer | required | |
github.event.workflow_run.run_number | integer | required | |
github.event.workflow_run.run_started_at | string | required | |
github.event.workflow_run.triggering_actor | object or null | required | |
github.event.workflow_run.triggering_actor.avatar_url | string | optional | |
github.event.workflow_run.triggering_actor.deleted | boolean | optional | |
github.event.workflow_run.triggering_actor.email | string or null | optional | |
github.event.workflow_run.triggering_actor.events_url | string | optional | |
github.event.workflow_run.triggering_actor.followers_url | string | optional | |
github.event.workflow_run.triggering_actor.following_url | string | optional | |
github.event.workflow_run.triggering_actor.gists_url | string | optional | |
github.event.workflow_run.triggering_actor.gravatar_id | string | optional | |
github.event.workflow_run.triggering_actor.html_url | string | optional | |
github.event.workflow_run.triggering_actor.id | integer | required | |
github.event.workflow_run.triggering_actor.login | string | required | |
github.event.workflow_run.triggering_actor.name | string | optional | |
github.event.workflow_run.triggering_actor.node_id | string | optional | |
github.event.workflow_run.triggering_actor.organizations_url | string | optional | |
github.event.workflow_run.triggering_actor.received_events_url | string | optional | |
github.event.workflow_run.triggering_actor.repos_url | string | optional | |
github.event.workflow_run.triggering_actor.site_admin | boolean | optional | |
github.event.workflow_run.triggering_actor.starred_url | string | optional | |
github.event.workflow_run.triggering_actor.subscriptions_url | string | optional | |
github.event.workflow_run.triggering_actor.type | Bot , User , Organization | optional | |
github.event.workflow_run.triggering_actor.url | string | optional | |
github.event.workflow_run.updated_at | string | required | |
github.event.workflow_run.url | string | required | |
github.event.workflow_run.workflow_id | integer | required | |
github.event.workflow_run.workflow_url | string | required |
completed
#
This event occurs when there is activity relating to a run of a GitHub Actions workflow. For more information, see "About workflows." For information about the APIs to manage workflow runs, see the GraphQL documentation or "Workflow runs" in the REST API documentation.
For activity relating to a job in a workflow run, use the workflow_job
event.
To subscribe to this event, a GitHub App must have at least read-level access for the "Actions" repository permission.
field | type | required | description |
---|---|---|---|
github.event.action | completed | required | |
github.event.workflow_run.conclusion | success , failure , neutral , cancelled , timed_out , action_required , stale , None , skipped | required | |
github.event.workflow_run.status | requested , in_progress , completed , queued , pending , waiting | required |
in_progress
#
This event occurs when there is activity relating to a run of a GitHub Actions workflow. For more information, see "About workflows." For information about the APIs to manage workflow runs, see the GraphQL documentation or "Workflow runs" in the REST API documentation.
For activity relating to a job in a workflow run, use the workflow_job
event.
To subscribe to this event, a GitHub App must have at least read-level access for the "Actions" repository permission.
field | type | required | description |
---|---|---|---|
github.event.action | in_progress | required | |
github.event.workflow_run.conclusion | success , failure , neutral , cancelled , timed_out , action_required , stale , skipped , None | required | |
github.event.workflow_run.status | requested , in_progress , completed , queued , pending | required |
requested
#
This event occurs when there is activity relating to a run of a GitHub Actions workflow. For more information, see "About workflows." For information about the APIs to manage workflow runs, see the GraphQL documentation or "Workflow runs" in the REST API documentation.
For activity relating to a job in a workflow run, use the workflow_job
event.
To subscribe to this event, a GitHub App must have at least read-level access for the "Actions" repository permission.
field | type | required | description |
---|---|---|---|
github.event.action | requested | required | |
github.event.workflow_run.conclusion | success , failure , neutral , cancelled , timed_out , action_required , stale , None , skipped , startup_failure | required | |
github.event.workflow_run.status | requested , in_progress , completed , queued , pending , waiting | required | |
github.event.workflow_run.display_title | string | required |