About YAML syntax for workflows

Workflow files use YAML syntax, and must have either a.yml or.yaml file extension. If you're new to YAML and want to learn more, seeLearn YAML in Y minutes.

You must store workflow files in the.github/workflows directory of your repository.

name

The name of the workflow. GitHub displays the names of your workflows under your repository's "Actions" tab. If you omitname, GitHub displays the workflow file path relative to the root of the repository.

run-name

The name for workflow runs generated from the workflow. GitHub displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. Ifrun-name is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run. For example, for a workflow triggered by apush orpull_request event, it is set as the commit message or the title of the pull request.

This value can include expressions and can reference thegithub andinputs contexts.

Example ofrun-name

run-name:Deployto${{inputs.deploy_target}}by@${{github.actor}}

on

To automatically trigger a workflow, useon to define which events can cause the workflow to run. For a list of available events, seeEvents that trigger workflows.

You can define single or multiple events that can trigger a workflow, or set a time schedule. You can also restrict the execution of a workflow to only occur for specific files, tags, or branch changes. These options are described in the following sections.

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

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 activity types and filters with multiple events

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

For example, a workflow with the 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:

on.<event_name>.types

Useon.<event_name>.types to define the type of activity that will trigger a workflow run. Most GitHub events are triggered by more than one type of activity. For example, thelabel is triggered when a label iscreated,edited, ordeleted. Thetypes keyword enables you to narrow down activity that causes the workflow to run. When only one activity type triggers a webhook event, thetypes keyword is unnecessary.

You can use an array of eventtypes. For more information about each event and their activity types, seeEvents that trigger workflows.

