Configuring a workflow

You can create, view, or edit workflows for a repository if you have write or admin permissions to the repository. You can customize your workflow configuration based on the type of actions you include in your workflow.

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 about the beta, see "About GitHub Actions."

For more information about using GitHub Actions, see "Automating your workflow with GitHub Actions."

In this article

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

Annotated workflow run image

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:

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

Filtering pattern cheat sheet

You can use the * and ** wildcard characters in path, branch, and tag filters.

The * character is a special character in YAML. When you start a pattern with *, you must use quotes.

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

Patterns to match branches and tags

Pattern Description Example matches
feature/* The * wildcard matches any character, but does not match slash (/). -feature/my-branch
-feature/your-branch
feature/** The ** wildcard matches any character including slash (/) in branch and tag names. -feature/beta-a/my-branch
-feature/your-branch
-feature/mona/the/octocat
-master
-releases/mona-the-octcat
Matches the exact name of a branch or tag name. -master
-releases/mona-the-octocat
'*' Matches all branch and tag names that don't contain a slash (/). The * character is a special character in YAML. When you start a pattern with *, you must use quotes. -master
-releases
'**' Matches all branch and tag names. This is the default behavior when you don't use a branches or tags filter. -all/the/branches
-every/tag
'*feature' The * character is a special character in YAML. When you start a pattern with *, you must use quotes. -mona-feature
-feature
-ver-10-feature
v2* Matches branch and tag names that start with v2. -v2
-v2.0
-v2.9

Patterns to match file paths

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

Pattern Description of matches Example matches
'*' The * wildcard matches any character, but does not match slash (/). The * character is a special character in YAML. When you start a pattern with *, you must use quotes. -README.md
-server.rb
'**' The ** wildcard matches any character including slash (/). This is the default behavior when you don't use a path filter. -all/the/files.md
'*.js' The * wildcard matches any character, but does not match slash (/). Matches all .js files at the root of the repository. -app.js
-index.js
'**.js' Matches all .js files in the repository. -index.js
-js/index.js
-src/js/app.js
docs/* All files within the root of the docs directory, at the root of the repository. -docs/README.md
-docs/file.txt
docs/** Any files in the /docs directory at the root of the repository. -docs/README.md
-docs/mona/octocat.txt
docs/**/*.md A file with a .md suffix anywhere in the docs directory. -docs/README.md
-docs/mona/hello-world.md
-docs/a/shell/file.sh
'**/docs/**' Any files in a docs directory anywhere in the repository. -/docs/hello.md
-dir/docs/my-file.txt
-space/docs/plan/space.doc
'**/README.md' A README.md file anywhere in the repository. -README.md
-js/README.md
'**/*src/**' Any file in a folder with a src suffix anywhere in the repository. -a/src/app.js
-my-src/code/js/app.js
'**/*-post.md' A file with the suffix -post.md anywhere in the repository. -my-post.md
-path/their-post.md
'**/migrate-*.sql' A file with the prefix migrate- and suffix .sql anywhere in the repository. -migrate-10909.sql
-db/migrate-v1.0.sql
-db/sept/migrate-v1.sql
-*.md
-!README.md
Using an exclamation mark (!) in front of a pattern negates it. When a file matches a pattern and also matches a negative pattern defined later in the file, the file will not be included. -hello.md
Does not match
-README.md
-docs/hello.md
-*.md
-!README.md
-README*
Patterns are checked sequentially. A pattern that negates a previous pattern will re-include file paths. -hello.md
-README.md
-README.doc

Choosing a virtual environment

You can run workflows on a GitHub-hosted virtual machine or in a Docker container. You can specify the virtual environment for each job in a workflow.

To specify the operating system, tools, packages, and settings of the virtual environment where you want to run your workflow, you must use special syntax in your workflow file.

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

Virtual host machines

You can select from different types and versions of virtual host machines, including Ubuntu, Linux, and macOS. Each job in a workflow executes in the same virtual environment, allowing the actions in that job to share information using the filesystem.

To run a job on a fresh instance of the virtual environment, you can specify a virtual host to run a job.

runs-on: ubuntu-18.04

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

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-14.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:

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:

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:

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 or the Docker actions repository.

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. Badges display the status of your default branch (usually master).

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

Further reading

Ask a human

Can't find what you're looking for?

Contact us