GitHub Actions

This document provides the conventions that we use to configure workflows and actions on GitHub Actions. Consistency are quite important as workflows may need to evolve over multiple generations.

Jobs are decomposed into actions that are as reusable as possible. These are located in .gitub/actions.

Workflows are as simple as possible and are meant to define a job that "just" chain actions together. Each workflow is defined in .github/workflows.

Conventions

We apply the following to ensure consistency:

Names are title cased.
Descriptions are single quoted. If a single quote is required, you should double it to escape it.
List of attributes, are ordered alphabetically. This ensures that the location of an additional attribute is predicable, which makes diff across generations easier to read.
The structure of a YAML file is well-defined, see below for examples.

Actions

Each action is defined in an action.yml located a sub-directory of .github/actions. If possible, additional assets such as configuration files should be located in the same sub-directory.

The basic structure of an action is as follows:

name: <short name>
description: <human readable description, single quoted>
inputs: <input attributes, oredered alphabetically>
outputs: <output attributes, ordered alphabetically>
runs:

Inputs/Outputs

Inputs are ordered alphabetically. Each input has the following attributes, default is optional.

inputs:
  attribute-1:
    description: <human readable description, single quoted>
    required: <true/false>
    default: <optional: default value, single quoted>
  attribute-2:
    description: <human readable description, single quoted>
    required: <true/false>

Description follows the same semantic as our configuration properties.

Action attributes can only be String. If a boolean value is used, it unfortunately has to be quoted (e.g. 'false') and treated accordingly.

Runs

The runs section defines the steps of the action, see the dedicated section.

Steps

A step can have multiple attributes, and we can’t list them all. Here are some examples based on our own usage.

Step referring to an action

steps:
  - name: <short name>
    id: <optional: identifier if reference to the step is necessary>
    if: <optional: step condition>
    uses: <action to use>
    with: <optional: list of input parameters, ordered alphabetically>
    env: <optional: list of environment variables, ordered alphabetically>

Bash-like step

steps:
  - name: <short name>
    id: <optional: identifier if reference to the step is necessary>
    if: <optional: step condition>
    shell: bash
    env: <optional: list of environment variables, ordered alphabetically>
    run: <command(s) to run>

Workflows

The basic structure of a workflow is as follows:

name:
on:
concurrency:
permissions:
jobs:

There are more settings available, but this document focuses on our own use.

Jobs

A job can have multiple attributes, and we can’t list them all. Here are some examples based on our own usage.

Job Defining Steps

jobs:
  <id>:
    name: <name>
    if: <optional: job condition>
    needs: <optiona: jobs that should have completed>
    runs-on:
    steps:

Job Referring to Another Workflow

jobs:
  <id>:
    name: <name>
    if: <optional: job condition>
    needs: <optiona: jobs that should have completed>
    uses: <path to the workflow>
    secrets: <optional: secrets, ordered alphabetically>
    with: <optional: input parameters, ordered alphabetically>