on:label:types: [created,edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

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'

on.push.<branches|tags|branches-ignore|tags-ignore>

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'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

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.

on.schedule

You can useon.schedule to define a time schedule for your workflows. You can schedule a workflow to run at specific UTC times usingPOSIX 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:# * is a special character in YAML so you have to quote this string-cron:'30 5,17 * * *'

A single workflow can be triggered by multipleschedule events. You can access the schedule event that triggered the workflow through thegithub.event.schedule context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips theNot 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-lateststeps:-name:NotonMondayorWednesdayif:github.event.schedule!='30 5 * * 1,3'run:echo"This step will be skipped on Monday and Wednesday"-name:Everytimerun:echo"This step will always run"

For more information about cron syntax, seeEvents that trigger workflows.

on.workflow_call

Useon.workflow_call to define the inputs and outputs for a reusable workflow. You can also map the secrets that are available to the called workflow. For more information on reusable workflows, seeReuse workflows.

on.workflow_call.inputs

When using theworkflow_call keyword, you can optionally specify inputs that are passed to the called workflow from the caller workflow. For more information about theworkflow_call keyword, seeEvents that trigger workflows.

In addition to the standard input parameters that are available,on.workflow_call.inputs requires atype parameter. For more information, seeon.workflow_call.inputs.<input_id>.type.

If adefault parameter is not set, the default value of the input isfalse for a boolean,0 for a number, and"" for a string.

Within the called workflow, you can use theinputs context to refer to an input. For more information, seeContexts reference.

If a caller workflow passes an input that is not specified in the called workflow, this results in an error.

Example ofon.workflow_call.inputs

on:workflow_call:inputs:username:description:'A username passed from the caller workflow'default:'john-doe'required:falsetype:stringjobs:print-username:runs-on:ubuntu-lateststeps:-name:PrinttheinputnametoSTDOUTrun:echoTheusernameis${{inputs.username}}

For more information, seeReuse workflows.

on.workflow_call.inputs.<input_id>.type

Required if input is defined for theon.workflow_call keyword. The value of this parameter is a string specifying the data type of the input. This must be one of:boolean,number, orstring.

on.workflow_call.outputs

A map of outputs for a called workflow. Called workflow outputs are available to all downstream jobs in the caller workflow. Each output has an identifier, an optionaldescription, and avalue. Thevalue must be set to the value of an output from a job within the called workflow.

In the example below, two outputs are defined for this reusable workflow:workflow_output1 andworkflow_output2. These are mapped to outputs calledjob_output1 andjob_output2, both from a job calledmy_job.

Example ofon.workflow_call.outputs

on:workflow_call:# Map the workflow outputs to job outputsoutputs:workflow_output1:description:"The first job output"value:${{jobs.my_job.outputs.job_output1}}workflow_output2:description:"The second job output"value:${{jobs.my_job.outputs.job_output2}}

For information on how to reference a job output, seejobs.<job_id>.outputs. For more information, seeReuse workflows.

on.workflow_call.secrets

A map of the secrets that can be used in the called workflow.

Within the called workflow, you can use thesecrets context to refer to a secret.

If a caller workflow passes a secret that is not specified in the called workflow, this results in an error.

Example ofon.workflow_call.secrets

on:workflow_call:secrets:access-token:description:'A token passed from the caller workflow'required:falsejobs:pass-secret-to-action:runs-on:ubuntu-lateststeps:# passing the secret to an action-name:Passthereceivedsecrettoanactionuses:./.github/actions/my-actionwith:token:${{secrets.access-token}}# passing the secret to a nested reusable workflowpass-secret-to-workflow:uses:./.github/workflows/my-workflowsecrets:token:${{secrets.access-token}}

on.workflow_call.secrets.<secret_id>

A string identifier to associate with the secret.

on.workflow_call.secrets.<secret_id>.required

A boolean specifying whether the secret must be supplied.

on.workflow_run.<branches|branches-ignore>

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'

on.workflow_dispatch

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.

on.workflow_dispatch.inputs

The triggered workflow receives the inputs in theinputs context. For more information, seeContexts.

Example ofon.workflow_dispatch.inputs

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

on.workflow_dispatch.inputs.<input_id>.required

A boolean specifying whether the input must be supplied.

on.workflow_dispatch.inputs.<input_id>.type

The value of this parameter is a string specifying the data type of the input. This must be one of:boolean,choice,number,environment orstring.

permissions

You can usepermissions to modify the default permissions granted to theGITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access. For more information, seeUse GITHUB_TOKEN in workflows.

You can usepermissions either as a top-level key, to apply to all jobs in the workflow, or within specific jobs. When you add thepermissions key within a specific job, all actions and run commands within that job that use theGITHUB_TOKEN gain the access rights you specify. For more information, seejobs.<job_id>.permissions.

Owners of an organization can restrict write access for theGITHUB_TOKEN at the repository level. For more information, seeDisabling or limiting GitHub Actions for your organization.

When a workflow is triggered by thepull_request_target event, theGITHUB_TOKEN is granted read/write repository permission, even when it is triggered from a public fork. For more information, seeEvents that trigger workflows.

For each of the available permissions, shown in the table below, you can assign one of the access levels:read (if applicable),write, ornone.write includesread. If you specify the access for any of these permissions, all of those that are not specified are set tonone.

Available permissions and details of what each allows an action to do:

Defining access for theGITHUB_TOKEN scopes

You can define the access that theGITHUB_TOKEN will permit by specifyingread,write, ornone as the value of the available permissions within thepermissions key.

permissions:actions:read|write|noneattestations:read|write|nonechecks:read|write|nonecontents:read|write|nonedeployments:read|write|noneid-token:write|noneissues:read|write|nonemodels:read|nonediscussions:read|write|nonepackages:read|write|nonepages:read|write|nonepull-requests:read|write|nonesecurity-events:read|write|nonestatuses:read|write|none

If you specify the access for any of these permissions, all of those that are not specified are set tonone.

You can use the following syntax to define one ofread-all orwrite-all access for all of the available permissions:

permissions:read-all

permissions:write-all

You can use the following syntax to disable permissions for all of the available permissions:

permissions: {}

Changing the permissions in a forked repository

You can use thepermissions key to add and remove read permissions for forked repositories, but typically you can't grant write access. The exception to this behavior is where an admin user has selected theSend write tokens to workflows from pull requests option in the GitHub Actions settings. For more information, seeManaging GitHub Actions settings for a repository.

How permissions are calculated for a workflow job

The permissions for theGITHUB_TOKEN are initially set to the default setting for the enterprise, organization, or repository. If the default is set to the restricted permissions at any of these levels then this will apply to the relevant repositories. For example, if you choose the restricted default at the organization level then all repositories in that organization will use the restricted permissions as the default. The permissions are then adjusted based on any configuration within the workflow file, first at the workflow level and then at the job level. Finally, if the workflow was triggered by a pull request from a forked repository, and theSend write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read only.

Setting theGITHUB_TOKEN permissions for all jobs in a workflow

You can specifypermissions at the top level of a workflow, so that the setting applies to all jobs in the workflow.

Example: Setting theGITHUB_TOKEN permissions for an entire workflow

This example shows permissions being set for theGITHUB_TOKEN that will apply to all jobs in the workflow. All permissions are granted read access.

name:"My workflow"on: [push ]permissions:read-alljobs:...

Using thepermissions key for forked repositories

You can use thepermissions key to add and removeread permissions for forked repositories, but typically you can't grantwrite access. The exception to this behavior is where an admin user has selected theSend write tokens to workflows from pull requests option in the GitHub Actions settings. For more information, seeManaging GitHub Actions settings for a repository.

Permissions for workflow runs triggered by Dependabot

Workflow runs triggered by Dependabot pull requests run as if they are from a forked repository, and therefore use a read-onlyGITHUB_TOKEN. These workflow runs cannot access any secrets. For information about strategies to keep these workflows secure, seeSecure use reference.

env

Amap of variables that are available to the steps of all jobs in the workflow. You can also set variables that are only available to the steps of a single job or to a single step. For more information, seejobs.<job_id>.env andjobs.<job_id>.steps[*].env.

Variables in theenv map cannot be defined in terms of other variables in the map.

When more than one environment variable is defined with the same name, GitHub uses the most specific variable. For example, an environment variable defined in a step will override job and workflow environment variables with the same name, while the step executes. An environment variable defined for a job will override a workflow variable with the same name, while the job executes.

Example ofenv

env:SERVER:production

defaults

Usedefaults to create amap of default settings that will apply to all jobs in the workflow. You can also set default settings that are only available to a job. For more information, seejobs.<job_id>.defaults.

When more than one default setting is defined with the same name, GitHub uses the most specific default setting. For example, a default setting defined in a job will override a default setting that has the same name defined in a workflow.

defaults.run

You can usedefaults.run to provide defaultshell andworking-directory options for allrun steps in a workflow. You can also set default settings forrun that are only available to a job. For more information, seejobs.<job_id>.defaults.run. You cannot use contexts or expressions in this keyword.

When more than one default setting is defined with the same name, GitHub uses the most specific default setting. For example, a default setting defined in a job will override a default setting that has the same name defined in a workflow.

Example: Set the default shell and working directory

defaults:run:shell:bashworking-directory:./scripts

defaults.run.shell

Useshell to define theshell for a step. This keyword can reference several contexts. For more information, seeContexts.

When more than one default setting is defined with the same name, GitHub uses the most specific default setting. For example, a default setting defined in a job will override a default setting that has the same name defined in a workflow.

defaults.run.working-directory

Useworking-directory to define the working directory for theshell for a step. This keyword can reference several contexts. For more information, seeContexts.

concurrency

Useconcurrency to ensure that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can only usegithub,inputs andvars contexts. For more information about expressions, seeEvaluate expressions in workflows and actions.

You can also specifyconcurrency at the job level. For more information, seejobs.<job_id>.concurrency.

This means that there can be at most one running and one pending job in a concurrency group at any time. When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will bepending. Any existingpending job or workflow in the same concurrency group, if it exists, will be canceled and the new queued job or workflow will take its place.

To also cancel any currently running job or workflow in the same concurrency group, specifycancel-in-progress: true. To conditionally cancel currently running jobs or workflows in the same concurrency group, you can specifycancel-in-progress as an expression with any of the allowed expression contexts.

Example: Using concurrency and the default behavior

The default behavior of GitHub Actions is to allow multiple jobs or workflow runs to run concurrently. Theconcurrency keyword allows you to control the concurrency of workflow runs.

For example, you can use theconcurrency keyword immediately after where trigger conditions are defined to limit the concurrency of entire workflow runs for a specific branch:

on:push:branches:-mainconcurrency:group:${{github.workflow}}-${{github.ref}}cancel-in-progress:true

You can also limit the concurrency of jobs within a workflow by using theconcurrency keyword at the job level:

on:push:branches:-mainjobs:job-1:runs-on:ubuntu-latestconcurrency:group:example-groupcancel-in-progress:true

Example: Concurrency groups

Concurrency groups provide a way to manage and limit the execution of workflow runs or jobs that share the same concurrency key.

Theconcurrency key is used to group workflows or jobs together into a concurrency group. When you define aconcurrency key, GitHub Actions ensures that only one workflow or job with that key runs at any given time. If a new workflow run or job starts with the sameconcurrency key, GitHub Actions will cancel any workflow or job already running with that key. Theconcurrency key can be a hard-coded string, or it can be a dynamic expression that includes context variables.

It is possible to define concurrency conditions in your workflow so that the workflow or job is part of a concurrency group.

This means that when a workflow run or job starts, GitHub will cancel any workflow runs or jobs that are already in progress in the same concurrency group. This is useful in scenarios where you want to prevent parallel runs for a certain set of a workflows or jobs, such as the ones used for deployments to a staging environment, in order to prevent actions that could cause conflicts or consume more resources than necessary.

In this example,job-1 is part of a concurrency group namedstaging_environment. This means that if a new run ofjob-1 is triggered, any runs of the same job in thestaging_environment concurrency group that are already in progress will be cancelled.

jobs:job-1:runs-on:ubuntu-latestconcurrency:group:staging_environmentcancel-in-progress:true

Alternatively, using a dynamic expression such asconcurrency: ci-${{ github.ref }} in your workflow means that the workflow or job would be part of a concurrency group namedci- followed by the reference of the branch or tag that triggered the workflow. In this example, if a new commit is pushed to the main branch while a previous run is still in progress, the previous run will be cancelled and the new one will start:

on:push:branches:-mainconcurrency:group:ci-${{github.ref}}cancel-in-progress:true

Example: Using concurrency to cancel any in-progress job or run

To use concurrency to cancel any in-progress job or run in GitHub Actions, you can use theconcurrency key with thecancel-in-progress option set totrue:

concurrency:group:${{github.ref}}cancel-in-progress:true

Note that in this example, without defining a particular concurrency group, GitHub Actions will cancelany in-progress run of the job or workflow.

Example: Using a fallback value

If you build the group name with a property that is only defined for specific events, you can use a fallback value. For example,github.head_ref is only defined onpull_request events. If your workflow responds to other events in addition topull_request events, you will need to provide a fallback to avoid a syntax error. The following concurrency group cancels in-progress jobs or runs onpull_request events only; ifgithub.head_ref is undefined, the concurrency group will fallback to the run ID, which is guaranteed to be both unique and defined for the run.

concurrency:group:${{github.head_ref||github.run_id}}cancel-in-progress:true

Example: Only cancel in-progress jobs or runs for the current workflow

If you have multiple workflows in the same repository, concurrency group names must be unique across workflows to avoid canceling in-progress jobs or runs from other workflows. Otherwise, any previously in-progress or pending job will be canceled, regardless of the workflow.

To only cancel in-progress runs of the same workflow, you can use thegithub.workflow property to build the concurrency group:

concurrency:group:${{github.workflow}}-${{github.ref}}cancel-in-progress:true

Example: Only cancel in-progress jobs on specific branches

If you would like to cancel in-progress jobs on certain branches but not on others, you can use conditional expressions withcancel-in-progress. For example, you can do this if you would like to cancel in-progress jobs on development branches but not on release branches.

To only cancel in-progress runs of the same workflow when not running on a release branch, you can setcancel-in-progress to an expression similar to the following:

concurrency:group:${{github.workflow}}-${{github.ref}}cancel-in-progress:${{!contains(github.ref,'release/')}}

In this example, multiple pushes to arelease/1.2.3 branch would not cancel in-progress runs. Pushes to another branch, such asmain, would cancel in-progress runs.

jobs

A workflow run is made up of one or morejobs, which run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using thejobs.<job_id>.needs keyword.

Each job runs in a runner environment specified byruns-on.

You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, seeBilling and usage for GitHub-hosted runners andActions limits for self-hosted runner usage limits.

If you need to find the unique identifier of a job running in a workflow run, you can use the GitHub API. For more information, seeREST API endpoints for GitHub Actions.

jobs.<job_id>

Usejobs.<job_id> to give your job a unique identifier. The keyjob_id is a string and its value is a map of the job's configuration data. You must replace<job_id> with a string that is unique to thejobs object. The<job_id> must start with a letter or_ and contain only alphanumeric characters,-, or_.

Example: Creating jobs

In this example, two jobs have been created, and theirjob_id values aremy_first_job andmy_second_job.

jobs:my_first_job:name:Myfirstjobmy_second_job:name:Mysecondjob

jobs.<job_id>.name

Usejobs.<job_id>.name to set a name for the job, which is displayed in the GitHub UI.

jobs.<job_id>.permissions

For a specific job, you can usejobs.<job_id>.permissions to modify the default permissions granted to theGITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access. For more information, seeUse GITHUB_TOKEN in workflows.

By specifying the permission within a job definition, you can configure a different set of permissions for theGITHUB_TOKEN for each job, if required. Alternatively, you can specify the permissions for all jobs in the workflow. For information on defining permissions at the workflow level, seepermissions.

For each of the available permissions, shown in the table below, you can assign one of the access levels:read (if applicable),write, ornone.write includesread. If you specify the access for any of these permissions, all of those that are not specified are set tonone.

Available permissions and details of what each allows an action to do:

Defining access for theGITHUB_TOKEN scopes

You can define the access that theGITHUB_TOKEN will permit by specifyingread,write, ornone as the value of the available permissions within thepermissions key.

permissions:actions:read|write|noneattestations:read|write|nonechecks:read|write|nonecontents:read|write|nonedeployments:read|write|noneid-token:write|noneissues:read|write|nonemodels:read|nonediscussions:read|write|nonepackages:read|write|nonepages:read|write|nonepull-requests:read|write|nonesecurity-events:read|write|nonestatuses:read|write|none

If you specify the access for any of these permissions, all of those that are not specified are set tonone.

You can use the following syntax to define one ofread-all orwrite-all access for all of the available permissions:

permissions:read-all

permissions:write-all

You can use the following syntax to disable permissions for all of the available permissions:

permissions: {}

Changing the permissions in a forked repository

You can use thepermissions key to add and remove read permissions for forked repositories, but typically you can't grant write access. The exception to this behavior is where an admin user has selected theSend write tokens to workflows from pull requests option in the GitHub Actions settings. For more information, seeManaging GitHub Actions settings for a repository.

Example: Setting theGITHUB_TOKEN permissions for one job in a workflow

This example shows permissions being set for theGITHUB_TOKEN that will only apply to the job namedstale. Write access is granted for theissues andpull-requests permissions. All other permissions will have no access.

jobs:stale:runs-on:ubuntu-latestpermissions:issues:writepull-requests:writesteps:-uses:actions/stale@v9

jobs.<job_id>.needs

Usejobs.<job_id>.needs to identify any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails or is skipped, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue. If a run contains a series of jobs that need each other, a failure or skip applies to all jobs in the dependency chain from the point of failure or skip onwards. If you would like a job to run even if a job it is dependent on did not succeed, use thealways() conditional expression injobs.<job_id>.if.

Example: Requiring successful dependent jobs

jobs:job1:job2:needs:job1job3:needs: [job1,job2]

In this example,job1 must complete successfully beforejob2 begins, andjob3 waits for bothjob1 andjob2 to complete.

The jobs in this example run sequentially:

1. job1
2. job2
3. job3

Example: Not requiring successful dependent jobs

jobs:job1:job2:needs:job1job3:if:${{always()}}needs: [job1,job2]

In this example,job3 uses thealways() conditional expression so that it always runs afterjob1 andjob2 have completed, regardless of whether they were successful. For more information, seeEvaluate expressions in workflows and actions.

jobs.<job_id>.if

You can use thejobs.<job_id>.if conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional. For more information on which contexts are supported in this key, seeContexts reference.

When you use expressions in anif conditional, you can, optionally, omit the${{ }} expression syntax because GitHub Actions automatically evaluates theif conditional as an expression. However, this exception does not apply everywhere.

You must always use the${{ }} expression syntax or escape with'',"", or() when the expression starts with!, since! is reserved notation in YAML format. For example:

if:${{!startsWith(github.ref,'refs/tags/')}}

For more information, seeEvaluate expressions in workflows and actions.

Example: Only run job for specific repository

This example usesif to control when theproduction-deploy job can run. It will only run if the repository is namedocto-repo-prod and is within theocto-org organization. Otherwise, the job will be marked asskipped.

name: example-workflowon: [push]jobs:  production-deploy:    if: github.repository == 'octo-org/octo-repo-prod'    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: actions/setup-node@v4        with:          node-version: '14'      - run: npm install -g bats

name:example-workflowon: [push]jobs:production-deploy:if:github.repository=='octo-org/octo-repo-prod'runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-uses:actions/setup-node@v4with:node-version:'14'-run:npminstall-gbats

jobs.<job_id>.runs-on

Usejobs.<job_id>.runs-on to define the type of machine to run the job on.

• The destination machine can be either aGitHub-hosted runner,larger runner, or aself-hosted runner.

• You can target runners based on the labels assigned to them, or their group membership, or a combination of these.

• You can provideruns-on as:

  • A single string
  • A single variable containing a string
  • An array of strings, variables containing strings, or a combination of both
  • Akey: value pair using thegroup orlabels keys

• If you specify an array of strings or variables, your workflow will execute on any runner that matches all of the specifiedruns-on values. For example, here the job will only run on a self-hosted runner that has the labelslinux,x64, andgpu:

  runs-on: [self-hosted,linux,x64,gpu]

  For more information, seeChoosing self-hosted runners.

• You can mix strings and variables in an array. For example:

  on:workflow_dispatch:inputs:chosen-os:required:truetype:choiceoptions:-Ubuntu-macOSjobs:test:runs-on: [self-hosted,"${{ inputs.chosen-os }}"]steps:-run:echoHelloworld!

• If you would like to run your workflow on multiple machines, usejobs.<job_id>.strategy.

Choosing GitHub-hosted runners

If you use a GitHub-hosted runner, each job runs in a fresh instance of a runner image specified byruns-on.

The value for runs-on, when you are using a GitHub-hosted runner, is a runner label or the name of a runner group. The labels for the standard GitHub-hosted runners are shown in the following tables.

For more information, seeAbout GitHub-hosted runners.

Standard GitHub-hosted runners for public repositories

For public repositories, jobs using the workflow labels shown in the table below will run on virtual machines with the associated specifications. The use of these runners on public repositories is free and unlimited.

Standard GitHub-hosted runners for private repositories

For private repositories, jobs using the workflow labels shown in the table below will run on virtual machines with the associated specifications. These runners use your GitHub account's allotment of free minutes, and are then charged at the per minute rates. For more information, seeAbout billing for GitHub Actions.

In addition to the standard GitHub-hosted runners, GitHub offers customers on GitHub Team and GitHub Enterprise Cloud plans a range of managed virtual machines with advanced features - for example, more cores and disk space, GPU-powered machines, and ARM-powered machines. For more information, seeAbout larger runners.

Example: Specifying an operating system

runs-on:ubuntu-latest

For more information, seeAbout GitHub-hosted runners.

Choosing self-hosted runners

To specify a self-hosted runner for your job, configureruns-on in your workflow file with self-hosted runner labels.

Self-hosted runners may have theself-hosted label. When setting up a self-hosted runner, by default we will include the labelself-hosted. You may pass in the--no-default-labels flag to prevent the self-hosted label from being applied. Labels can be used to create targeting options for runners, such as operating system or architecture, we recommend providing an array of labels that begins withself-hosted (this must be listed first) and then includes additional labels as needed. When you specify an array of labels, jobs will be queued on runners that have all the labels that you specify.

Note that Actions Runner Controller does not support multiple labels and does not support theself-hosted label.

Example: Using labels for runner selection

runs-on: [self-hosted,linux]

For more information, seeAbout self-hosted runners andUsing self-hosted runners in a workflow.

Choosing runners in a group

You can useruns-on to target runner groups, so that the job will execute on any runner that is a member of that group. For more granular control, you can also combine runner groups with labels.

Runner groups can only havelarger runners orself-hosted runners as members.

Example: Using groups to control where jobs are run

In this example, Ubuntu runners have been added to a group calledubuntu-runners. Theruns-on key sends the job to any available runner in theubuntu-runners group:

name:learn-github-actionson: [push]jobs:check-bats-version:runs-on:group:ubuntu-runnerssteps:-uses:actions/checkout@v4-uses:actions/setup-node@v4with:node-version:'14'-run:npminstall-gbats-run:bats-v

Example: Combining groups and labels

When you combine groups and labels, the runner must meet both requirements to be eligible to run the job.

In this example, a runner group calledubuntu-runners is populated with Ubuntu runners, which have also been assigned the labelubuntu-20.04-16core. Theruns-on key combinesgroup andlabels so that the job is routed to any available runner within the group that also has a matching label:

name:learn-github-actionson: [push]jobs:check-bats-version:runs-on:group:ubuntu-runnerslabels:ubuntu-20.04-16coresteps:-uses:actions/checkout@v4-uses:actions/setup-node@v4with:node-version:'14'-run:npminstall-gbats-run:bats-v

jobs.<job_id>.environment

Usejobs.<job_id>.environment to define the environment that the job references.

You can provide the environment as only the environmentname, or as an environment object with thename andurl. The URL maps toenvironment_url in the deployments API. For more information about the deployments API, seeREST API endpoints for repositories.

Example: Using a single environment name

environment:staging_environment

Example: Using environment name and URL

environment:name:production_environmenturl:https://github.com

The value ofurl can be an expression. Allowed expression contexts:github,inputs,vars,needs,strategy,matrix,job,runner,env, andsteps. For more information about expressions, seeEvaluate expressions in workflows and actions.

Example: Using output as URL

environment:name:production_environmenturl:${{steps.step_id.outputs.url_output}}

The value ofname can be an expression. Allowed expression contexts:github,inputs,vars,needs,strategy, andmatrix. For more information about expressions, seeEvaluate expressions in workflows and actions.

Example: Using an expression as environment name

environment:name:${{github.ref_name}}

jobs.<job_id>.concurrency

You can usejobs.<job_id>.concurrency to ensure that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. Allowed expression contexts:github,inputs,vars,needs,strategy, andmatrix. For more information about expressions, seeEvaluate expressions in workflows and actions.

You can also specifyconcurrency at the workflow level. For more information, seeconcurrency.

This means that there can be at most one running and one pending job in a concurrency group at any time. When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will bepending. Any existingpending job or workflow in the same concurrency group, if it exists, will be canceled and the new queued job or workflow will take its place.

To also cancel any currently running job or workflow in the same concurrency group, specifycancel-in-progress: true. To conditionally cancel currently running jobs or workflows in the same concurrency group, you can specifycancel-in-progress as an expression with any of the allowed expression contexts.

Example: Using concurrency and the default behavior

The default behavior of GitHub Actions is to allow multiple jobs or workflow runs to run concurrently. Theconcurrency keyword allows you to control the concurrency of workflow runs.

For example, you can use theconcurrency keyword immediately after where trigger conditions are defined to limit the concurrency of entire workflow runs for a specific branch:

on:push:branches:-mainconcurrency:group:${{github.workflow}}-${{github.ref}}cancel-in-progress:true

You can also limit the concurrency of jobs within a workflow by using theconcurrency keyword at the job level:

on:push:branches:-mainjobs:job-1:runs-on:ubuntu-latestconcurrency:group:example-groupcancel-in-progress:true

Example: Concurrency groups

Concurrency groups provide a way to manage and limit the execution of workflow runs or jobs that share the same concurrency key.

Theconcurrency key is used to group workflows or jobs together into a concurrency group. When you define aconcurrency key, GitHub Actions ensures that only one workflow or job with that key runs at any given time. If a new workflow run or job starts with the sameconcurrency key, GitHub Actions will cancel any workflow or job already running with that key. Theconcurrency key can be a hard-coded string, or it can be a dynamic expression that includes context variables.

It is possible to define concurrency conditions in your workflow so that the workflow or job is part of a concurrency group.

This means that when a workflow run or job starts, GitHub will cancel any workflow runs or jobs that are already in progress in the same concurrency group. This is useful in scenarios where you want to prevent parallel runs for a certain set of a workflows or jobs, such as the ones used for deployments to a staging environment, in order to prevent actions that could cause conflicts or consume more resources than necessary.

In this example,job-1 is part of a concurrency group namedstaging_environment. This means that if a new run ofjob-1 is triggered, any runs of the same job in thestaging_environment concurrency group that are already in progress will be cancelled.

jobs:job-1:runs-on:ubuntu-latestconcurrency:group:staging_environmentcancel-in-progress:true

Alternatively, using a dynamic expression such asconcurrency: ci-${{ github.ref }} in your workflow means that the workflow or job would be part of a concurrency group namedci- followed by the reference of the branch or tag that triggered the workflow. In this example, if a new commit is pushed to the main branch while a previous run is still in progress, the previous run will be cancelled and the new one will start:

on:push:branches:-mainconcurrency:group:ci-${{github.ref}}cancel-in-progress:true

Example: Using concurrency to cancel any in-progress job or run

To use concurrency to cancel any in-progress job or run in GitHub Actions, you can use theconcurrency key with thecancel-in-progress option set totrue:

concurrency:group:${{github.ref}}cancel-in-progress:true

Note that in this example, without defining a particular concurrency group, GitHub Actions will cancelany in-progress run of the job or workflow.

Example: Using a fallback value

If you build the group name with a property that is only defined for specific events, you can use a fallback value. For example,github.head_ref is only defined onpull_request events. If your workflow responds to other events in addition topull_request events, you will need to provide a fallback to avoid a syntax error. The following concurrency group cancels in-progress jobs or runs onpull_request events only; ifgithub.head_ref is undefined, the concurrency group will fallback to the run ID, which is guaranteed to be both unique and defined for the run.

concurrency:group:${{github.head_ref||github.run_id}}cancel-in-progress:true

Example: Only cancel in-progress jobs or runs for the current workflow

If you have multiple workflows in the same repository, concurrency group names must be unique across workflows to avoid canceling in-progress jobs or runs from other workflows. Otherwise, any previously in-progress or pending job will be canceled, regardless of the workflow.

To only cancel in-progress runs of the same workflow, you can use thegithub.workflow property to build the concurrency group:

concurrency:group:${{github.workflow}}-${{github.ref}}cancel-in-progress:true

Example: Only cancel in-progress jobs on specific branches

If you would like to cancel in-progress jobs on certain branches but not on others, you can use conditional expressions withcancel-in-progress. For example, you can do this if you would like to cancel in-progress jobs on development branches but not on release branches.

To only cancel in-progress runs of the same workflow when not running on a release branch, you can setcancel-in-progress to an expression similar to the following:

concurrency:group:${{github.workflow}}-${{github.ref}}cancel-in-progress:${{!contains(github.ref,'release/')}}

In this example, multiple pushes to arelease/1.2.3 branch would not cancel in-progress runs. Pushes to another branch, such asmain, would cancel in-progress runs.

jobs.<job_id>.outputs

You can usejobs.<job_id>.outputs to create amap of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, seejobs.<job_id>.needs.

Outputs can be a maximum of 1 MB per job. The total of all outputs in a workflow run can be a maximum of 50 MB. Size is approximated based on UTF-16 encoding.

Job outputs containing expressions are evaluated on the runner at the end of each job. Outputs containing secrets are redacted on the runner and not sent to GitHub Actions.

If an output is skipped because it may contain a secret, you will see the following warning message: "Skip output{output.Key} since it may contain secret." For more information on how to handle secrets, please refer to theExample: Masking and passing a secret between jobs or workflows.

To use job outputs in a dependent job, you can use theneeds context. For more information, seeContexts reference.

Example: Defining outputs for a job

jobs:job1:runs-on:ubuntu-latest# Map a step output to a job outputoutputs:output1:${{steps.step1.outputs.test}}output2:${{steps.step2.outputs.test}}steps:-id:step1run:echo"test=hello">>"$GITHUB_OUTPUT"-id:step2run:echo"test=world">>"$GITHUB_OUTPUT"job2:runs-on:ubuntu-latestneeds:job1steps:-env:OUTPUT1:${{needs.job1.outputs.output1}}OUTPUT2:${{needs.job1.outputs.output2}}run:echo"$OUTPUT1 $OUTPUT2"

Using Job Outputs in a Matrix Job

Matrices can be used to generate multiple outputs of different names. When using a matrix, job outputs will be combined from all jobs inside the matrix.

jobs:job1:runs-on:ubuntu-latestoutputs:output_1:${{steps.gen_output.outputs.output_1}}output_2:${{steps.gen_output.outputs.output_2}}output_3:${{steps.gen_output.outputs.output_3}}strategy:matrix:version: [1,2,3]steps:-name:Generateoutputid:gen_outputrun:|          version="${{ matrix.version }}"          echo "output_${version}=${version}" >> "$GITHUB_OUTPUT"job2:runs-on:ubuntu-latestneeds: [job1]steps:# Will show# {#   "output_1": "1",#   "output_2": "2",#   "output_3": "3"# }-run:echo'${{ toJSON(needs.job1.outputs) }}'

jobs.<job_id>.env

Amap of variables that are available to all steps in the job. You can set variables for the entire workflow or an individual step. For more information, seeenv andjobs.<job_id>.steps[*].env.

When more than one environment variable is defined with the same name, GitHub uses the most specific variable. For example, an environment variable defined in a step will override job and workflow environment variables with the same name, while the step executes. An environment variable defined for a job will override a workflow variable with the same name, while the job executes.

Example ofjobs.<job_id>.env

jobs:job1:env:FIRST_NAME:Mona

jobs.<job_id>.defaults

Usejobs.<job_id>.defaults to create amap of default settings that will apply to all steps in the job. You can also set default settings for the entire workflow. For more information, seedefaults.

When more than one default setting is defined with the same name, GitHub uses the most specific default setting. For example, a default setting defined in a job will override a default setting that has the same name defined in a workflow.

jobs.<job_id>.defaults.run

Usejobs.<job_id>.defaults.run to provide defaultshell andworking-directory to allrun steps in the job.

You can provide defaultshell andworking-directory options for allrun steps in a job. You can also set default settings forrun for the entire workflow. For more information, seedefaults.run.

These can be overridden at thejobs.<job_id>.defaults.run andjobs.<job_id>.steps[*].run levels.

When more than one default setting is defined with the same name, GitHub uses the most specific default setting. For example, a default setting defined in a job will override a default setting that has the same name defined in a workflow.

jobs.<job_id>.defaults.run.shell

Useshell to define theshell for a step. This keyword can reference several contexts. For more information, seeContexts.

When more than one default setting is defined with the same name, GitHub uses the most specific default setting. For example, a default setting defined in a job will override a default setting that has the same name defined in a workflow.

jobs.<job_id>.defaults.run.working-directory

Useworking-directory to define the working directory for theshell for a step. This keyword can reference several contexts. For more information, seeContexts.

Example: Setting defaultrun step options for a job

jobs:job1:runs-on:ubuntu-latestdefaults:run:shell:bashworking-directory:./scripts

jobs.<job_id>.steps

A job contains a sequence of tasks calledsteps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

GitHub only displays the first 1,000 checks, however, you can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, seeBilling and usage for GitHub-hosted runners andActions limits for self-hosted runner usage limits.

Example ofjobs.<job_id>.steps

name:GreetingfromMonaon:pushjobs:my-job:name:MyJobruns-on:ubuntu-lateststeps:-name:Printagreetingenv:MY_VAR:Hithere!MynameisFIRST_NAME:MonaMIDDLE_NAME:TheLAST_NAME:Octocatrun:|          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

A unique identifier for the step. You can use theid to reference the step in contexts. For more information, seeContexts reference.

jobs.<job_id>.steps[*].if

You can use theif conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional. For more information on which contexts are supported in this key, seeContexts reference.

When you use expressions in anif conditional, you can, optionally, omit the${{ }} expression syntax because GitHub Actions automatically evaluates theif conditional as an expression. However, this exception does not apply everywhere.

You must always use the${{ }} expression syntax or escape with'',"", or() when the expression starts with!, since! is reserved notation in YAML format. For example:

if:${{!startsWith(github.ref,'refs/tags/')}}

For more information, seeEvaluate expressions in workflows and actions.

Example: Using contexts

This step only runs when the event type is apull_request and the event action isunassigned.

steps:-name:Myfirststepif:${{github.event_name=='pull_request'&&github.event.action=='unassigned'}}run:echoThiseventisapullrequestthathadanassigneeremoved.

Example: Using status check functions

Themy backup step only runs when the previous step of a job fails. For more information, seeEvaluate expressions in workflows and actions.

steps:-name:Myfirststepuses:octo-org/action-name@main-name:Mybackupstepif:${{failure()}}uses:actions/heroku@1.0.0

Example: Using secrets

Secrets cannot be directly referenced inif: conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.

If a secret has not been set, the return value of an expression referencing the secret (such as${{ secrets.SuperSecret }} in the example) will be an empty string.

name:Runastepifasecrethasbeenseton:pushjobs:my-jobname:runs-on:ubuntu-latestenv:super_secret:${{secrets.SuperSecret}}steps:-if:${{env.super_secret!=''}}run:echo'This step will only run if the secret has a value set.'-if:${{env.super_secret==''}}run:echo'This step will only run if the secret does not have a value set.'

For more information, seeContexts reference andUsing secrets in GitHub Actions.

jobs.<job_id>.steps[*].name

A name for your step to display on GitHub.

jobs.<job_id>.steps[*].uses

Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in apublished Docker container image.

We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.

• Using the commit SHA of a released action version is the safest for stability and security.
• If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author.
• Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

Some actions require inputs that you must set using thewith keyword. Review the action's README file to determine the inputs required.

Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, seeruns-on.

Example: Using versioned actions

steps:# Reference a specific commit-uses:actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3# Reference the major version of a release-uses:actions/checkout@v4# Reference a specific version-uses:actions/checkout@v4.2.0# Reference a branch-uses:actions/checkout@main

Example: Using a public action

{owner}/{repo}@{ref}

You can specify a branch, ref, or SHA in a public GitHub repository.

jobs:my_first_job:steps:-name:Myfirststep# Uses the default branch of a public repositoryuses:actions/heroku@main-name:Mysecondstep# Uses a specific version tag of a public repositoryuses:actions/aws@v2.0.1

Example: Using a public action in a subdirectory

{owner}/{repo}/{path}@{ref}

A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.

jobs:my_first_job:steps:-name:Myfirststepuses:actions/aws/ec2@main

Example: Using an action in the same repository as the workflow

./path/to/dir

The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.

Example repository file structure:

|-- hello-world (repository)|   |__ .github|       └── workflows|           └── my-first-workflow.yml|       └── actions|           |__ hello-world-action|               └── action.yml

The path is relative (./) to the default working directory (github.workspace,$GITHUB_WORKSPACE). If the action checks out the repository to a location different than the workflow, the relative path used for local actions must be updated.

Example workflow file:

jobs:my_first_job:runs-on:ubuntu-lateststeps:# This step checks out a copy of your repository.-name:Myfirststep-checkoutrepositoryuses:actions/checkout@v4# This step references the directory that contains the action.-name:Uselocalhello-world-actionuses:./.github/actions/hello-world-action

Example: Using a Docker Hub action

docker://{image}:{tag}

A Docker image published onDocker Hub.

jobs:my_first_job:steps:-name:Myfirststepuses:docker://alpine:3.8

Example: Using the GitHub Packages Container registry

docker://{host}/{image}:{tag}

A public Docker image in the GitHub Packages Container registry.

jobs:my_first_job:steps:-name:Myfirststepuses:docker://ghcr.io/OWNER/IMAGE_NAME

Example: Using a Docker public registry action

docker://{host}/{image}:{tag}

A Docker image in a public registry. This example uses the Google Container Registry atgcr.io.

jobs:my_first_job:steps:-name:Myfirststepuses:docker://gcr.io/cloud-builders/gradle

Example: Using an action inside a different private repository than the workflow

Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as a secret. For more information, seeManaging your personal access tokens andUsing secrets in GitHub Actions.

ReplacePERSONAL_ACCESS_TOKEN in the example with the name of your secret.

jobs:my_first_job:steps:-name:Checkoutrepositoryuses:actions/checkout@v4with:repository:octocat/my-private-reporef:v1.0token:${{secrets.PERSONAL_ACCESS_TOKEN}}path:./.github/actions/my-private-repo-name:Runmyactionuses:./.github/actions/my-private-repo/my-action

Alternatively, use a GitHub App instead of a personal access token in order to ensure your workflow continues to run even if the personal access token owner leaves. For more information, seeMaking authenticated API requests with a GitHub App in a GitHub Actions workflow.

jobs.<job_id>.steps[*].run

Runs command-line programs that do not exceed 21,000 characters using the operating system's shell. If you do not provide aname, the step name will default to the text specified in therun command.

Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, seejobs.<job_id>.steps[*].shell.

Eachrun keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example:

• A single-line command:

  -name:InstallDependenciesrun:npminstall

• A multi-line command:

  -name:Cleaninstalldependenciesandbuildrun:|    npm ci    npm run build

jobs.<job_id>.steps[*].working-directory

Using theworking-directory keyword, you can specify the working directory of where to run the command.

-name:Cleantempdirectoryrun:rm-rf*working-directory:./temp

Alternatively, you can specify a default working directory for allrun steps in a job, or for allrun steps in the entire workflow. For more information, seedefaults.run.working-directory andjobs.<job_id>.defaults.run.working-directory.

You can also use arun step to run a script. For more information, seeAdding scripts to your workflow.

jobs.<job_id>.steps[*].shell

You can override the default shell settings in the runner's operating system and the job's default using theshell keyword. You can use built-inshell keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in therun keyword.

Alternatively, you can specify a default shell for allrun steps in a job, or for allrun steps in the entire workflow. For more information, seedefaults.run.shell andjobs.<job_id>.defaults.run.shell.

Example: Running a command using Bash

steps:-name:Displaythepathshell:bashrun:echo$PATH

Example: Running a command using Windowscmd

steps:-name:Displaythepathshell:cmdrun:echo%PATH%

Example: Running a command using PowerShell Core

steps:-name:Displaythepathshell:pwshrun:echo${env:PATH}

Example: Using PowerShell Desktop to run a command

steps:-name:Displaythepathshell:powershellrun:echo${env:PATH}

Example: Running an inline Python script

steps:-name:Displaythepathshell:pythonrun:|      import os      print(os.environ['PATH'])

Custom shell

You can set theshell value to a template string usingcommand [options] {0} [more_options]. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at{0}.

For example:

steps:-name:Displaytheenvironmentvariablesandtheirvaluesshell:perl {0}run:|      print %ENV

The command used,perl in this example, must be installed on the runner.

For information about the software included on GitHub-hosted runners, seeAbout GitHub-hosted runners.

Exit codes and error action preference

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

• bash/sh:

  • By default, fail-fast behavior is enforced usingset -e for bothsh andbash. Whenshell: bash is specified,-o pipefail is also applied to enforce early exit from pipelines that generate a non-zero exit status.
  • You can take full control over shell parameters by providing a template string to the shell options. For example,bash {0}.
  • sh-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code.

• powershell/pwsh

  • Fail-fast behavior when possible. Forpwsh andpowershell built-in shell, we will prepend$ErrorActionPreference = 'stop' to script contents.
  • We appendif ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } to powershell scripts so action statuses reflect the script's last exit code.
  • Users can always opt out by not using the built-in shell, and providing a custom shell option like:pwsh -File {0}, orpowershell -Command "& '{0}'", depending on need.

