Article version: GitHub.com

Workflow syntax for GitHub Actions

A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration.

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server, and GitHub AE. GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans. For more information, see "GitHub's products."

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, see "Learn YAML in Y minutes."

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

`name`

The name of your workflow. GitHub displays the names of your workflows on your repository's actions page. If you omit name, GitHub sets it to the workflow file path relative to the root of the repository.

`on`

Required. The name of the GitHub event that triggers the workflow. You can provide a single event string, array of events, array of event types, or an event configuration map that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see "Events that trigger workflows."

Example: Using a single event

# Triggered when code is pushed to any branch in a repository
on: push

Example: Using a list of events

# Triggers the workflow on push or pull request events
on: [push, pull_request]

Example: Using multiple events with activity types or configuration

If you need to specify activity types or configuration for an event, you must configure each event separately. You must append a colon (:) to all events, including events without configuration.

on:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  # Also trigger on page_build, as well as release created events
  page_build:
  release:
    types: # This configuration does not affect the page_build event above
      - created

`on.<event_name>.types`

Selects the types of activity that will trigger a workflow run. Most GitHub events are triggered by more than one type of activity. For example, the event for the release resource is triggered when a release is published, unpublished, created, edited, deleted, or prereleased. The types keyword enables you to narrow down activity that causes the workflow to run. When only one activity type triggers a webhook event, the types keyword is unnecessary.

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

# Trigger the workflow on pull request activity
on:
  release:
    # Only use the types keyword to narrow down the activity types that will trigger your workflow.
    types: [published, created, edited]

`on.<push|pull_request>.<branches|tags>`

When using the push and pull_request events, you can configure a workflow to run on specific branches or tags. For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.

The branches, branches-ignore, tags, and tags-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 to escape each of these special characters with \. For more information about glob patterns, see the "Filter pattern cheat sheet."

Example: Including branches and tags

The patterns defined in branches and tags are evaluated against the Git ref's name. For example, defining the pattern mona/octocat in branches will match the refs/heads/mona/octocat Git ref. The pattern releases/** will match the refs/heads/releases/10 Git ref.

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      # Push events on main branch
      - main
      # Push events to branches matching refs/heads/mona/octocat
      - 'mona/octocat'
      # Push events to branches matching refs/heads/releases/10
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:        
      - v1             # Push events to v1 tag
      - v1.*           # Push events to v1.0, v1.1, and v1.9 tags

Example: Ignoring branches and tags

Anytime a pattern matches the branches-ignore or tags-ignore pattern, the workflow will not run. The patterns defined in branches-ignore and tags-ignore are evaluated against the Git ref's name. For example, defining the pattern mona/octocat in branches will match the refs/heads/mona/octocat Git ref. The pattern releases/**-alpha in branches will match the refs/releases/beta/3-alpha Git ref.

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      # Do not push events to branches matching refs/heads/mona/octocat
      - 'mona/octocat'
      # Do not push events to branches matching refs/heads/releases/beta/3-alpha
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:
      - v1.*           # Do not push events to tags v1.0, v1.1, and v1.9

Excluding branches and tags

You can use two types of filters to prevent a workflow from running on pushes and pull requests to tags and branches.

branches or branches-ignore - You cannot use both the branches and branches-ignore filters for the same event in a workflow. Use the branches filter when you need to filter branches for positive matches and exclude branches. Use the branches-ignore filter when you only need to exclude branch names.
tags or tags-ignore - You cannot use both the tags and tags-ignore filters for the same event in a workflow. Use the tags filter when you need to filter tags for positive matches and exclude tags. Use the tags-ignore filter when you only need to exclude tag names.

Example: Using positive and negative patterns

