Workflow syntax for GitHub Actions

You can add a workflow file to your repository to create custom automated processes to automate your software development life cycle.

GitHub Actions is currently in limited public beta and is subject to change. We strongly recommend that you do not use this feature for high-value workflows and content during the beta period.

For more information, see "About GitHub Actions."

In this article

About YAML syntax for workflows

Workflow files use YAML syntax. If you're new to YAML and want to learn more, see "Learn YAML in five minutes."

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

Usage limits

Exceeding usage limits may result in jobs queueing, failing to run, or failing to complete. Limits are subject to change.

name

The name of your workflow. GitHub displays the names of your workflows on your repository's actions page. If you omit this field, GitHub sets the name to the workflow's filename.

on

Required The name of the GitHub event that triggers the workflow. You can provide a single event string, array of events, 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

# Trigger on push
on: push

Example using a list of events

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

Example restricting the workflow run to specific refs and paths

You can restrict the execution of a workflow to changes on specific branches, tags, or file paths.

You can include multiple paths and Git refs by using the same pattern matching syntax that .gitignore files use.

When you specify branches, tags, or paths, the workflow will only run when all patterns match.

# File paths to consider in the event. Optional; defaults to all
push:
  branches:    # Array of patterns that match refs/heads
  - master     # Push events on master branch
  - releases/* # Push events to branches matching refs/heads/releases/*
  - !refs/pull/*
  tags:        # Array of patterns that match refs/tags.
  - v1         # Push events to v1 tag
  paths:       # Push events containing matching files
  - test/*
  - *.xml
pull_request:  # Specify a second event with pattern matching
  paths:
  - js/*

Example scheduling workflows using cron syntax

This example triggers the workflow every 15 minutes:

on:
  schedule:
  # * is a special character in YAML so you have to quote this string
  - cron:  '*/15 * * * *'

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 fresh instance of the virtual 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."

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 will also fail unless the jobs use a conditional statement that causes the job to continue.

Example

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:

  1. job1
  2. job2
  3. job3

jobs.<job_id>.runs-on

Required The type of virtual host machine to run the job on. Each job runs with a fresh instance of the virtual environment specified in by runs-on.

Available virtual machine types are:

For more information, see Virtual environments for GitHub Actions for details.

Example

runs-on: ubuntu-18.04

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 are run as a step. Each step runs in its own process in the virtual environment and has access to the workspace and filesystem. Because steps are 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."

Example

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello-world@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          MY_VAR1: a_variable
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat
      - run: echo All Done!

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 "Contexts 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.

Expressions in an if conditional do not require the ${{ }} syntax. For more information, see "Contexts and expression syntax for GitHub Actions."

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 did my first step run?

Example using status check functions

The my backup step only runs when the previous step of a job fails. For more information, see "Status check functions."

    steps:
      - name: My first step
        uses: ./.github/actions/my-action
      - name: my backup step
        if: failure()
        uses: actions/heroku@master

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.

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 virtual environment. For more details, see runs-on and "Virtual environments for GitHub Actions."

Example using versioned actions

steps:    
  - uses: actions/setup-node@74bc508 # Reference a specific commit
  - uses: actions/setup-node@v1      # Reference the major version of a release   
  - uses: actions/setup-node@v1.2    # Reference a minor version of a release  
  - uses: actions/setup-node@master  # Reference a branch

Example using a public action

{owner}/{repo}@{ref}

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

jobs:
  my_first_job:
    steps:
      - name: My first step
      # Uses the master branch of a public repository
        uses: actions/heroku@master
      # use a specific version tag of a public repository
      - name: My second step
        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@master

Example using 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.

jobs:
  my_first_job:
    steps:
      - name: My first step
        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 a Docker public registry action

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

A Docker image in a public registry.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

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 run command. Commands run using non-login shells by default.

Each run represents a new process and shell in the virtual environment. You can provide multi-line content and each line runs in the same shell:

- name: Install Dependencies
  run: npm install      

jobs.<job_id>.steps.run.shell

The shell keyword allows you to override the default settings of the virtual environment's operating system shell. You can use built-in shell keywords, or you can define a custom set of shell options.

Supported for Windows platforms
Support for all platforms
Support for Linux and macOS platforms
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}.

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.

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@master
        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: monacorp/action-name@master
  with:
    entrypoint: /bin/echo
    args: this was run due to a $

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:

  1. Document required arguments in the action's README and omit them from the CMD instruction.
  2. Use defaults that allow using the action without specifying any args.
  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 Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

Example

steps:
- name: Run a custom command
  uses: monacorp/action-name@master
  with:
    entrypoint: /a/different/executable

The entrypoint keyword is meant to use 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 environment variables for steps to use in the virtual environment. Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets context. For more information, see "Virtual environments for GitHub Actions" and "Contexts and expression syntax for GitHub Actions."

steps:
- name: My first action
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    FIRST_NAME: Mona
    LAST_NAME: Octocat