• cmd

  • There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
  • cmd.exe will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previoussh andpwsh default behavior and is thecmd.exe default, so this behavior remains intact.

jobs.<job_id>.steps[*].with

Amap of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed withINPUT_ and converted to upper case.

Input parameters defined for a Docker container must useargs. For more information, seejobs.<job_id>.steps[*].with.args.

Example ofjobs.<job_id>.steps[*].with

Defines the three input parameters (first_name,middle_name, andlast_name) defined by thehello_world action. These input variables will be accessible to thehello-world action asINPUT_FIRST_NAME,INPUT_MIDDLE_NAME, andINPUT_LAST_NAME environment variables.

jobs:my_first_job:steps:-name:Myfirststepuses:actions/hello_world@mainwith:first_name:Monamiddle_name:Thelast_name:Octocat

jobs.<job_id>.steps[*].with.args

Astring that defines the inputs for a Docker container. GitHub passes theargs to the container'sENTRYPOINT when the container starts up. Anarray of strings is not supported by this parameter. A single argument that includes spaces should be surrounded by double quotes"".

Example ofjobs.<job_id>.steps[*].with.args

steps:-name:Explainwhythisjobranuses:octo-org/action-name@mainwith:entrypoint:/bin/echoargs:The${{github.event_name}}eventtriggeredthisstep.

