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, see "About 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. Create a new .yml file for your workflow in a new directory called .github/workflows at the root of your repository. For example, .github/workflows/continuous-integration-workflow.yml.

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

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

Workflow file example

name: Greet Everybody
# 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:
    - uses: actions/checkout@v1
    # This step uses the hello-world-action stored in this workflow's repository.
    - uses: ./hello-world-action
      with:
        who-to-greet: 'Octocat'
      id: hello
    # This step prints the 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:
    # * is a special character in YAML so you have to quote this string
  - 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

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

For example, this workflow runs when a push is made on the master branch.

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

For more information about referencing branches in your workflow, see "Workflow syntax for GitHub Actions."

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.

strategy:
  matrix:
    node: [6, 8, 10]
    os: [ubuntu-14.04, ubuntu-18.04]

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:

.github
└── workflows
    └── my-first-workflow.yml
.
└── 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: ./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."

Further reading

Ask a human

Can't find what you're looking for?

Contact us