Core Conceptions for GitHub Actions

  1. Workflow

A configurable automated process

  1. Workflow run

An instance of the workflow that runs when the pre-configured event occurs

  1. Workflow file

The YAML file that defines the workflow configuration with at least one job.

  1. Job

A defined task made up of steps. Each job is run in a fresh instance of the virtual environement.

  1. Step

A step is a set of tasks performed by a job. Each step in a job executes in the same virtual environment, allowing the actions in that job to share information using the filesystem.

  1. Action

Individual tasks that combined as steps to create a job. Actions are the smallest portable building block of a workflow.

Configuring a workflow

About workflows

  1. Store workflows in the .github/workflows directory in the root of the repository

Create a workflow file

  1. At the root of the repository, create a directory named ./github/workflows to store the workflow files.
  2. In .github/workflows, add a .yml or .yaml file for the workflow.
  3. Use Workflow syntax for GitHub Actions reference documentation to choose events to trigger an action, add actions, and customize the workflows.
  4. Commit the changes in the workflow file to the branch where the workflow is desired to run.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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
      - name: Hello World
        use: 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 }}.'

Configuring a build matrix

To test across multiple operating system, platforms, and language versions at the same time, a matrix could be set up.

A build matrix provides different configurations for the virtual environment to test.

1
2
3
4
5
runs-on: $\{\{ matrix.os }}
strategy:
  matrix::
    os: [ubuntu-14.04, ubuntu-18.04]
    node: [6, 8, 10]

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.

To use the standard checkout action without furthur specifications, including this step:

1
- uses: actions/checkout@v1

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

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

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

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 publised Docker container image on Docker Hub
1
2
3
4
5
6
7
8
jobs:
  my_first_job:
    steps:
      - uses: actions/setup-node@v1
        with:
          node-version: 10.x
      - uses: ./.github/actions/hello-world-action
      - uses: docker://alpine:3.8

Workflow syntax for GitHub Actions

name

The name of the workflow.

on

Required The name of the GitHub event that triggers the workflow.
string, array and map are acceptable

1
2
on: push
on: [push, pull_request]

on.<push|pull_request>.<tag|branches>

When using the push and pull_request events, you can configure a workflow to run on specific branches or tags

1
2
3
4
5
6
7
8
on:
  push:
    branches:
      - master
      - 'release/*'
    tags:
      - v1
      - v1.0

on.<push|pull_request>.paths

When using the push and pull_request events, you can configure a workflow to run when at least one modified file matches a pattern defined in paths.

1
2
3
4
5
6
on:
  push:
    paths:
      - '*'
      - '!*.js'
      ```

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

Each job runs in a fresh instance of the virtual environment specified by runs-on.

jobs.

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

1
2
3
4
5
jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs..name

The name of the job displayed on GitHub

jobs..needs

Identifies any jobs that must complete successfully before this job will run. It can be a string or array of string

1
2
3
4
5
6
jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

jobs.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 by runs-on:

Available virtual machine types are:

  • ubuntu-latest, ubuntu-18.04 or ubuntu-16.04
  • windows-latest, windows-2019 or windows-2016
  • macOS-latest, macOS-10.14

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

Each step run in its own process in the virtual 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $LAST_NAME.
jobs..steps.id

A unique identifier for the step. You can use the id to reference the step in contexts.

jobs..steps.if

You can use the if conditional to prevent a step from running unless a condition is met.

Expression in an if conditional do not require the $\{\{ }} syntax.

1
2
3
4
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
jobs..step.name

A name for the step to display on GitHub.

jobs..steps.uses

Selects an action to run as part of a step in your job. An action is a reusable unit of code.

The version of the action is strongly recommended to be included in the action by specifying a Git Ref, SHA, or Docker tag number.

jobs..steps.with

A map of the input parameters defined by the action. Each input parameter is a key/pair. Input parameters are set as environment variables.

The variable is prefixed with INPUT_ and converted to uppercase.

1
2
3
4
5
6
7
8
9
jobs:
  my_first_step:
    steps:
      - name: My first step
        uses: actions/hello_world@master
        with:
          first_name: Mona # INPUT_FIRST_NAME
          middle_name: The # INPUT_MIDDLE_NAME
          last_name: Octocat # INPUT_LAST_NAME
jobs..steps.with.args

// TODO:

jobs.steps.with.entrypoint

// TODO:

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

1
2
3
4
steps:
  - name: My first step
    env:
      GITHUB_TOKEN: $\{\{ secrets.GITHUB_TOKEN }}