Prerequisites

To learn more about workflows and triggering workflows, seeWorkflows.

Triggering a workflow from a workflow

When you use the repository'sGITHUB_TOKEN to perform tasks, events triggered by theGITHUB_TOKEN, with the exception ofworkflow_dispatch andrepository_dispatch, will not create a new workflow run. This prevents you from accidentally creating recursive workflow runs. For example, if a workflow run pushes code using the repository'sGITHUB_TOKEN, a new workflow will not run even when the repository contains a workflow configured to run whenpush events occur. For more information, seeUse GITHUB_TOKEN for authentication in workflows.

If you do want to trigger a workflow from within a workflow run, you can use a GitHub App installation access token or a personal access token instead ofGITHUB_TOKEN to trigger events that require a token.

If you use a GitHub App, you'll need to create a GitHub App and store the app ID and private key as secrets. For more information, seeMaking authenticated API requests with a GitHub App in a GitHub Actions workflow. If you use a personal access token, you'll need to create a personal access token and store it as a secret. For more information about creating a personal access token, seeManaging your personal access tokens. For more information about storing secrets, seeUsing secrets in GitHub Actions.

To minimize your GitHub Actions usage costs, ensure that you don't create recursive or unintended workflow runs.

For example, the following workflow uses a personal access token (stored as a secret calledMY_TOKEN) to add a label to an issue via GitHub CLI. Any workflows that run when a label is added will run once this step is performed.

on:issues:types:-openedjobs:label_issue:runs-on:ubuntu-lateststeps:-env:GH_TOKEN:${{secrets.MY_TOKEN}}ISSUE_URL:${{github.event.issue.html_url}}run:|          gh issue edit $ISSUE_URL --add-label "triage"

Conversely, the following workflow usesGITHUB_TOKEN to add a label to an issue. It will not trigger any workflows that run when a label is added.

on:issues:types:-openedjobs:label_issue:runs-on:ubuntu-lateststeps:-env:GH_TOKEN:${{secrets.GITHUB_TOKEN}}ISSUE_URL:${{github.event.issue.html_url}}run:|          gh issue edit $ISSUE_URL --add-label "triage"

Using events to trigger workflows

Use theon key to specify what events trigger your workflow. For more information about events you can use, seeEvents that trigger workflows.

Using a single event

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

on:push

Using multiple events

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

on: [push,fork]

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

Using activity types and filters with multiple events

You can use activity types and filters to further control when your workflow will run. For more information, seeUsing event activity types andUsing filters. If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately. You must append a colon (:) to all events, including events without configuration.

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

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

on:label:types:-createdpush:branches:-mainpage_build:

Using event activity types

Some events have activity types that give you more control over when your workflow should run. Useon.<event_name>.types to define the type of event activity that will trigger a workflow run.

For example, theissue_comment event has thecreated,edited, anddeleted activity types. If your workflow triggers on thelabel event, it will run whenever a label is created, edited, or deleted. If you specify thecreated activity type for thelabel event, your workflow will run when a label is created but not when a label is edited or deleted.

on:label:types:-created

If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events.

on:issues:types:-opened-labeled

For more information about each event and their activity types, seeEvents that trigger workflows.

Using filters

Some events have filters that give you more control over when your workflow should run.

For example, thepush event has abranches filter that causes your workflow to run only when a push to a branch that matches thebranches filter occurs, instead of when any push occurs.

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

Using filters to target specific branches for pull request events

When using thepull_request andpull_request_target events, you can configure a workflow to run only for pull requests that target specific branches.

Use thebranches filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use thebranches-ignore filter when you only want to exclude branch name patterns. You cannot use both thebranches andbranches-ignore filters for the same event in a workflow.

If you define bothbranches/branches-ignore andpaths/paths-ignore, the workflow will only run when both filters are satisfied.

Thebranches andbranches-ignore keywords accept glob patterns that use characters like*,**,+,?,! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with\. For more information about glob patterns, see theWorkflow syntax for GitHub Actions.

Example: Including branches

The patterns defined inbranches are evaluated against the Git ref's name. For example, the following workflow would run whenever there is apull_request event for a pull request targeting:

• A branch namedmain (refs/heads/main)
• A branch namedmona/octocat (refs/heads/mona/octocat)
• A branch whose name starts withreleases/, likereleases/10 (refs/heads/releases/10)

on:pull_request:# Sequence of patterns matched against refs/headsbranches:-main-'mona/octocat'-'releases/**'

If a workflow is skipped due to branch filtering,path filtering, or acommit message, then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.

Example: Excluding branches

When a pattern matches thebranches-ignore pattern, the workflow will not run. The patterns defined inbranches-ignore are evaluated against the Git ref's name. For example, the following workflow would run whenever there is apull_request event unless the pull request is targeting:

• A branch namedmona/octocat (refs/heads/mona/octocat)
• A branch whose name matchesreleases/**-alpha, likereleases/beta/3-alpha (refs/heads/releases/beta/3-alpha)

on:pull_request:# Sequence of patterns matched against refs/headsbranches-ignore:-'mona/octocat'-'releases/**-alpha'

Example: Including and excluding branches

You cannot usebranches andbranches-ignore to filter the same event in a single workflow. If you want to both include and exclude branch patterns for a single event, use thebranches filter along with the! character to indicate which branches should be excluded.

If you define a branch with the! character, you must also define at least one branch without the! character. If you only want to exclude branches, usebranches-ignore instead.

The order that you define patterns matters.

• A matching negative pattern (prefixed with!) after a positive match will exclude the Git ref.
• A matching positive pattern after a negative match will include the Git ref again.

The following workflow will run onpull_request events for pull requests that targetreleases/10 orreleases/beta/mona, but not for pull requests that targetreleases/10-alpha orreleases/beta/3-alpha because the negative pattern!releases/**-alpha follows the positive pattern.

on:pull_request:branches:-'releases/**'-'!releases/**-alpha'

Using filters to target specific branches or tags for push events

When using thepush event, you can configure a workflow to run on specific branches or tags.

Use thebranches filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use thebranches-ignore filter when you only want to exclude branch name patterns. You cannot use both thebranches andbranches-ignore filters for the same event in a workflow.

Use thetags filter when you want to include tag name patterns or when you want to both include and exclude tag names patterns. Use thetags-ignore filter when you only want to exclude tag name patterns. You cannot use both thetags andtags-ignore filters for the same event in a workflow.

If you define onlytags/tags-ignore or onlybranches/branches-ignore, the workflow won't run for events affecting the undefined Git ref. If you define neithertags/tags-ignore orbranches/branches-ignore, the workflow will run for events affecting either branches or tags. If you define bothbranches/branches-ignore andpaths/paths-ignore, the workflow will only run when both filters are satisfied.

Thebranches,branches-ignore,tags, andtags-ignore keywords accept glob patterns that use characters like*,**,+,?,! and others to match more than one branch or tag name. If a name contains any of these characters and you want a literal match, you need toescape each of these special characters with\. For more information about glob patterns, see theWorkflow syntax for GitHub Actions.

Example: Including branches and tags

The patterns defined inbranches andtags are evaluated against the Git ref's name. For example, the following workflow would run whenever there is apush event to:

• A branch namedmain (refs/heads/main)
• A branch namedmona/octocat (refs/heads/mona/octocat)
• A branch whose name starts withreleases/, likereleases/10 (refs/heads/releases/10)
• A tag namedv2 (refs/tags/v2)
• A tag whose name starts withv1., likev1.9.1 (refs/tags/v1.9.1)

on:push:# Sequence of patterns matched against refs/headsbranches:-main-'mona/octocat'-'releases/**'# Sequence of patterns matched against refs/tagstags:-v2-v1.*

Example: Excluding branches and tags

When a pattern matches thebranches-ignore ortags-ignore pattern, the workflow will not run. The patterns defined inbranches andtags are evaluated against the Git ref's name. For example, the following workflow would run whenever there is apush event, unless thepush event is to:

• A branch namedmona/octocat (refs/heads/mona/octocat)
• A branch whose name matchesreleases/**-alpha, likereleases/beta/3-alpha (refs/heads/releases/beta/3-alpha)
• A tag namedv2 (refs/tags/v2)
• A tag whose name starts withv1., likev1.9 (refs/tags/v1.9)

on:push:# Sequence of patterns matched against refs/headsbranches-ignore:-'mona/octocat'-'releases/**-alpha'# Sequence of patterns matched against refs/tagstags-ignore:-v2-v1.*

Example: Including and excluding branches and tags

You can't usebranches andbranches-ignore to filter the same event in a single workflow. Similarly, you can't usetags andtags-ignore to filter the same event in a single workflow. If you want to both include and exclude branch or tag patterns for a single event, use thebranches ortags filter along with the! character to indicate which branches or tags should be excluded.

If you define a branch with the! character, you must also define at least one branch without the! character. If you only want to exclude branches, usebranches-ignore instead. Similarly, if you define a tag with the! character, you must also define at least one tag without the! character. If you only want to exclude tags, usetags-ignore instead.

The order that you define patterns matters.

• A matching negative pattern (prefixed with!) after a positive match will exclude the Git ref.
• A matching positive pattern after a negative match will include the Git ref again.

The following workflow will run on pushes toreleases/10 orreleases/beta/mona, but not onreleases/10-alpha orreleases/beta/3-alpha because the negative pattern!releases/**-alpha follows the positive pattern.

on:push:branches:-'releases/**'-'!releases/**-alpha'

Using filters to target specific paths for pull request or push events

When using thepush andpull_request events, you can configure a workflow to run based on what file paths are changed. Path filters are not evaluated for pushes of tags.

Use thepaths filter when you want to include file path patterns or when you want to both include and exclude file path patterns. Use thepaths-ignore filter when you only want to exclude file path patterns. You cannot use both thepaths andpaths-ignore filters for the same event in a workflow. If you want to both include and exclude path patterns for a single event, use thepaths filter prefixed with the! character to indicate which paths should be excluded.

If you define bothbranches/branches-ignore andpaths/paths-ignore, the workflow will only run when both filters are satisfied.

Thepaths andpaths-ignore keywords accept glob patterns that use the* and** wildcard characters to match more than one path name. For more information, see theWorkflow syntax for GitHub Actions.

Example: Including paths

If at least one path matches a pattern in thepaths filter, the workflow runs. For example, the following workflow would run anytime you push a JavaScript file (.js).

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

If a workflow is skipped due to path filtering,branch filtering, or acommit message, then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.

Example: Excluding paths

When all the path names match patterns inpaths-ignore, the workflow will not run. If any path names do not match patterns inpaths-ignore, even if some path names match the patterns, the workflow will run.

A workflow with the following path filter will only run onpush events that include at least one file outside thedocs directory at the root of the repository.

on:push:paths-ignore:-'docs/**'

Example: Including and excluding paths

You cannot usepaths andpaths-ignore to filter the same event in a single workflow. If you want to both include and exclude path patterns for a single event, use thepaths filter prefixed with the! character to indicate which paths should be excluded.

If you define a path with the! character, you must also define at least one path without the! character. If you only want to exclude paths, usepaths-ignore instead.

The order that you definepaths patterns matters:

• A matching negative pattern (prefixed with!) after a positive match will exclude the path.
• A matching positive pattern after a negative match will include the path again.

This example runs anytime thepush event includes a file in thesub-project directory or its subdirectories, unless the file is in thesub-project/docs directory. For example, a push that changedsub-project/index.js orsub-project/src/index.js will trigger a workflow run, but a push changing onlysub-project/docs/readme.md will not.

on:push:paths:-'sub-project/**'-'!sub-project/docs/**'

Git diff comparisons

The filter determines if a workflow should run by evaluating the changed files and running them against thepaths-ignore orpaths list. If there are no files changed, the workflow will not run.

GitHub generates the list of changed files using two-dot diffs for pushes and three-dot diffs for pull requests:

• Pull requests: Three-dot diffs are a comparison between the most recent version of the topic branch and the commit where the topic branch was last synced with the base branch.
• Pushes to existing branches: A two-dot diff compares the head and base SHAs directly with each other.
• Pushes to new branches: A two-dot diff against the parent of the ancestor of the deepest commit pushed.

For more information, seeAbout comparing branches in pull requests.

Using filters to target specific branches for workflow run events

When using theworkflow_run event, you can specify what branches the triggering workflow must run on in order to trigger your workflow.

Thebranches andbranches-ignore filters accept glob patterns that use characters like*,**,+,?,! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need toescape each of these special characters with\. For more information about glob patterns, see theWorkflow syntax for GitHub Actions.

For example, a workflow with the following trigger will only run when the workflow namedBuild runs on a branch whose name starts withreleases/:

on:workflow_run:workflows: ["Build"]types: [requested]branches:-'releases/**'

A workflow with the following trigger will only run when the workflow namedBuild runs on a branch that is not namedcanary:

on:workflow_run:workflows: ["Build"]types: [requested]branches-ignore:-"canary"

You cannot use both thebranches andbranches-ignore filters for the same event in a workflow. If you want to both include and exclude branch patterns for a single event, use thebranches filter along with the! character to indicate which branches should be excluded.

The order that you define patterns matters.

• A matching negative pattern (prefixed with!) after a positive match will exclude the branch.
• A matching positive pattern after a negative match will include the branch again.

For example, a workflow with the following trigger will run when the workflow namedBuild runs on a branch that is namedreleases/10 orreleases/beta/mona but will notreleases/10-alpha,releases/beta/3-alpha, ormain.

on:workflow_run:workflows: ["Build"]types: [requested]branches:-'releases/**'-'!releases/**-alpha'

Defining inputs for manually triggered workflows

When using theworkflow_dispatch event, you can optionally specify inputs that are passed to the workflow.

This trigger only receives events when the workflow file is on the default branch.The triggered workflow receives the inputs in theinputs context. For more information, seeContexts.

on:workflow_dispatch:inputs:logLevel:description:'Log level'required:truedefault:'warning'type:choiceoptions:-info-warning-debugprint_tags:description:'True to print to STDOUT'required:truetype:booleantags:description:'Test scenario tags'required:truetype:stringenvironment:description:'Environment to run tests against'type:environmentrequired:truejobs:print-tag:runs-on:ubuntu-latestif:${{inputs.print_tags}}steps:-name:PrinttheinputtagtoSTDOUTrun:echoThetagsare${{inputs.tags}}

Defining inputs, outputs, and secrets for reusable workflows

You can define inputs and secrets that a reusable workflow should receive from a calling workflow. You can also specify outputs that a reusable workflow will make available to a calling workflow. For more information, seeReuse workflows.

Using event information

Information about the event that triggered a workflow run is available in thegithub.event context. The properties in thegithub.event context depend on the type of event that triggered the workflow. For example, a workflow triggered when an issue is labeled would have information about the issue and label.

Viewing all properties of an event

Reference the webhook event documentation for common properties and example payloads. For more information, seeWebhook events and payloads.

You can also print the entiregithub.event context to see what properties are available for the event that triggered your workflow:

jobs:print_context:runs-on:ubuntu-lateststeps:-env:EVENT_CONTEXT:${{toJSON(github.event)}}run:|          echo $EVENT_CONTEXT

Accessing and using event properties

You can use thegithub.event context in your workflow. For example, the following workflow runs when a pull request that changespackage*.json,.github/CODEOWNERS, or.github/workflows/** is opened. If the pull request author (github.event.pull_request.user.login) is notoctobot ordependabot[bot], then the workflow uses the GitHub CLI to label and comment on the pull request (github.event.pull_request.number).

on:pull_request:types:-openedpaths:-'.github/workflows/**'-'.github/CODEOWNERS'-'package*.json'jobs:triage:if:>-      github.event.pull_request.user.login != 'octobot' &&      github.event.pull_request.user.login != 'dependabot[bot]'runs-on:ubuntu-lateststeps:-name:"Comment about changes we can't accept"env:GH_TOKEN:${{secrets.GITHUB_TOKEN}}PR:${{github.event.pull_request.html_url}}run:|          gh pr edit $PR --add-label 'invalid'          gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. We do not allow contributions to these files. Please review our [contributing guidelines](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) for what contributions are accepted.'

For more information about contexts, seeContexts reference. For more information about event payloads, seeWebhook events and payloads.

Further controlling how your workflow will run

If you want more granular control than events, event activity types, or event filters provide, you can use conditionals and environments to control whether individual jobs or steps in your workflow will run.

Using conditionals

You can use conditionals to further control whether jobs or steps in your workflow will run.

Example using a value in the event payload

For example, if you want the workflow to run when a specific label is added to an issue, you can trigger on theissues labeled event activity type and use a conditional to check what label triggered the workflow. The following workflow will run when any label is added to an issue in the workflow's repository, but therun_if_label_matches job will only execute if the label is namedbug.

on:issues:types:-labeledjobs:run_if_label_matches:if:github.event.label.name=='bug'runs-on:ubuntu-lateststeps:-run:echo'The label was bug'

Example using event type

For example, if you want to run different jobs or steps depending on what event triggered the workflow, you can use a conditional to check whether a specific event type exists in the event context. The following workflow will run whenever an issue or pull request is closed. If the workflow ran because an issue was closed, thegithub.event context will contain a value forissue but not forpull_request. Therefore, theif_issue step will run but theif_pr step will not run. Conversely, if the workflow ran because a pull request was closed, theif_pr step will run but theif_issue step will not run.

on:issues:types:-closedpull_request:types:-closedjobs:state_event_type:runs-on:ubuntu-lateststeps:-name:if_issueif:github.event.issuerun:|        echo An issue was closed-name:if_prif:github.event.pull_requestrun:|        echo A pull request was closed

For more information about what information is available in the event context, seeUsing event information. For more information about how to use conditionals, seeEvaluate expressions in workflows and actions.

Using environments to manually trigger workflow jobs

If you want to manually trigger a specific job in a workflow, you can use an environment that requires approval from a specific team or user. First, configure an environment with required reviewers. For more information, seeManaging environments for deployment. Then, reference the environment name in a job in your workflow using theenvironment: key. Any job referencing the environment will not run until at least one reviewer approves the job.

For example, the following workflow will run whenever there is a push to main. Thebuild job will always run. Thepublish job will only run after thebuild job successfully completes (due toneeds: [build]) and after all of the rules (including required reviewers) for the environment calledproduction pass (due toenvironment: production).

on:push:branches:-mainjobs:build:runs-on:ubuntu-lateststeps:-name:buildrun:|          echo 'building'publish:needs: [build]runs-on:ubuntu-latestenvironment:productionsteps:-name:publishrun:|          echo 'publishing'

Available events

For a full list of available events, seeEvents that trigger workflows.