Configuring a workflow

In this article

• About workflows
• Creating a workflow file
• Triggering a workflow with events
• Filtering for specific branches, tags, and paths
• Choosing a runner
• Configuring a build matrix
• Using the checkout action
• Choosing the type of actions for your workflow
• Adding a workflow status badge to your repository
• Referencing actions in your workflow

About workflows

Workflows are custom automated processes that you can set up in your repository to build, test, package, release, or deploy any project on GitHub. With workflows you can automate your software development life cycle with a wide range of tools and services. For more information, see "About GitHub Actions."

You can create more than one workflow in a repository. You must store workflows in the .github/workflows directory in the root of your repository.

Workflows must have at least one job, and jobs contain a set of steps that perform individual tasks. Steps can run commands or use an action. You can create your own actions or use actions shared by the GitHub community and customize them as needed.

You can configure a workflow to start when a GitHub event occurs, on a schedule, or from an external event.

You need to configure workflows using YAML syntax, and save them as workflow files in your repository. Once you've successfully created a YAML workflow file and triggered the workflow, you will see the build logs, tests results, artifacts, and statuses for each step of your workflow. For more information, see "Managing a workflow run."

You can also receive notifications for workflow status updates. For more information about notification options, see "Choosing the delivery method for your notifications."

Usage limits apply to individual workflows. For more information, see "Usage limits for workflows."

Creating a workflow file

At a high level, these are the steps to add a workflow file. You can find specific configuration examples in the sections that follow.

1. At the root of your repository, create a directory named .github/workflows to store your workflow files.

2. In .github/workflows, add a .yml or .yaml file for your workflow. For example, .github/workflows/continuous-integration-workflow.yml.

3. Use the "Workflow syntax for GitHub Actions" reference documentation to choose events to trigger an action, add actions, and customize your workflow.

4. Commit your changes in the workflow file to the branch where you want your workflow to run.

Workflow file example

name: Greet Everyone
# This workflow is triggered on pushes to the repository.
on: [push]

jobs:
  build:
    # Job name is Greeting
    name: Greeting
    # This job runs on Linux
    runs-on: ubuntu-latest
    steps:
      # This step uses GitHub's hello-world-javascript-action: https://github.com/actions/hello-world-javascript-action
      - name: Hello world
        uses: actions/hello-world-javascript-action@v1
        with:
          who-to-greet: 'Mona the Octocat'
        id: hello
      # This step prints an output (time) from the previous step's action.
      - name: Echo the greeting's time
        run: echo 'The time was ${{ steps.hello.outputs.time }}.'

Triggering a workflow with events

You can configure a workflow to start once:

• An event on GitHub occurs, such as when someone pushes a commit to a repository or when an issue or pull request is created.
• A scheduled event begins.
• An external event occurs.

To trigger a workflow after an event happens on GitHub, add on: and an event value after the workflow name. For example, this workflow is triggered when changes are pushed to any branch in the repository.

name: descriptive-workflow-name
on: push

To schedule a workflow, you can use the POSIX cron syntax in your workflow file. The shortest interval you can run scheduled workflows is once every 5 minutes. For example, this workflow is triggered every hour.

on:
  schedule:
    - cron:  '0 * * * *'

To trigger a workflow after an external event occurs, you can invoke a repository_dispatch webhook event by calling the "Create a repository dispatch event" REST API endpoint. For more information, see "Create a repository dispatch event" in the GitHub Developer documentation.

For more information and examples, see "Events that trigger workflows."

Filtering for specific branches, tags, and paths

You can set up your workflow to run only on certain branches.

For example, this workflow runs when a push that includes files in the test directory is made on the master branch, or pushes to the v1 tag.

on:
  push:
    branches:
      - master
    tags:
      - v1
    # file paths to consider in the event. Optional; defaults to all.
    paths:
      - 'test/*'

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

Choosing a runner

You can run workflows on GitHub-hosted runners or self-hosted runners. Jobs can run directly on the machine or in a Docker container.

You can specify the runner for each job in a workflow using runs-on. For more information about runs-on, see "Workflow syntax for GitHub Actions."

Using a GitHub-hosted runner

You can select from different types and versions of virtual host machines, including Linux, Windows, and macOS. Each job in a workflow executes in a fresh instance of the virtual environment, and steps within a job can share information using the filesystem. For more information, see "Virtual environments for GitHub Actions-hosted runners."

For example, you can use ubuntu-latest to specify the latest version of an Ubuntu GitHub-hosted runner.

runs-on: ubuntu-latest

Using a self-hosted runner

If you've added self-hosted runners to your repository, you can specify a self-hosted runner using labels. All self-hosted runners get the self-hosted label and each self-hosted runner has labels for its operating system and system architecture. For more information, see "Using self-hosted runners in a workflow."

For example, if you added a self-hosted runner with a Linux operating system and ARM32 architecture, you can select that runner using the self-hosted, linux, and ARM32 labels.

runs-on: [self-hosted, linux, ARM32]

Configuring a build matrix

To test across multiple operating systems, platforms, and language versions at the same time, you can configure a build matrix.

