Workflow triggers are events that cause a workflow to run. For more information about how to use workflow triggers, see "Triggering a workflow."
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: Not all webhook events trigger workflows.
Webhook event payloadActivity typesGITHUB_SHAGITHUB_REFbranch_protection_rule- createdediteddeletedLast commit on default branchDefault branch
Note: More than one activity type triggers this event. 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.
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 "Objects" in the GraphQL API documentation or "REST API endpoints for branches and their settings."
For example, you can run a workflow when a branch protection rule has been created or deleted:
on:
branch_protection_rule:
types:
[created
, deleted
]
GITHUB_SHAGITHUB_REFcheck_run- createdrerequestedcompletedrequested_actionLast commit on default branchDefault branch
Note: More than one activity type triggers this event. 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.
Runs your workflow when activity related to a check run occurs. A check run is an individual test that is part of a check suite. For information, see "Using the REST API to interact with checks." For information about the check run APIs, see "Objects" in the GraphQL API documentation or "REST API endpoints for checks."
For example, you can run a workflow when a check run has been rerequested or completed.
on:
check_run:
types:
[rerequested
, completed
]
GITHUB_SHAGITHUB_REFcheck_suite- completedLast commit on default branchDefault branch
Note: More than one activity type triggers this event. For information about each activity type, see "Webhook events and payloads." Although only the completed activity type is supported, specifying the activity type will keep your workflow specific if more activity types are added in the future. 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: To prevent recursive workflows, this event does not trigger workflows if the check suite was created by GitHub Actions.
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 "Using the REST API to interact with checks." For information about the check suite APIs, see "Objects" in the GraphQL API documentation or "REST API endpoints for checks."
For example, you can run a workflow when a check suite has been completed.
on:
check_suite:
types:
[completed
]
GITHUB_SHAGITHUB_REFcreateNot applicableLast commit on the created branch or tagBranch or tag created
Note: An event will not be created when you create more than three tags at once.
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 "Mutations" in the GraphQL API documentation or "REST API endpoints for Git database."
For example, you can run a workflow when the create event occurs.
on:
create
GITHUB_SHAGITHUB_REFdeleteNot applicableLast commit on default branchDefault branch
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
Note: An event will not be created when you delete more than three tags at once.
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 "Mutations" in the GraphQL API documentation or "REST API endpoints for Git database."
For example, you can run a workflow when the delete event occurs.
on:
delete
GITHUB_SHAGITHUB_REFdeploymentNot applicableCommit to be deployedBranch or tag to be deployed (empty if created with a commit SHA)
Runs your workflow when someone creates a deployment in the workflow's repository. Deployments created with a commit SHA may not have a Git ref. For information about the APIs to create a deployment, see "Mutations" in the GraphQL API documentation or "REST API endpoints for repositories."
For example, you can run a workflow when the deployment event occurs.
on:
deployment
GITHUB_SHAGITHUB_REFdeployment_statusNot applicableCommit to be deployedBranch or tag to be deployed (empty if commit)
Note: When a deployment status's state is set to inactive, a workflow run will not be triggered.
Runs your workflow when a third party provides a deployment status. Deployments created with a commit SHA may not have a Git ref. For information about the APIs to create a deployment status, see "Mutations" in the GraphQL API documentation or "REST API endpoints for deployments."
For example, you can run a workflow when the deployment_status event occurs.
on:
deployment_status
GITHUB_SHAGITHUB_REFdiscussion- createdediteddeletedtransferredpinnedunpinnedlabeledunlabeledlockedunlockedcategory_changedansweredunansweredLast commit on default branchDefault branch
Note: More than one activity type triggers this event. 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: Webhook events for GitHub Discussions are currently in beta and subject to change.
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 "Objects."
For example, you can run a workflow when a discussion has been created, edited, or answered.
on:
discussion:
types:
[created
, edited
, answered
]
GITHUB_SHAGITHUB_REFdiscussion_comment- createdediteddeletedNote: More than one activity type triggers this event. 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: Webhook events for GitHub Discussions are currently in beta and subject to change.
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 "Objects."
For example, you can run a workflow when a discussion comment has been created or deleted.
on:
discussion_comment:
types:
[created
, deleted
]
GITHUB_SHAGITHUB_REFforkNot applicableLast commit on default branchDefault branch
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
Runs your workflow when someone forks a repository. For information about the REST API, see "REST API endpoints for repositories."
For example, you can run a workflow when the fork event occurs.
on:
fork
GITHUB_SHAGITHUB_REFgollumNot applicableLast commit on default branchDefault branch
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
Runs your workflow when someone creates or updates a Wiki page. For more information, see "About wikis."
For example, you can run a workflow when the gollum event occurs.
on:
gollum
GITHUB_SHAGITHUB_REFissue_comment- createdediteddeletedNote: More than one activity type triggers this event. 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.
Runs your workflow when an issue or pull request comment is created, edited, or deleted. For information about the issue comment APIs, see "Objects" in the GraphQL API documentation or "Webhook events and payloads" 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
]
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.
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:
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:
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
}}
GITHUB_SHAGITHUB_REFissues- openedediteddeletedtransferredpinnedunpinnedclosedreopenedassignedunassignedlabeledunlabeledlockedunlockedmilestoneddemilestonedLast commit on default branchDefault branch
Note: More than one activity type triggers this event. 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.
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 more information about issues, see "About issues." For information about the issue APIs, see "Objects" in the GraphQL API documentation or "REST API endpoints for issues."
For example, you can run a workflow when an issue has been opened, edited, or milestoned.
on:
issues:
types:
[opened
, edited
, milestoned
]
GITHUB_SHAGITHUB_REFlabel- createdediteddeletedNote: More than one activity type triggers this event. 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.
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 "Objects" in the GraphQL API documentation or "REST API endpoints for issues."
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.
For example, you can run a workflow when a label has been created or deleted.
on:
label:
types:
[created
, deleted
]
GITHUB_SHAGITHUB_REFmerge_groupchecks_requestedSHA of the merge groupRef of the merge group
Note: More than one activity type triggers this event. Although only the checks_requested activity type is supported, specifying the activity type will keep your workflow specific if more activity types are added in the future. 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."
Runs your workflow when a pull request is added to a merge queue, which adds the pull request to a merge group. For more information see "Merging a pull request with a merge queue".
For example, you can run a workflow when the checks_requested activity has occurred.
on:
merge_group:
types:
[checks_requested
]
GITHUB_SHAGITHUB_REFmilestone- createdclosedopenedediteddeletedNote: More than one activity type triggers this event. 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.
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 "Objects" in the GraphQL API documentation or "REST API endpoints for issues."
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.
For example, you can run a workflow when a milestone has been opened or deleted.
on:
milestone:
types:
[opened
, deleted
]
GITHUB_SHAGITHUB_REFpage_buildNot applicableLast commit on default branchNot applicable
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
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." For information about the REST API, see "REST API endpoints for repositories."
For example, you can run a workflow when the page_build event occurs.
on:
page_build
GITHUB_SHAGITHUB_REFproject- createdclosedreopenedediteddeletedNote: More than one activity type triggers this event. The edited activity type refers to when a project (classic), not a column or card on the project (classic), is edited. 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: This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository.
Note: This event only occurs for projects (classic).
Runs your workflow when a project (classic) is created or modified. For activity related to cards or columns in a project (classic), use the project_card or project_column events instead. For more information about projects (classic), see "About projects (classic)." For information about the project (classic) APIs, see "Objects" in the GraphQL API documentation or "Projects (classic)" in the REST API documentation.
For example, you can run a workflow when a project has been created or deleted.
on:
project:
types:
[created
, deleted
]
GITHUB_SHAGITHUB_REFproject_card- createdmovedconverted to an issueediteddeletedLast commit on default branchDefault branch
Note: More than one activity type triggers this event. 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: This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository.
Note: This event only occurs for projects (classic).
Runs your workflow when a card on a project (classic) is created or modified. For activity related to projects (classic) or columns in a project (classic), use the project or project_column event instead. For more information about projects (classic), see "About projects (classic)." For information about the project card APIs, see "Objects" in the GraphQL API documentation or "Projects (classic)" 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
]
GITHUB_SHAGITHUB_REFproject_column- createdupdatedmoveddeletedLast commit on default branchDefault branch
Note: More than one activity type triggers this event. 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: This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository.
Note: This event only occurs for projects (classic).
Runs your workflow when a column on a project (classic) is created or modified. For activity related to projects (classic) or cards in a project (classic), use the project or project_card event instead. For more information about projects (classic), see "About projects (classic)." For information about the project column APIs, see "Objects" in the GraphQL API documentation or "Projects (classic)" in the REST API documentation.
For example, you can run a workflow when a project column has been created or deleted.
on:
project_column:
types:
[created
, deleted
]
GITHUB_SHAGITHUB_REFpublicNot applicableLast commit on default branchDefault branch
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
Runs your workflow when your workflow's repository changes from private to public. For information about the REST API, see "REST API endpoints for repositories."
For example, you can run a workflow when the public event occurs.
on:
public
GITHUB_SHAGITHUB_REFpull_request- assignedunassignedlabeledunlabeledopenededitedclosedreopenedsynchronizeconverted_to_draftlockedunlockedenqueueddequeuedmilestoneddemilestonedready_for_reviewreview_requestedreview_request_removedauto_merge_enabledauto_merge_disabledLast merge commit on the GITHUB_REF branchPR merge branch refs/pull/PULL_REQUEST_NUMBER/merge
Notes:
More than one activity type triggers this event. For information about each activity type, see "Webhook events and payloads." By default, a workflow only runs when a pull_request event's activity type is opened, synchronize, or reopened. To trigger workflows by different activity types, use the types keyword. For more information, see "Workflow syntax for GitHub Actions."
Workflows will not run on pull_request activity if the pull request has a merge conflict. The merge conflict must be resolved first.
Conversely, workflows with the pull_request_target event will run even if the pull request has a merge conflict. Before using the pull_request_target trigger, you should be aware of the security risks. For more information, see pull_request_target.
The pull_request webhook event payload is empty for merged pull requests and pull requests that come from forked repositories.
The value of GITHUB_REF varies for a closed pull request depending on whether the pull request has been merged or not. If a pull request was closed but not merged, it will be refs/pull/PULL_REQUEST_NUMBER/merge. If a pull request was closed as a result of being merged, it will be the fully qualified ref of the branch it was merged into, for example /refs/heads/main.
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 "Objects" in the GraphQL API documentation or "Pulls" 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'
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/**'
Note: If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a pull request that includes a change to a JavaScript (.js) file is opened on a branch whose name starts with 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/'"
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'
Note: If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a pull request that includes a change to a JavaScript (.js) file is opened on a branch whose name starts with releases/:
on:
pull_request:
types:
-
opened
branches:
-
'releases/**'
paths:
-
'**.js'
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.
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
Workflows don't run in forked repositories by default. You must enable GitHub Actions in the Actions tab of the forked repository.
With the exception of GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository. The GITHUB_TOKEN has read-only permissions in pull requests from forked repositories. For more information, see "Automatic token authentication."
For pull requests from a forked repository to the base repository, GitHub 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.
When a first-time contributor submits a pull request to a public repository, a maintainer with write access may need to approve running workflows on the pull request. For more information, see "Approving workflow runs from public forks."
For pull requests from a forked repository to a private repository, workflows only run when they are enabled, see "Managing GitHub Actions settings for a repository."
Note: Workflows triggered by Dependabot pull requests are treated as though they are from a forked repository, and are also subject to these restrictions.
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.
GITHUB_SHAGITHUB_REFpull_request_review- submittedediteddismissedLast merge commit on the GITHUB_REF branchPR merge branch refs/pull/PULL_REQUEST_NUMBER/merge
Note: More than one activity type triggers this event. 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."
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 "Objects" in the GraphQL API documentation or "Pulls" in the REST API documentation.
For example, you can run a workflow when a pull request review has been edited or dismissed.
on:
pull_request_review:
types:
[edited
, dismissed
]
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 don't run in forked repositories by default. You must enable GitHub Actions in the Actions tab of the forked repository.
With the exception of GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository. The GITHUB_TOKEN has read-only permissions in pull requests from forked repositories. For more information, see "Automatic token authentication."
For pull requests from a forked repository to the base repository, GitHub 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.
When a first-time contributor submits a pull request to a public repository, a maintainer with write access may need to approve running workflows on the pull request. For more information, see "Approving workflow runs from public forks."
For pull requests from a forked repository to a private repository, workflows only run when they are enabled, see "Managing GitHub Actions settings for a repository."
Note: Workflows triggered by Dependabot pull requests are treated as though they are from a forked repository, and are also subject to these restrictions.
Webhook event payloadActivity typesGITHUB_SHAGITHUB_REFpull_request_review_comment- createdediteddeletedLast merge commit on the GITHUB_REF branchPR merge branch refs/pull/PULL_REQUEST_NUMBER/merge
Note: More than one activity type triggers this event. 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."
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 "Objects" in the GraphQL API documentation or "Pulls" in the REST API documentation.
For example, you can run a workflow when a pull request review comment has been created or deleted.
on:
pull_request_review_comment:
types:
[created
, deleted
]
Workflows don't run in forked repositories by default. You must enable GitHub Actions in the Actions tab of the forked repository.
With the exception of GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository. The GITHUB_TOKEN has read-only permissions in pull requests from forked repositories. For more information, see "Automatic token authentication."
For pull requests from a forked repository to the base repository, GitHub 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.
When a first-time contributor submits a pull request to a public repository, a maintainer with write access may need to approve running workflows on the pull request. For more information, see "Approving workflow runs from public forks."
For pull requests from a forked repository to a private repository, workflows only run when they are enabled, see "Managing GitHub Actions settings for a repository."
Note: Workflows triggered by Dependabot pull requests are treated as though they are from a forked repository, and are also subject to these restrictions.
Webhook event payloadActivity typesGITHUB_SHAGITHUB_REFpull_request- assignedunassignedlabeledunlabeledopenededitedclosedreopenedsynchronizeconverted_to_draftready_for_reviewlockedunlocked review_requested review_request_removed auto_merge_enabled auto_merge_disabledLast commit on the PR base branchPR base branch
Note: More than one activity type triggers this event. For information about each activity type, see "Webhook events and payloads." By default, a workflow only runs when a pull_request_target event's activity type is opened, synchronize, or reopened. To trigger workflows by different activity types, use the types keyword. For more information, see "Workflow syntax for GitHub Actions."
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.
To ensure repository security, branches with names that match certain patterns (such as those which look similar to SHAs) may not trigger workflows with the pull_request_target event.
Warning: For workflows that are triggered by the pull_request_target event, the GITHUB_TOKEN is granted read/write repository permission unless the permissions key is specified and the workflow can access secrets, even when it is triggered from a fork. Although the workflow runs in the context of the base of the pull request, you should make sure that you do not check out, build, or run untrusted code from the pull request with this event. Additionally, any caches share the same scope as the base branch. To help prevent cache poisoning, you should not save the cache if there is a possibility that the cache contents were altered. For more information, see "Keeping your GitHub Actions and workflows secure: Preventing pwn requests" on the GitHub Security Lab website.
For example, you can run a workflow when a pull request has been assigned, opened, synchronize, or reopened.
on:
pull_request_target:
types:
[assigned
, opened
, synchronize
, reopened
]
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/**'
Note: If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a pull request that includes a change to a JavaScript (.js) file is opened on a branch whose name starts with 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_target:
types:
-
opened
jobs:
run_if:
if:
startsWith(github.head_ref,
'releases/'
)
runs-on:
ubuntu-latest
steps:
-
run:
echo
"The head of this PR starts with 'releases/'"
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'
Note: If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a pull request that includes a change to a JavaScript (.js) file is opened on a branch whose name starts with releases/:
on:
pull_request_target:
types:
-
opened
branches:
-
'releases/**'
paths:
-
'**.js'
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.
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
GITHUB_SHAGITHUB_REFpushNot applicableWhen you delete a branch, the SHA in the workflow run (and its associated refs) reverts to the default branch of the repository.Updated ref
Note: The webhook payload available to GitHub Actions does not include the added, removed, and modified attributes in the commit object. You can retrieve the full commit object using the API. For information, see "Objects" in the GraphQL API documentation or "REST API endpoints for commits."
Note: An event will not be created when you push more than three tags at once.
Runs your workflow when you push a commit or tag, or when you create a repository from a template.
For example, you can run a workflow when the push event occurs.
on:
push
Note: When a push webhook event triggers a workflow run, the Actions UI's "pushed by" field shows the account of the pusher and not the author or committer. However, if the changes are pushed to a repository using SSH authentication with a deploy key, then the "pushed by" field will be the repository admin who verified the deploy key when it was added it to a repository.
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/**'
Note: If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a push that includes a change to a JavaScript (.js) file is made to a branch whose name starts with releases/:
on:
push:
branches:
-
'releases/**'
paths:
-
'**.js'
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 "Workflow syntax for GitHub Actions."
For example, this workflow will run when someone pushes a tag that starts with v1..
on:
push:
tags:
-
v1.**
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'
Note: If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a push that includes a change to a JavaScript (.js) file is made to a branch whose name starts with releases/:
on:
push:
branches:
-
'releases/**'
paths:
-
'**.js'
GITHUB_SHAGITHUB_REFregistry_package- publishedupdatedCommit of the published packageBranch or tag of the published package
Note: More than one activity type triggers this event. 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: When pushing multi-architecture container images, this event occurs once per manifest, so you might observe your workflow triggering multiple times. To mitigate this, and only run your workflow job for the event that contains the actual image tag information, use a conditional:
jobs:
job_name:
if:
${{
github.event.registry_package.package_version.container_metadata.tag.name
!=
''
}}
Runs your workflow when activity related to GitHub Packages occurs in your repository. For more information, see "GitHub Packages Documentation."
For example, you can run a workflow when a new package version has been published.
on:
registry_package:
types:
[published
]
GITHUB_SHAGITHUB_REFrelease- published unpublished created edited deleted prereleasedreleasedLast commit in the tagged releaseTag ref of release refs/tags/<tag_name>
Note: More than one activity type triggers this event. 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: Workflows are not triggered for the created, edited, or deleted activity types for draft releases. When you create your release through the GitHub browser UI, your release may automatically be saved as a draft.
Note: The prereleased type will not trigger for pre-releases published from draft releases, but the published type will trigger. If you want a workflow to run when stable and pre-releases publish, subscribe to published instead of released and prereleased.
Runs your workflow when release activity in your repository occurs. For information about the release APIs, see "Objects" in the GraphQL API documentation or "REST API endpoints for releases and release assets" in the REST API documentation.
For example, you can run a workflow when a release has been published.
on:
release:
types:
[published
]
GITHUB_SHAGITHUB_REFrepository_dispatchCustomLast commit on default branchDefault branch
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
You can use the GitHub API to trigger a webhook event called repository_dispatch when you want to trigger a workflow for activity that happens outside of GitHub. For more information, see "REST API endpoints for repositories."
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:
[test_result
]
Note: The event_type value is limited to 100 characters.
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
Notes:
client_payload is 10.GITHUB_SHAGITHUB_REFNot applicableNot applicableLast commit on default branchDefault branch
Notes:
schedule event can be delayed during periods of high loads of GitHub Actions workflow runs. High load times include the start of every hour. If the load is sufficiently high enough, some queued jobs may be dropped. To decrease the chance of delay, schedule your workflow to run at a different time of the hour.The schedule event allows you to trigger a workflow at a scheduled time.
You can schedule a workflow to run at specific UTC times using POSIX cron syntax. Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes.
This example triggers the workflow every day at 5:30 and 17:30 UTC:
on:
schedule:
-
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"
Cron syntax has five fields separated by a space, and each field represents a unit of time.
┌───────────── 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)
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
* * * * *
You can use these operators in any of the five fields:
OperatorDescriptionExample*Any value15 * * * * runs at every minute 15 of every hour of every day.,Value list separator2,10 4,5 * * * runs at minute 2 and 10 of the 4th and 5th hour of every day.-Range of values30 4-6 * * * runs at minute 30 of the 4th, 5th, and 6th hour./Step values20/15 * * * * runs every 15 minutes starting from minute 20 through 59 (minutes 20, 35, and 50).
Note: GitHub Actions does not support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly, and @reboot.
You can use crontab guru to help generate your cron syntax and confirm what time it will run. To help you get started, there is also a list of crontab guru examples.
Notifications for scheduled workflows are sent to the user who last modified the cron syntax in the workflow file. For more information, see "Notifications for workflow runs."
Webhook event payloadActivity typesGITHUB_SHAGITHUB_REFstatusNot applicableLast commit on default branchNot applicable
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
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 "Objects" in the GraphQL API documentation or "REST API endpoints for commits."
For example, you can run a workflow when the status event occurs.
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
GITHUB_SHAGITHUB_REFwatch- startedLast commit on default branchDefault branch
Note: More than one activity type triggers this event. Although only the started activity type is supported, specifying the activity type will keep your workflow specific if more activity types are added in the future. 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.
Runs your workflow when the workflow's repository is starred. For information about the pull request APIs, see "Mutations" in the GraphQL API documentation or "REST API endpoints for activity."
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
]
GITHUB_SHAGITHUB_REFSame as the caller workflowNot applicableSame as the caller workflowSame as the caller workflow
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 payload 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
GITHUB_SHAGITHUB_REFworkflow_dispatchNot applicableLast commit on the GITHUB_REF branch or tagBranch or tag that received dispatch
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
To enable a workflow to be triggered manually, you need to configure the workflow_dispatch event. You can manually trigger a workflow run using the GitHub API, GitHub CLI, or GitHub browser interface. For more information, see "Manually running a workflow."
on:
workflow_dispatch
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 inputs context. For more information, see "Contexts."
Notes:
github.event.inputs context. The information in the inputs context and github.event.inputs context is identical except that the inputs context preserves Boolean values as Booleans instead of converting them to strings. The choice type resolves to a string and is a single selectable option.inputs is 10.inputs is 65,535 characters.This example defines inputs called logLevel, tags, and environment. You pass values for these inputs to the workflow when you run it. This workflow then prints the values to the log, using the inputs.logLevel, inputs.tags, and inputs.environment context properties.
on:
workflow_dispatch:
inputs:
logLevel:
description:
'Log level'
required:
true
default:
'warning'
type:
choice
options:
-
info
-
warning
-
debug
tags:
description:
'Test scenario tags'
required:
false
type:
boolean
environment:
description:
'Environment to run tests against'
type:
environment
required:
true
jobs:
log-the-inputs:
runs-on:
ubuntu-latest
steps:
-
run:
|
echo "Log level: $LEVEL"
echo "Tags: $TAGS"
echo "Environment: $ENVIRONMENT"
env:
LEVEL:
${{
inputs.logLevel
}}
TAGS:
${{
inputs.tags
}}
ENVIRONMENT:
${{
inputs.environment
}}
If you run this workflow from a browser you must enter values for the required inputs manually before the workflow will run.
You can also pass inputs when you run a workflow from a script, or by using GitHub CLI. For example:
gh workflow run run-tests.yml -f logLevel=warning -f tags=false -f environment=staging
For more information, see the GitHub CLI information in "Manually running a workflow."
Webhook event payloadActivity typesGITHUB_SHAGITHUB_REFworkflow_run- completedrequestedin_progressLast commit on default branchDefault 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
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'
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
]
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!'
});
GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production.
GitHub Actions goes beyond just DevOps and lets you run workflows when other events happen in your repository. For example, you can run a workflow to automatically add the appropriate labels whenever someone creates a new issue in your repository.
GitHub provides Linux, Windows, and macOS virtual machines to run your workflows, or you can host your own self-hosted runners in your own data center or cloud infrastructure.
For more information about introducing GitHub Actions to your enterprise, see "Introducing GitHub Actions to your enterprise."
You can configure a GitHub Actions workflow to be triggered when an event occurs in your repository, such as a pull request being opened or an issue being created. Your workflow contains one or more jobs which can run in sequential order or in parallel. Each job will run inside its own virtual machine runner, or inside a container, and has one or more steps that either run a script that you define or run an action, which is a reusable extension that can simplify your workflow.
A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.
Workflows are defined in the .github/workflows directory in a repository, and a repository can have multiple workflows, each of which can perform a different set of tasks. For example, you can have one workflow to build and test pull requests, another workflow to deploy your application every time a release is created, and still another workflow that adds a label every time someone opens a new issue.
You can reference a workflow within another workflow. For more information, see "Reusing workflows."
For more information about workflows, see "Using workflows."
An event is a specific activity in a repository that triggers a workflow run. For example, activity can originate from GitHub when someone creates a pull request, opens an issue, or pushes a commit to a repository. You can also trigger a workflow to run on a schedule, by posting to a REST API, or manually.
For a complete list of events that can be used to trigger workflows, see Events that trigger workflows.
A job is a set of steps in a workflow that is executed on the same runner. Each step is either a shell script that will be executed, or an action that will be run. Steps are executed in order and are dependent on each other. Since each step is executed on the same runner, you can share data from one step to another. For example, you can have a step that builds your application followed by a step that tests the application that was built.
You can configure a job's dependencies with other jobs; by default, jobs have no dependencies and run in parallel with each other. When a job takes a dependency on another job, it will wait for the dependent job to complete before it can run. For example, you may have multiple build jobs for different architectures that have no dependencies, and a packaging job that is dependent on those jobs. The build jobs will run in parallel, and when they have all completed successfully, the packaging job will run.
For more information about jobs, see "Using jobs."
An action is a custom application for the GitHub Actions platform that performs a complex but frequently repeated task. Use an action to help reduce the amount of repetitive code that you write in your workflow files. An action can pull your git repository from GitHub, set up the correct toolchain for your build environment, or set up the authentication to your cloud provider.
You can write your own actions, or you can find actions to use in your workflows in the GitHub Marketplace.
To share actions across your enterprise without publishing the actions publicly, you can store the actions in an internal repository, then configure the repository to allow access to GitHub Actions workflows in other repositories owned by the same organization or by any organization in the enterprise. For more information, see "Sharing actions and workflows with your enterprise."
For more information, see "Creating actions."
A runner is a server that runs your workflows when they're triggered. Each runner can run a single job at a time. GitHub provides Ubuntu Linux, Microsoft Windows, and macOS runners to run your workflows; each workflow run executes in a fresh, newly-provisioned virtual machine. GitHub also offers larger runners, which are available in larger configurations. For more information, see "About larger runners." If you need a different operating system or require a specific hardware configuration, you can host your own runners. For more information about self-hosted runners, see "Hosting your own runners."
GitHub Actions uses YAML syntax to define the workflow. Each workflow is stored as a separate YAML file in your code repository, in a directory named .github/workflows.
You can create an example workflow in your repository that automatically triggers a series of commands whenever code is pushed. In this workflow, GitHub Actions checks out the pushed code, installs the bats testing framework, and runs a basic command to output the bats version: bats -v.
In your repository, create the .github/workflows/ directory to store your workflow files.
In the .github/workflows/ directory, create a new file called learn-github-actions.yml and add the following code.
YAML
name: learn-github-actions
run-name: ${{ github.actor }} is learning GitHub Actions
on: [push]
jobs:
check-bats-version:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
- run: npm install -g bats
- run: bats -v
name:
learn-github-actions
run-name:
${{
github.actor
}}
is
learning
GitHub
Actions
on:
[push
]
jobs:
check-bats-version:
runs-on:
ubuntu-latest
steps:
-
uses:
actions/checkout@v4
-
uses:
actions/setup-node@v4
with:
node-version:
'14'
-
run:
npm
install
-g
bats
-
run:
bats
-v
Commit these changes and push them to your GitHub repository.
Your new GitHub Actions workflow file is now installed in your repository and will run automatically each time someone pushes a change to the repository. To see the details about a workflow's execution history, see "Viewing the activity for a workflow run."
To help you understand how YAML syntax is used to create a workflow file, this section explains each line of the introduction's example:
YAML
# Optional - The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. If this field is omitted, the name of the workflow file will be used instead.
name: learn-github-actions
# Optional - The name for workflow runs generated from the workflow, which will appear in the list of workflow runs on your repository's "Actions" tab. This example uses an expression with the `github` context to display the username of the actor that triggered the workflow run. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#run-name)."
run-name: ${{ github.actor }} is learning GitHub Actions
# Specifies the trigger for this workflow. This example uses the `push` event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see "[AUTOTITLE](/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)."
on: [push]
# Groups together all the jobs that run in the `learn-github-actions` workflow.
jobs:
# Defines a job named `check-bats-version`. The child keys will define properties of the job.
check-bats-version:
# Configures the job to run on the latest version of an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see "[AUTOTITLE](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)"
runs-on: ubuntu-latest
# Groups together all the steps that run in the `check-bats-version` job. Each item nested under this section is a separate action or shell script.
steps:
# The `uses` keyword specifies that this step will run `v4` of the `actions/checkout` action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will use the repository's code.
- uses: actions/checkout@v4
# This step uses the `actions/setup-node@v4` action to install the specified version of the Node.js. (This example uses version 14.) This puts both the `node` and `npm` commands in your `PATH`.
- uses: actions/setup-node@v4
with:
node-version: '14'
# The `run` keyword tells the job to execute a command on the runner. In this case, you are using `npm` to install the `bats` software testing package.
- run: npm install -g bats
# Finally, you'll run the `bats` command with a parameter that outputs the software version.
- run: bats -v
name:
learn-github-actions
Optional - The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. If this field is omitted, the name of the workflow file will be used instead.
run-name:
${{
github.actor
}}
is
learning
GitHub
Actions
Optional - The name for workflow runs generated from the workflow, which will appear in the list of workflow runs on your repository's "Actions" tab. This example uses an expression with the github context to display the username of the actor that triggered the workflow run. For more information, see "Workflow syntax for GitHub Actions."
on:
[push
]Specifies the trigger for this workflow. This example uses the push event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see "Workflow syntax for GitHub Actions."
jobs:
Groups together all the jobs that run in the learn-github-actions workflow.
check-bats-version:
Defines a job named check-bats-version. The child keys will define properties of the job.
runs-on:
ubuntu-latest
Configures the job to run on the latest version of an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see "Workflow syntax for GitHub Actions"
steps:
Groups together all the steps that run in the check-bats-version job. Each item nested under this section is a separate action or shell script.
-
uses:
actions/checkout@v4
The uses keyword specifies that this step will run v4 of the actions/checkout action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will use the repository's code.
-
uses:
actions/setup-node@v4
with:
node-version:
'14'
This step uses the actions/setup-node@v4 action to install the specified version of the Node.js. (This example uses version 14.) This puts both the node and npm commands in your PATH.
-
run:
npm
install
-g
bats
The run keyword tells the job to execute a command on the runner. In this case, you are using npm to install the bats software testing package.
-
run:
bats
-v
Finally, you'll run the bats command with a parameter that outputs the software version.
name:
learn-github-actions
run-name:
${{
github.actor
}}
is
learning
GitHub
Actions
on:
[push
]
jobs:
check-bats-version:
runs-on:
ubuntu-latest
steps:
-
uses:
actions/checkout@v4
-
uses:
actions/setup-node@v4
with:
node-version:
'14'
-
run:
npm
install
-g
bats
-
run:
bats
-v
In this diagram, you can see the workflow file you just created and how the GitHub Actions components are organized in a hierarchy. Each step executes a single action or shell script. Steps 1 and 2 run actions, while steps 3 and 4 run shell scripts. To find more prebuilt actions for your workflows, see "Finding and customizing actions."
When your workflow is triggered, a workflow run is created that executes the workflow. After a workflow run has started, you can see a visualization graph of the run's progress and view each step's activity on GitHub.
On GitHub.com, navigate to the main page of the repository.
Under your repository name, click Actions.
In the left sidebar, click the workflow you want to see.
From the list of workflow runs, click the name of the run to see the workflow run summary.
In the left sidebar or in the visualization graph, click the job you want to see.
To view the results of a step, click the step.
GitHub Actions can help you automate nearly every aspect of your application development processes. Ready to get started? Here are some helpful resources for taking your next steps with GitHub Actions:
Please visit our website for more information on this topic.
Want more information on Flow Meter Measurement? Feel free to contact us.