jobs.<job_id>.steps.working-directory

The default directory that the action uses in a job's workspace.

jobs.<job_id>.steps.continue-on-error

Prevents a job from failing when a step fails. Set to true 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.

jobs.<job_id>.timeout-minutes

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

jobs.<job_id>.strategy

A strategy creates a build matrix for your jobs. You can define different variations of an environment to run each job in.

jobs.<job_id>.strategy.matrix

A build matrix is a set of different configurations of the virtual environment. For example you might run a job against more than one supported version of a language, operating system, or tool. Each configuration is a copy of the job that runs and reports a status.

You can specify a matrix by supplying an array for the configuration options. For example, if the GitHub virtual environment supports Node.js versions 6, 8, and 10 you could specify an array of those versions in the matrix.

You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "Usage limits."

Example

This example creates a matrix of three jobs, setting the node variable to a different value for each and using that variable as input to thesetup-node action. As a result, each job will use a different node version.

strategy:
  matrix:
    node: [6, 8, 10]
steps:
- uses: actions/setup-node@v1
  with:
    node-version: ${{ matrix.node }}

You could also run those jobs in two different Linux versions, using a matrix variable as input to the runs-on specifier, to create a total of 6 jobs (3 node versions x 2 Linux versions).

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    node: [6, 8, 10]
    os: [ubuntu-16.04, ubuntu-18.04]
steps:
- uses: actions/setup-node@v1
  with:
    node-version: ${{ matrix.node }}

To find supported configuration options for a GitHub virtual environment, see "Virtual environments for GitHub Actions."

You can restrict running the job to a subset of configurations in the matrix using include and exclude options.

The number of jobs is the cross product of the number of versions included in the arrays you provide along with any additions (include) or subtractions (exclude).

strategy:
  matrix:
    node: [4, 6, 8, 10]
    os: [macOS-10.14, windows-2016, ubuntu-18.04]
    include:
      # includes a new variable of npm with a value of 2 for the matrix leg matching the os and version
    - os: windows-2016
      node: 4
      npm: 2
    exclude:
      # excludes node 4 on macOS
    - os: macos-10.14
      node: 4

You can also specify the exact combinations you want using the include list:

strategy:
  matrix:
    include:
    - node: 4.0.0
      os: macOS-10.14
    - rvm: 6.0.0
      os: macOS-10.14
    - rvm: 8.0.0
      os: macOS-10.14

jobs.<job_id>.strategy.fail-fast

When set to true, GitHub cancels all in-progress jobs if any matrix job fails. Default: true

jobs.<job_id>.strategy.max-parallel

The maximum number of jobs that can run simultaneously when using a matrix job strategy. By default, GitHub will maximize the number of jobs run in parallel depending on the available runners on GitHub-hosted virtual machines.

strategy:
  max-parallel: 2

jobs.<job_id>.container

A container to run any steps in a job that don't already specify a container. When you do not set a container, all steps will run directly on the host specified by runs-on unless a step refers to an action configured to run in 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.

Example

jobs:
  my_job:
    container:
      image: node:10.16-jessie
      env:
        NODE_ENV: development
      ports:
      - 80
      volumes:
      - my_docker_volume:/volume_mount
      options: --cpus 1

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

jobs:
  my_job:
    container: node:10.16-jessie

jobs.<job_id>.container.image

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

jobs.<job_id>.container.env

Sets an array of environment variables in the container.

jobs.<job_id>.container.ports

Sets an array of ports to expose on the container.

jobs.<job_id>.container.volumes

Sets an array 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

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

jobs.<job_id>.container.options

Additional Docker container resource options. For a list of options, see "docker create options."

jobs.<job_id>.services

Additional containers to host services for a job in a workflow. These are useful for creating databases or cache services like redis. The runner on the virtual machine will automatically create a network and manage the lifecycle of the service containers.

The list of IP addresses for GitHub Actions outbound traffic is dynamic. GitHub cannot provide a consistent list of allowed IP addresses.

Example

This example creates two services for nginx and redis. GitHub selects an open port on the virtual host to bind the redis default port to. GitHub sets the bound host port in the ${{ job.services.<service_name>.ports[<port>] }} job context. For example, the redis port would be set in the ${{ job.services.redis.ports['6379'] }} environment variable.

services:
  nginx:
    image: nginx
    ports:
    - 8080:80
    env:
      NGINX_PORT: 80
  redis:
    image: redis
    ports:
    - 6379/tcp

jobs.<job_id>.services.image

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

jobs.<job_id>.services.env

Sets an array of environment variables in the service container.

jobs.<job_id>.services.ports

Sets an array of ports to expose on the service ontainer.

jobs.<job_id>.services.volumes

Sets an array 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

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

jobs.<job_id>.services.options

Additional Docker container resource options. For a list of options, see "docker create options."

Ask a human

Can't find what you're looking for?

Contact us