Theargs are used in place of theCMD instruction in aDockerfile. If you useCMD in yourDockerfile, use the guidelines ordered by preference:

1. Document required arguments in the action's README and omit them from theCMD instruction.
2. Use defaults that allow using the action without specifying anyargs.
3. If the action exposes a--help flag, or something similar, use that as the default to make your action self-documenting.

jobs.<job_id>.steps[*].with.entrypoint

Overrides the DockerENTRYPOINT in theDockerfile, or sets it if one wasn't already specified. Unlike the DockerENTRYPOINT instruction which has a shell and exec form,entrypoint keyword accepts only a single string defining the executable to be run.

Example ofjobs.<job_id>.steps[*].with.entrypoint

steps:-name:Runacustomcommanduses:octo-org/action-name@mainwith:entrypoint:/a/different/executable

Theentrypoint keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

jobs.<job_id>.steps[*].env

Sets variables for steps to use in the runner environment. You can also set variables for the entire workflow or a job. For more information, seeenv andjobs.<job_id>.env.

When more than one environment variable is defined with the same name, GitHub uses the most specific variable. For example, an environment variable defined in a step will override job and workflow environment variables with the same name, while the step executes. An environment variable defined for a job will override a workflow variable with the same name, while the job executes.

Public actions may specify expected variables in the README file. If you are setting a secret or sensitive value, such as a password or token, you must set secrets using thesecrets context. For more information, seeContexts reference.