A build matrix provides different configurations for the virtual environment to test. For example, a workflow can run a job for more than one supported version of a language, operating system, or tool. For each configuration, a copy of the job runs and reports a status.

You can specify a build matrix in your workflow file with an array that lists the configuration options under strategy:. For example, this build matrix will run a job with different versions of Node.js and Ubuntu, a Linux operating system.

When you define a matrix of operating systems, you must set the required runs-on keyword to the operating system of the current job, rather than hard-coding the operating system name. To access the operating system name, you can use the matrix.os context parameter to set runs-on. For more information, see "Contexts and expression syntax for GitHub Actions."

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-16.04, ubuntu-18.04]
    node: [6, 8, 10]

For more information, see "Workflow syntax for GitHub Actions."

Using the checkout action

There are several standard actions you can use in your workflow. The checkout action is a standard action that you must include in your workflow before other actions when:

• Your workflow requires a copy of your repository's code, such as when you're building and testing your repository or using continuous integration.
• There's at least one action in your workflow that is defined in the same repository. For more information, see "Referencing actions in your workflow."

To use the standard checkout action without further specifications, include this step:

- uses: actions/checkout@v1

Using v1 in this example ensures you're using a stable version of the checkout action.

To shallow clone your repository, or copy only the latest version of your repository, set the fetch-depth with the with syntax:

- uses: actions/checkout@v1
  with:
    fetch-depth: 1

For more information, see the checkout action.

Choosing the type of actions for your workflow

There are different types of actions you can use in your workflow to suit your project's needs:

• Docker container actions
• JavaScript actions

For more information, see "About actions."

When choosing the type of actions to use in your workflow, we recommend exploring existing actions in public repositories or on Docker hub and potentially customizing these actions for your project.

You can browse and use actions built by GitHub in the github.com/actions organization. To visit Docker Hub, see "Docker Hub" on the Docker site.

Referencing actions in your workflow

To reference actions in your workflow file with the correct syntax, you must consider where the action is defined.

Workflows can use actions defined in:

• A public repository
• The same repository where your workflow file references the actions
• A published Docker container image on Docker Hub

To use an action defined in a private repository, both the workflow file and the action must be in the same repository. Your workflow cannot use actions defined in other private repositories, even if the other private repository is in the same organization.

To keep your workflow stable even when updates are made to an action, you can reference the version of the action you're using by specifying a Git ref or Docker tag number in your workflow file. For examples, see "Workflow syntax for GitHub Actions."

For more detailed configuration options, see "Workflow syntax for GitHub Actions."

Referencing an action from a public repository

If an action is defined in a public repository, you must reference the action using the syntax {owner}/{repo}@{ref} or {owner}/{repo}/{path}@{ref}.

jobs:
  my_first_job:
    name: My Job Name
      steps:
        - uses: actions/setup-node@v1
          with:
            node-version: 10.x

To see a complete workflow example, see the setup node template repository.

Referencing an action in the same repository where a workflow file uses the action

If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌{owner}/{repo}@{ref} or ./path/to/dir syntax in your workflow file.

Example repository file structure:

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

Example workflow file:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - uses: actions/checkout@v1
      # This step references the directory that contains the action.
      - uses: ./.github/actions/hello-world-action

Referencing a container on Docker Hub

If an action is defined in a published Docker container image on Docker Hub, you must reference the action with the docker://{image}:{tag} syntax in your workflow file. To protect your code and data, we strongly recommend you verify the integrity of the Docker container image from Docker Hub before using it in your workflow.

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

For some examples of Docker actions, see the Docker-image.yml workflow and "Creating a Docker container action."

For more information, see "Workflow syntax for GitHub Actions."

Adding a workflow status badge to your repository

Status badges show whether a workflow is currently failing or passing. A common place to add a status badge is in the README.md file of your repository, but you can add it to any web page you'd like. By default, badges display the status of your default branch (usually master). You can also display the status of a workflow run for a specific branch or event using the branch and event query parameters in the URL.

If your workflow uses the name keyword, you can reference the workflow by name. If the name of your workflow contains white space, you'll need to replace the space with the URL encoded string %20. For more information about the name keyword, see "Workflow syntax for GitHub Actions."

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg

If your workflow doesn't have a name, you can reference the workflow file using the file path relative to the repository's root directory.

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_FILE_PATH>/badge.svg

Example using a workflow name

This Markdown example adds a status badge for a workflow with the name "Greet Everyone." The OWNER of the repository is the actions organization and the REPOSITORY name is hello-world.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg)

Example using a workflow file path

This Markdown example adds a status badge for a workflow with the file path .github/workflows/main.yml. The OWNER of the repository is the actions organization and the REPOSITORY name is hello-world.

![](https://github.com/actions/hello-world/workflows/.github/workflows/main.yml/badge.svg)

Example using the branch parameter

This Markdown example adds a status badge for a branch with the name feature-1.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg?branch=feature-1)

Example using the event parameter

This Markdown example adds a badge that displays the status of workflow runs triggered by the pull_request event.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg?event=pull_request)

Further reading

• "Automating your workflow with GitHub Actions"
• "Managing billing for GitHub Actions"