GitHub Workflows

How to create an automation script in GitHub? - Or at least how to get started…

How to Handle Automation Scripts

Automation scripts for GitHub should be included in the repository and must be located in the .github/workflows/ directory. You can name the YAML files as you prefer, and you are free to add multiple files to the .github/workflows/ directory, enabling you to associate several Workflows with a single Project. Each file in that directory is treated as a separate definition of a Workflow. This is an excellent method for sharing complete workflows across projects; simply copy the relevant YAML file.

Minimal Content of an Automation Script

A GitHub Workflow must include at least the following elements (keys):

Note

GitHub provides a comprehensive overview of all top-level keys and their purpose.

on

is a mandatory top-level key that determines when to initiate the Workflow, such as when pushing code, opening a pull request, or creating an issue.

Workflows in GitHub can be triggered by:

• Repository events: Like commits, pull requests, or issue creation, e.g. on: create or on: [push, fork].

• External events: Webhooks or APIs that signal GitHub to start a Workflow.

• Scheduled times: Set Workflows to run at regular intervals (e.g., nightly builds using cron syntax).

• Manual triggers: Start a Workflow manually from the GitHub UI.

We recommend to read about triggering events if you want to learn more about them.

jobs

is a top-level key that holds a dictionary of jobs, each specify an environment along with a sequence of tasks to perform.

Jobs can be arbitrarily named (i.e. the key an be set freely). They will run in parallel by default and each job can contain a collection of steps that are executed sequentially.

Some of the more relevant keys a job might contain:

• runs-on: Defines the type of machine (or VM) to run this job on.

• steps: Sequence of tasks to perform.

• needs: Establishes dependencies with other jobs.

• if: Allows to specify conditions to prevent a job from running.

• permissions: Modify the default permissions granted to the GITHUB_TOKEN

jobs might look like this:

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        uses: actions/checkout@v3
      - name: Print a greeting
        run: |
          echo ${{ github.repository }}

A full list of keys a job accepts can be found here.

steps

is a mandatory key within a job. steps defines a list of individual commands or actions to be executed as part of a job.

Steps can either run shell commands or use pre-built GitHub Actions to perform specific tasks.

Some keys an entry in steps might contain:

The keys run and uses cannot be used together.

• if: Allows to specify conditions to prevent a step from running.

• run: A string that will be run as a shell command.

• uses: Specifies a pre-defined action to run.

Minimal Automation Script

An minimal exemplary Workflow file could look like this:

# .github/workflows/hello_world.yml

on:
  push:
    branches:
      - main

jobs:
  say_hello:
    steps:
      - uses: actions/checkout@v2
      - run: echo "Hello, World!"

How to Trigger an Automation Script

In GitHub, a variety of events can trigger a Workflow, and each Workflow (i.e., each YAML file located in .github/workflows/) must include the top-level key on, which specifies the events that will activate this Workflow.

Additionally, individual jobs (i.e., entries under the top-level key jobs) and specific steps (i.e., elements within the steps key of a job) can utilize the if key to set conditions for skipping that particular step or job. However, it’s important to note that if a Workflow runs and a job is skipped, its status will be updated to skipped.

A conditional job could look like this:

name: example-workflow
on: [push]
jobs:
  conditional-greet:
    if: ${{ github.repository == 'myuser/myrepo' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Howdie!"

How to Define Variables for an Automation Script

GitHub allows the use of variables in Workflows definitions and provides a variety of context variables that can be accessed using the ${{...}} syntax.

Some important contextual variables include:

• github: Provides metadata about the Workflow run, Repository, and event that triggered the Workflow, etc.

  • E.g. github.event_name indicates the name of the event that triggered the Workflow (e.g. push, pull_request, etc.) while github.repository provides the name of the Repository.

• vars: Contains variables defined at the Repository, Organization or Environment level. These variables can be set via the Web-UI.

  • For instance, vars.my_variable represents a variable named my_variable.

Warning

Sensitive data should be stored outside of GitHub! secrets is the only half-way acceptable place to store sensitive data!

• secrets: contains the names and values of secrets defined for the Repository, Organization or Environment. Secrets are handled in a specific way by GitHub and can be set via the Web-UI.

  • For example, secrets.TOKEN refers to a secret named TOKEN.

Refer to the official documentation for a complete overview of GitHub’s contextual variables and their availability.

Inspect context variables

Context variables are, as their name suggests, context-dependent, and it may not always be clear what values are actually defined when a Workflow runs.

A straightforward way to debug context variables is to simply have their content returned by a job that runs in specific context:

jobs:
  list-github-context:
    runs-on: ubuntu-latest
    steps:
      - name: Print GitHub Context Variables
        env:
          GITHUB_CONTEXT: ${{ toJSON(github) }}
        run: |
          echo "GitHub context variables:"
          echo "$GITHUB_CONTEXT" | jq '.'