Example ofjobs.<job_id>.steps[*].env

steps:-name:Myfirstactionenv:GITHUB_TOKEN:${{secrets.GITHUB_TOKEN}}FIRST_NAME:MonaLAST_NAME:Octocat

jobs.<job_id>.steps[*].continue-on-error

Prevents a job from failing when a step fails. Set totrue to allow a job to pass when this step fails.

jobs.<job_id>.steps[*].timeout-minutes

The maximum number of minutes to run the step before killing the process.

Fractional values are not supported.timeout-minutes must be a positive integer.

jobs.<job_id>.timeout-minutes

The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360

If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, seeBilling and usage for GitHub-hosted runners andActions limits for self-hosted runner usage limits.

jobs.<job_id>.strategy

Usejobs.<job_id>.strategy to use a matrix strategy for your jobs. A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based on the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems. For more information, seeRunning variations of jobs in a workflow.

jobs.<job_id>.strategy.matrix

Usejobs.<job_id>.strategy.matrix to define a matrix of different job configurations. For more information, seeRunning variations of jobs in a workflow.

A matrix will generate a maximum of 256 jobs per workflow run. This limit applies to both GitHub-hosted and self-hosted runners.

The variables that you define become properties in thematrix context, and you can reference the property in other areas of your workflow file. In this example, you can usematrix.version andmatrix.os to access the current value ofversion andos that the job is using. For more information, seeContexts reference.