You can exclude tags and branches using the ! character. 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 to releases/10 or releases/beta/mona, but not on releases/10-alpha or releases/beta/3-alpha because the negative pattern !releases/**-alpha follows the positive pattern.

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

`on.<push|pull_request>.paths`

When using the push and pull_request events, you can configure a workflow to run when at least one file does not match paths-ignore or at least one modified file matches the configured paths. Path filters are not evaluated for pushes to tags.

The paths-ignore and paths keywords accept glob patterns that use the * and ** wildcard characters to match more than one path name. For more information, see the "Filter pattern cheat sheet."

Example: Ignoring paths

When all the path names match patterns in paths-ignore, the workflow will not run. GitHub evaluates patterns defined in paths-ignore against the path name. A workflow with the following path filter will only run on push events that include at least one file outside the docs directory at the root of the repository.

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

Example: Including paths

If at least one path matches a pattern in the paths filter, the workflow runs. To trigger a build anytime you push a JavaScript file, you can use a wildcard pattern.

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

Excluding paths

You can exclude paths using two types of filters. You cannot use both of these filters for the same event in a workflow.

paths-ignore - Use the paths-ignore filter when you only need to exclude path names.
paths - Use the paths filter when you need to filter paths for positive matches and exclude paths.

Example: Using positive and negative patterns

You can exclude paths using the ! character. The order that you define 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 the push event includes a file in the sub-project directory or its subdirectories, unless the file is in the sub-project/docs directory. For example, a push that changed sub-project/index.js or sub-project/src/index.js will trigger a workflow run, but a push changing only sub-project/docs/readme.md will not.

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

Git diff comparisons

Note: If you push more than 1,000 commits, or if GitHub does not generate the diff due to a timeout, the workflow will always run.

The filter determines if a workflow should run by evaluating the changed files and running them against the paths-ignore or paths 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.

Diffs are limited to 300 files. If there are files changed that aren't matched in the first 300 files returned by the filter, the workflow will not run. You may need to create more specific filters so that the workflow will run automatically.

For more information, see "About comparing branches in pull requests."

`on.workflow_dispatch.inputs`

When using workflow_dispatch event, you can optionally specify inputs that are passed to the workflow. Workflow dispatch inputs are specified with the same format as action inputs. For more information about the format see "Metadata syntax for GitHub Actions."

on: 
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'
        required: false

The triggered workflow receives the inputs in the github.event.inputs context. For more information, see "Context and expression syntax for GitHub Actions."

`on.schedule`

You can schedule a workflow to run at specific UTC times using POSIX cron syntax. Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes.

This example triggers the workflow every day at 5:30 and 17:30 UTC:

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

For more information about cron syntax, see "Events that trigger workflows."

`permissions`

You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access. For more information, see "Authentication in a workflow."

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

Available scopes and access values:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

If you specify the access for any of these scopes, all of those that are not specified are set to none.

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

You can use the permissions 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 the Send write tokens to workflows from pull requests option in the GitHub Actions settings. For more information, see "Disabling or limiting GitHub Actions for a repository."

Example

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

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

`env`

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

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

Example

env:
  SERVER: production

`defaults`

A map 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, see jobs.<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 provide default shell and working-directory options for all run steps in a workflow. You can also set default settings for run that are only available to a job. For more information, see jobs.<job_id>.defaults.run. You cannot use contexts or expressions in this keyword.

Example

defaults:
  run:
    shell: bash
    working-directory: scripts

`concurrency`

Note: Concurrency is currently in beta and subject to change.

Concurrency ensures 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 use the github context. For more information about expressions, see "Context and expression syntax for GitHub Actions."

You can also specify concurrency at the job level. For more information, see jobs.<job_id>.concurrency.

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 be pending. Any previously pending job or workflow in the concurrency group will be canceled. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true.

Examples: Using concurrency and the default behavior

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

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

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

`jobs`

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

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

You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" 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, see "Workflow Jobs."

`jobs.<job_id>`

Each job must have an id to associate with the job. The key job_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 the jobs object. The <job_id> must start with a letter or _ and contain only alphanumeric characters, -, or _.

Example

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

`jobs.<job_id>.name`

The name of the job displayed on GitHub.

`jobs.<job_id>.needs`

Identifies any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue.

Example: Requiring dependent jobs to be successful

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

In this example, job1 must complete successfully before job2 begins, and job3 waits for both job1 and job2 to complete.

The jobs in this example run sequentially:

job1
job2
job3

Example: Not requiring dependent jobs to be successful

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: always()
    needs: [job1, job2]

In this example, job3 uses the always() conditional expression so that it always runs after job1 and job2 have completed, regardless of whether they were successful. For more information, see "Context and expression syntax."

`jobs.<job_id>.runs-on`

Required. The type of machine to run the job on. The machine can be either a GitHub-hosted runner or a self-hosted runner.

GitHub-hosted runners

If you use a GitHub-hosted runner, each job runs in a fresh instance of a virtual environment specified by runs-on.

Available GitHub-hosted runner types are:

Virtual environment	YAML workflow label	Notes
Windows Server 2022^[beta]	`windows-2022`	The `windows-latest` label currently uses the Windows Server 2019 runner image.
Windows Server 2019	`windows-latest` or `windows-2019`
Windows Server 2016	`windows-2016`
Ubuntu 20.04	`ubuntu-latest` or `ubuntu-20.04`
Ubuntu 18.04	`ubuntu-18.04`
Ubuntu 16.04^[deprecated]	`ubuntu-16.04`	Deprecated and limited to existing customers only. Migrate to Ubuntu 20.04. For more information, see the blog post.
macOS Big Sur 11	`macos-11`	The `macos-latest` label currently uses the macOS 10.15 runner image.
macOS Catalina 10.15	`macos-latest` or `macos-10.15`

Note: Beta Images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta Images may not be covered by customer support.

Example

runs-on: ubuntu-latest

For more information, see "Virtual environments for GitHub-hosted runners."

Self-hosted runners

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

All self-hosted runners have the self-hosted label, and you can select any self-hosted runner by providing only the self-hosted label. Alternatively, you can use self-hosted in an array with additional labels, such as labels for a specific operating system or system architecture, to select only the runner types you specify.

Example

runs-on: [self-hosted, linux]

For more information, see "About self-hosted runners" and "Using self-hosted runners in a workflow."

`jobs.<job_id>.permissions`

By specifying the permission within a job definition, you can configure a different set of permissions for the GITHUB_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, see permissions.

Available scopes and access values:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

If you specify the access for any of these scopes, all of those that are not specified are set to none.

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

Example

This example shows permissions being set for the GITHUB_TOKEN that will only apply to the job named stale. Write access is granted for the issues and pull-requests scopes. All other scopes will have no access.

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v3

`jobs.<job_id>.environment`

The environment that the job references. All environment protection rules must pass before a job referencing the environment is sent to a runner. For more information, see "Environments."

You can provide the environment as only the environment name, or as an environment object with the name and url. The URL maps to environment_url in the deployments API. For more information about the deployments API, see "Deployments."

Example using a single environment name

environment: staging_environment

Example using environment name and URL

environment:
  name: production_environment
  url: https://github.com

The URL can be an expression and can use any context except for the secrets context. For more information about expressions, see "Context and expression syntax for GitHub Actions."

Example

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

`jobs.<job_id>.concurrency`

Note: Concurrency is currently in beta and subject to change.

Note: When concurrency is specified at the job level, order is not guaranteed for jobs or runs that queue within 5 minutes of each other.

Concurrency ensures 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 use any context except for the secrets context. For more information about expressions, see "Context and expression syntax for GitHub Actions."

You can also specify concurrency at the workflow level. For more information, see concurrency.

Examples: Using concurrency and the default behavior

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

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

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

`jobs.<job_id>.outputs`

A map 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, see jobs.<job_id>.needs.

Job outputs are strings, and 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.

To use job outputs in a dependent job, you can use the needs context. For more information, see "Context and expression syntax for GitHub Actions."

Example

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}

`jobs.<job_id>.env`

A map of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see env and jobs.<job_id>.steps[*].env.

Example

jobs:
  job1:
    env:
      FIRST_NAME: Mona

`jobs.<job_id>.defaults`

A map 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, see defaults.

`jobs.<job_id>.defaults.run`

Provide default shell and working-directory to all run steps in the job. Context and expression are not allowed in this section.

You can provide default shell and working-directory options for all run steps in a job. You can also set default settings for run for the entire workflow. For more information, see jobs.defaults.run. You cannot use contexts or expressions in this keyword.

Example

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: scripts

`jobs.<job_id>.if`

You can use the 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.

When you use expressions in an if conditional, you may omit the expression syntax (${{ }}) because GitHub automatically evaluates the if conditional as an expression. For more information, see "Context and expression syntax for GitHub Actions."

`jobs.<job_id>.steps`

A job contains a sequence of tasks called steps. 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.

You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Example

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

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

A unique identifier for the step. You can use the id to reference the step in contexts. For more information, see "Context and expression syntax for GitHub Actions."

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

You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.

Example: Using contexts

This step only runs when the event type is a pull_request and the event action is unassigned.

steps:
 - name: My first step
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
   run: echo This event is a pull request that had an assignee removed.

Example: Using status check functions

The my backup step only runs when the previous step of a job fails. For more information, see "Context and expression syntax for GitHub Actions."

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

`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 a published 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 number. 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.
Using the specific major action version allows you to receive critical fixes and security patches while still maintaining compatibility. It also assures that your workflow should still work.
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 the with 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, see runs-on.

Example: Using versioned actions

steps:
  # Reference a specific commit
  - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
  # Reference the major version of a release
  - uses: actions/checkout@v2
  # Reference a specific version
  - uses: actions/checkout@v2.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: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: 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: My first step
        uses: 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.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Use local my-action
        uses: ./.github/actions/my-action

Example: Using a Docker Hub action

docker://{image}:{tag}

A Docker image published on Docker Hub.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Example: Using the GitHub Packages Container registry

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

A Docker image in the GitHub Packages Container registry.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: 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 at gcr.io.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: 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 an encrypted secret. For more information, see "Creating a personal access token" and "Encrypted secrets."

Replace PERSONAL_ACCESS_TOKEN in the example with the name of your secret.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

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

Runs command-line programs using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run 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, see "Using a specific shell."

Each run 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: Install Dependencies
  run: npm install

A multi-line command:

- name: Clean install dependencies and build
  run: |
    npm ci
    npm run build

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

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

Using a specific shell

You can override the default shell settings in the runner's operating system using the shell keyword. You can use built-in shell 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 specifed in the run keyword.

Supported platform	`shell` parameter	Description	Command run internally
All	`bash`	The default shell on non-Windows platforms with a fallback to `sh`. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used.	`bash --noprofile --norc -eo pipefail {0}`
All	`pwsh`	The PowerShell Core. GitHub appends the extension `.ps1` to your script name.	`pwsh -command ". '{0}'"`
All	`python`	Executes the python command.	`python {0}`
Linux / macOS	`sh`	The fallback behavior for non-Windows platforms if no shell is provided and `bash` is not found in the path.	`sh -e {0}`
Windows	`cmd`	GitHub appends the extension `.cmd` to your script name and substitutes for `{0}`.	`%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`.
Windows	`pwsh`	This is the default shell used on Windows. The PowerShell Core. GitHub appends the extension `.ps1` to your script name. If your self-hosted Windows runner does not have PowerShell Core installed, then PowerShell Desktop is used instead.	`pwsh -command ". '{0}'"`.
Windows	`powershell`	The PowerShell Desktop. GitHub appends the extension `.ps1` to your script name.	`powershell -command ". '{0}'"`.

Example: Running a script using bash

steps:
  - name: Display the path
    run: echo $PATH
    shell: bash

Example: Running a script using Windows `cmd`

steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd

Example: Running a script using PowerShell Core

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh

Example: Using PowerShell Desktop to run a script

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: powershell

Example: Running a python script

steps:
  - name: Display the path
    run: |
      import os
      print(os.environ['PATH'])
    shell: python

Custom shell

You can set the shell value to a template string using command […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: Display the environment variables and their values
    run: |
      print %ENV
    shell: perl {0}

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

For information about the software included on GitHub-hosted runners, see "Specifications for 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:
- Fail-fast behavior using set -eo pipefail: Default for bash and built-in shell. It is also the default when you don't provide an option on non-Windows platforms.
- You can opt out of fail-fast and take full control 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. For pwsh and powershell built-in shell, we will prepend $ErrorActionPreference = 'stop' to script contents.
- We append if ((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}, or powershell -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 previous sh and pwsh default behavior and is the cmd.exe default, so this behavior remains intact.

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

A map 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 with INPUT_ and converted to upper case.

Example

Defines the three input parameters (first_name, middle_name, and last_name) defined by the hello_world action. These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

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

A string that defines the inputs for a Docker container. GitHub passes the args to the container's ENTRYPOINT when the container starts up. An array of strings is not supported by this parameter.

Example

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

Document required arguments in the action's README and omit them from the CMD instruction.
Use defaults that allow using the action without specifying any args.
If the action exposes a --help fla