By default, GitHub will maximize the number of jobs run in parallel depending on runner availability. The order of the variables in the matrix determines the order in which the jobs are created. The first variable you define will be the first job that is created in your workflow run.

Using a single-dimension matrix

The following workflow defines the variableversion with the values[10, 12, 14]. The workflow will run three jobs, one for each value in the variable. Each job will access theversion value through thematrix.version context and pass the value asnode-version to theactions/setup-node action.

jobs:example_matrix:strategy:matrix:version: [10,12,14]steps:-uses:actions/setup-node@v4with:node-version:${{matrix.version}}

Using a multi-dimensional matrix

Specify multiple variables to create a multi-dimensional matrix. A job will run for each possible combination of the variables.

For example, the following workflow specifies two variables:

• Two operating systems specified in theos variable
• Three Node.js versions specified in theversion variable

The workflow will run six jobs, one for each combination of theos andversion variables. Each job will set theruns-on value to the currentos value and will pass the currentversion value to theactions/setup-node action.

jobs:example_matrix:strategy:matrix:os: [ubuntu-22.04,ubuntu-20.04]version: [10,12,14]runs-on:${{matrix.os}}steps:-uses:actions/setup-node@v4with:node-version:${{matrix.version}}

A variable configuration in a matrix can be anarray ofobjects. For example, the following matrix produces 4 jobs with corresponding contexts.

matrix:os:-ubuntu-latest-macos-latestnode:-version:14-version:20env:NODE_OPTIONS=--openssl-legacy-provider

Each job in the matrix will have its own combination ofos andnode values, as shown below.

-matrix.os:ubuntu-latestmatrix.node.version:14-matrix.os:ubuntu-latestmatrix.node.version:20matrix.node.env:NODE_OPTIONS=--openssl-legacy-provider-matrix.os:macos-latestmatrix.node.version:14-matrix.os:macos-latestmatrix.node.version:20matrix.node.env:NODE_OPTIONS=--openssl-legacy-provider

jobs.<job_id>.strategy.matrix.include

For each object in theinclude list, the key:value pairs in the object will be added to each of the matrix combinations if none of the key:value pairs overwrite any of the original matrix values. If the object cannot be added to any of the matrix combinations, a new matrix combination will be created instead. Note that the original matrix values will not be overwritten, but added matrix values can be overwritten.

Example: Expanding configurations

For example, the following workflow will run four jobs, one for each combination ofos andnode. When the job for theos value ofwindows-latest andnode value of16 runs, an additional variable callednpm with the value of6 will be included in the job.

jobs:example_matrix:strategy:matrix:os: [windows-latest,ubuntu-latest]node: [14,16]include:-os:windows-latestnode:16npm:6runs-on:${{matrix.os}}steps:-uses:actions/setup-node@v4with:node-version:${{matrix.node}}-if:${{matrix.npm}}run:npminstall-gnpm@${{matrix.npm}}-run:npm--version

Example: Adding configurations

For example, this matrix will run 10 jobs, one for each combination ofos andversion in the matrix, plus a job for theos value ofwindows-latest andversion value of17.

jobs:example_matrix:strategy:matrix:os: [macos-latest,windows-latest,ubuntu-latest]version: [12,14,16]include:-os:windows-latestversion:17

If you don't specify any matrix variables, all configurations underinclude will run. For example, the following workflow would run two jobs, one for eachinclude entry. This lets you take advantage of the matrix strategy without having a fully populated matrix.

jobs:includes_only:runs-on:ubuntu-lateststrategy:matrix:include:-site:"production"datacenter:"site-a"-site:"staging"datacenter:"site-b"

jobs.<job_id>.strategy.matrix.exclude

An excluded configuration only has to be a partial match for it to be excluded.

Allinclude combinations are processed afterexclude. This allows you to useinclude to add back combinations that were previously excluded.

jobs.<job_id>.strategy.fail-fast

jobs.<job_id>.strategy.fail-fast applies to the entire matrix. Ifjobs.<job_id>.strategy.fail-fast is set totrue or its expression evaluates totrue, GitHub will cancel all in-progress and queued jobs in the matrix if any job in the matrix fails. This property defaults totrue.

You can control how job failures are handled withjobs.<job_id>.strategy.fail-fast andjobs.<job_id>.continue-on-error.

jobs.<job_id>.strategy.fail-fast applies to the entire matrix. Ifjobs.<job_id>.strategy.fail-fast is set totrue or its expression evaluates totrue, GitHub will cancel all in-progress and queued jobs in the matrix if any job in the matrix fails. This property defaults totrue.

jobs.<job_id>.continue-on-error applies to a single job. Ifjobs.<job_id>.continue-on-error istrue, other jobs in the matrix will continue running even if the job withjobs.<job_id>.continue-on-error: true fails.

You can usejobs.<job_id>.strategy.fail-fast andjobs.<job_id>.continue-on-error together. For example, the following workflow will start four jobs. For each job,continue-on-error is determined by the value ofmatrix.experimental. If any of the jobs withcontinue-on-error: false fail, all jobs that are in progress or queued will be cancelled. If the job withcontinue-on-error: true fails, the other jobs will not be affected.

jobs:test:runs-on:ubuntu-latestcontinue-on-error:${{matrix.experimental}}strategy:fail-fast:truematrix:version: [6,7,8]experimental: [false]include:-version:9experimental:true

jobs.<job_id>.strategy.max-parallel

By default, GitHub will maximize the number of jobs run in parallel depending on runner availability.

jobs.<job_id>.continue-on-error

jobs.<job_id>.continue-on-error applies to a single job. Ifjobs.<job_id>.continue-on-error istrue, other jobs in the matrix will continue running even if the job withjobs.<job_id>.continue-on-error: true fails.

Prevents a workflow run from failing when a job fails. Set totrue to allow a workflow run to pass when this job fails.

Example: Preventing a specific failing matrix job from failing a workflow run

You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job withnode set to15 to fail without failing the workflow run.

runs-on:${{matrix.os}}continue-on-error:${{matrix.experimental}}strategy:fail-fast:falsematrix:node: [13,14]os: [macos-latest,ubuntu-latest]experimental: [false]include:-node:15os:ubuntu-latestexperimental:true

jobs.<job_id>.container

Usejobs.<job_id>.container to create a container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts.

If you do not set acontainer, all steps will run directly on the host specified byruns-on unless a step refers to an action configured to run in a container.

Example: Running a job within a container

name: CIon:  push:    branches: [ main ]jobs:  container-test-job:    runs-on: ubuntu-latest    container:      image: node:18      env:        NODE_ENV: development      ports:        - 80      volumes:        - my_docker_volume:/volume_mount      options: --cpus 1    steps:      - name: Check for dockerenv file        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

name:CIon:push:branches: [main ]jobs:container-test-job:runs-on:ubuntu-latestcontainer:image:node:18env:NODE_ENV:developmentports:-80volumes:-my_docker_volume:/volume_mountoptions:--cpus1steps:-name:Checkfordockerenvfilerun:(ls/.dockerenv&&echoFounddockerenv)||(echoNodockerenv)

When you only specify a container image, you can omit theimage keyword.

jobs:container-test-job:runs-on:ubuntu-latestcontainer:node:18

jobs.<job_id>.container.image

Usejobs.<job_id>.container.image to define the Docker image to use as the container to run the action. The value can be the Docker Hub image name or a registry name.

jobs.<job_id>.container.credentials

If the image's container registry requires authentication to pull the image, you can usejobs.<job_id>.container.credentials to set amap of theusername andpassword. The credentials are the same values that you would provide to thedocker login command.

Example: Defining credentials for a container registry

container:image:ghcr.io/owner/imagecredentials:username:${{github.actor}}password:${{secrets.github_token}}

jobs.<job_id>.container.env

Usejobs.<job_id>.container.env to set amap of environment variables in the container.

jobs.<job_id>.container.ports

Usejobs.<job_id>.container.ports to set anarray of ports to expose on the container.

jobs.<job_id>.container.volumes

Usejobs.<job_id>.container.volumes to set anarray of volumes for the container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.

To specify a volume, you specify the source and destination path:

<source>:<destinationPath>.

The<source> is a volume name or an absolute path on the host machine, and<destinationPath> is an absolute path in the container.

Example: Mounting volumes in a container

volumes:-my_docker_volume:/volume_mount-/data/my_data-/source/directory:/destination/directory

jobs.<job_id>.container.options

Usejobs.<job_id>.container.options to configure additional Docker container resource options. For a list of options, seedocker create options.

jobs.<job_id>.services

Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.

If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.

For more information about the differences between networking service containers, seeCommunicating with Docker service containers.

Example: Using localhost

This example creates two services: nginx and redis. When you specify the container port but not the host port, the container port is randomly assigned to a free port on the host. GitHub sets the assigned host port in the${{job.services.<service_name>.ports}} context. In this example, you can access the service host ports using the${{ job.services.nginx.ports['80'] }} and${{ job.services.redis.ports['6379'] }} contexts.

services:nginx:image:nginx# Map port 8080 on the Docker host to port 80 on the nginx containerports:-8080:80redis:image:redis# Map random free TCP port on Docker host to port 6379 on redis containerports:-6379/tcpsteps:-run:|      echo "Redis available on 127.0.0.1:${{ job.services.redis.ports['6379'] }}"      echo "Nginx available on 127.0.0.1:${{ job.services.nginx.ports['80'] }}"

jobs.<job_id>.services.<service_id>.image

The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.

Ifjobs.<job_id>.services.<service_id>.image is assigned an empty string, the service will not start. You can use this to set up conditional services, similar to the following example.

services:nginx:image:${{options.nginx==true&&'nginx'||''}}

jobs.<job_id>.services.<service_id>.credentials

If the image's container registry requires authentication to pull the image, you can usejobs.<job_id>.container.credentials to set amap of theusername andpassword. The credentials are the same values that you would provide to thedocker login command.

Example ofjobs.<job_id>.services.<service_id>.credentials

services:myservice1:image:ghcr.io/owner/myservice1credentials:username:${{github.actor}}password:${{secrets.github_token}}myservice2:image:dockerhub_org/myservice2credentials:username:${{secrets.DOCKER_USER}}password:${{secrets.DOCKER_PASSWORD}}

jobs.<job_id>.services.<service_id>.env

Sets amap of environment variables in the service container.

jobs.<job_id>.services.<service_id>.ports

Sets anarray of ports to expose on the service container.

jobs.<job_id>.services.<service_id>.volumes

Sets anarray of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.

To specify a volume, you specify the source and destination path:

<source>:<destinationPath>.

The<source> is a volume name or an absolute path on the host machine, and<destinationPath> is an absolute path in the container.

Example ofjobs.<job_id>.services.<service_id>.volumes

volumes:-my_docker_volume:/volume_mount-/data/my_data-/source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

Additional Docker container resource options. For a list of options, seedocker create options.

jobs.<job_id>.uses

The location and version of a reusable workflow file to run as a job. Use one of the following syntaxes:

• {owner}/{repo}/.github/workflows/{filename}@{ref} for reusable workflows in public and private repositories.
• ./.github/workflows/{filename} for reusable workflows in the same repository.

In the first option,{ref} can be a SHA, a release tag, or a branch name. If a release tag and a branch have the same name, the release tag takes precedence over the branch name. Using the commit SHA is the safest option for stability and security. For more information, seeSecure use reference.

If you use the second syntax option (without{owner}/{repo} and@{ref}) the called workflow is from the same commit as the caller workflow. Ref prefixes such asrefs/heads andrefs/tags are not allowed. You cannot use contexts or expressions in this keyword.

Example ofjobs.<job_id>.uses

jobs:call-workflow-1-in-local-repo:uses:octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89call-workflow-2-in-local-repo:uses:./.github/workflows/workflow-2.ymlcall-workflow-in-another-repo:uses:octo-org/another-repo/.github/workflows/workflow.yml@v1

For more information, seeReuse workflows.

jobs.<job_id>.with

When a job is used to call a reusable workflow, you can usewith to provide a map of inputs that are passed to the called workflow.

Any inputs that you pass must match the input specifications defined in the called workflow.

Unlikejobs.<job_id>.steps[*].with, the inputs you pass withjobs.<job_id>.with are not available as environment variables in the called workflow. Instead, you can reference the inputs by using theinputs context.

Example ofjobs.<job_id>.with

jobs:call-workflow:uses:octo-org/example-repo/.github/workflows/called-workflow.yml@mainwith:username:mona

jobs.<job_id>.with.<input_id>

A pair consisting of a string identifier for the input and the value of the input. The identifier must match the name of an input defined byon.workflow_call.inputs.<inputs_id> in the called workflow. The data type of the value must match the type defined byon.workflow_call.inputs.<input_id>.type in the called workflow.

Allowed expression contexts:github, andneeds.

jobs.<job_id>.secrets

When a job is used to call a reusable workflow, you can usesecrets to provide a map of secrets that are passed to the called workflow.

Any secrets that you pass must match the names defined in the called workflow.

Example ofjobs.<job_id>.secrets

jobs:call-workflow:uses:octo-org/example-repo/.github/workflows/called-workflow.yml@mainsecrets:access-token:${{secrets.PERSONAL_ACCESS_TOKEN}}

jobs.<job_id>.secrets.inherit

Use theinherit keyword to pass all the calling workflow's secrets to the called workflow. This includes all secrets the calling workflow has access to, namely organization, repository, and environment secrets. Theinherit keyword can be used to pass secrets across repositories within the same organization, or across organizations within the same enterprise.

Example ofjobs.<job_id>.secrets.inherit

on:workflow_dispatch:jobs:pass-secrets-to-workflow:uses:./.github/workflows/called-workflow.ymlsecrets:inherit

on:workflow_call:jobs:pass-secret-to-action:runs-on:ubuntu-lateststeps:-name:Usearepoororgsecretfromthecallingworkflow.run:echo${{secrets.CALLING_WORKFLOW_SECRET}}

jobs.<job_id>.secrets.<secret_id>

A pair consisting of a string identifier for the secret and the value of the secret. The identifier must match the name of a secret defined byon.workflow_call.secrets.<secret_id> in the called workflow.

Allowed expression contexts:github,needs, andsecrets.

Filter pattern cheat sheet

You can use special characters in path, branch, and tag filters.

• *: Matches zero or more characters, but does not match the/ character. For example,Octo* matchesOctocat.
• **: Matches zero or more of any character.
• ?: Matches zero or one of the preceding character.
• +: Matches one or more of the preceding character.
• [] Matches one alphanumeric character listed in the brackets or included in ranges. Ranges can only includea-z,A-Z, and0-9. For example, the range[0-9a-z] matches any digit or lowercase letter. For example,[CB]at matchesCat orBat and[1-2]00 matches100 and200.
• !: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character.

The characters*,[, and! are special characters in YAML. If you start a pattern with*,[, or!, you must enclose the pattern in quotes. Also, if you use aflow sequence with a pattern containing[ and/or], the pattern must be enclosed in quotes.

# Validpaths:-'**/README.md'# Invalid - creates a parse error that# prevents your workflow from running.paths:-**/README.md# Validbranches: [main,'release/v[0-9].[0-9]' ]# Invalid - creates a parse errorbranches: [main,release/v[0-9].[0-9] ]

For more information about branch, tag, and path filter syntax, seeon.<push>.<branches|tags>,on.<pull_request>.<branches|tags>, andon.<push|pull_request>.paths.

Patterns to match branches and tags

Patterns to match file paths

Path patterns must match the whole path, and start from the repository's root.