Skip to content

Github Actions🔗

Included in free plans for public repositories and in paid plans for private repositories, Github Actions allow us automation on our repositories (e.g: building a doc, check code style, creating a release, auto-label PRs, deploy, ...).

Core Concepts🔗

Discover the core concepts

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.

— About workflows

Info

Workflows are auto-discovered by Github inside .github/workflows. Nothing to configure!

Triggers🔗

i.e: what triggers the workflow.

Commit / Push to branches🔗

e.g: on commit on master:

1
2
3
4
5
6
7
8
# .github/workflows/my-workflow.yaml
name: My Workflow
on:
  push:
    branches:
      - master

# [...]

PR / Issues🔗

e.g: on opening a pull request:

1
2
3
4
5
6
7
8
# .github/workflows/my-workflow.yaml
name: My Workflow
on:
  pull_request:
    branches:
      - master

# [...]

Scheduled🔗

e.g: on schedule, every 15 minuntes:

1
2
3
4
5
6
7
8
# .github/workflows/my-workflow.yaml
name: My Workflow
on:
  schedule:
    # Every 15 minutes:
    - cron:  '*/15 * * * *'

# [...]

Manually🔗

e.g: on manuel trigger

  • by dispatching a workflow event through Github API:
1
2
3
4
5
6
# .github/workflows/my-workflow.yaml
name: My Workflow
on:
  workflow_dispatch:

# [...]

Tip

Worklows configured to be triggered on workflow event can also be triggered directly from the Github UI

Note

It can also be used to trigger workflows from other workflows, for instance by using GitHub Action for Dispatching Workflows

Note

Providing the workflow name in the yaml file allows to use it to reference the workflow as {workflow_id} instead of the path in the repository or its id.

Tip

In the Elao organisation, a Github App allows to trigger workflows for you programmatically, using its own identity (otherwise you need to configure a Personal Access Token, which would allow access to any of your repositories). Your repository must be added to the app configuration in order for this to work.
See how it is used for Clim'app deploy.
The Github App private key can be found in 1Password.

  • or by reacting to a repository custom event through Github API:
1
2
3
4
5
6
# .github/workflows/my-workflow.yaml
name: My Workflow
on:
  repository_dispatch: [my-event]

# [...]

Refs🔗

Jobs🔗

A set of steps that execute on the same runner. Jobs can either be executed in parallel or run sequentially, depending on the status of a previous job.

Secrets🔗

Secrets are encrypted environment variables that you create in a repository or organization. The secrets you create are available to use in GitHub Actions workflows.

The syntax to use secrets in workflows is:

1
2
3
4
5
6
7
8
jobs:
  build:
    steps:
      - name: Hello world action
        with: # Set the secret as an input of your step
          super_secret: ${{ secrets.SuperSecret }}
        env: # Or as an environment variable
          SUPER_SECRET: ${{ secrets.SuperSecret }}

Tip

The ${{ secrets.GITHUB_TOKEN }} is a special secret auto provided by Github with a token with repo-rights.

Samples🔗

Auto label PRs🔗

based on the directory:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# .github/workflows/autolabel-prs.yml
name: Auto label Pull Requests
on:
  - pull_request

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v3-preview
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

and in a .github/labeler.yml file:

1
2
3
4
Back:
  - src/**/*
Front:
  - assets/**/*

Projects using it:

Checkout code, build & deploy🔗

e.g: building a MkDocs site and deploying to GH Pages on commit / merge on master branch:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
name: Deploy Elao Cookbooks to GH Pages
on:
  push:
    branches:
      - master

jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout master
        uses: actions/checkout@v2

      - name: Deploy docs
        # https://github.com/mhausenblas/mkdocs-deploy-gh-pages
        uses: mhausenblas/mkdocs-deploy-gh-pages@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Projects using it:

Call a Makefile target🔗

1
2
3
4
5
6
7
8
9
# [...]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # [...]
      - name: Do my thing
        run: make it do it harder better faster stronger

Projects using it:

Commit changes🔗

Using EndBug/add-and-commit Github action:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# [...]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # Make changes...
      # [...]
      # https://github.com/EndBug/add-and-commit
      - name: Commit & push changes
        uses: EndBug/add-and-commit@v4
        with:
          author_name: GitHub Actions Bot
          author_email: actions@github.com
          message: '[AUTO] By Github Actions: generate some things'
          add: "docs/" # to only add some specific file changes
          ref: master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Info

Whenever pushing a commit from a Github action when using the special secrets.GITHUB_TOKEN as above, the new commit won't trigger a new build, hence avoiding infinite loop between Github actions.

Projects using it:

Adding a system PATH🔗

See Adding a system path official doc

Skip a workflow under some circonstances🔗

A whole workflow can be skipped under advanced circonstances if all its jobs are skipped.

See jobs.\<job_id>.if

In this example, I'd like to avoid triggering tests for draft or "WIP" labelled PRs:

1
2
3
4
5
6
jobs:
  test:
    name: 'Test'
    runs-on: ubuntu-latest
    # Do not run on WIP or Draft PRs
    if: "!github.event.pull_request || (!contains(github.event.pull_request.labels.*.name, 'WIP') && github.event.pull_request.draft == false)"

Timeout🔗

Please provide sensible timeout values to your heavy workflows!
It can either be set on job, steps, or both.

References🔗

Actions🔗

Cache🔗

The actions/cache action allows to cache files to be reused across your jobs and workflows.
Main use-cases are to cache Composer and NPM dependencies. See Implementation Examples

Cancel previous builds🔗

The cancel-workflow-action action allows to automatically cancels previous builds still running, in case you amended or push new commits to your branch, allowing to save some Github actions-minutes.

Debug workflows, actions & runner🔗

  • debugging-with-tmate stops your workflow and expose a public URL and SSH connection you can use to directly inspect the runner.
    ⚠ Don't forget to cancel your workflow once you're done. Otherwise, it might run indefinitely...

  • dump-context allows to dump the whole context to the output in a step (secrets are still hidden).

Advanced workflow configuration🔗

The variable-mapper actions allows to configure your workflow env vars in one step using a JSON for mapping env vars on a discriminator key.

It is especially useful to configure env vars to use depending on the target environment, when performing a relase or deploy.

See how it is used for Clim'app deploy for instance.

Create Github deployments🔗

The deployment-action & deployment-status actions allows to contact the Github API to create deployment entities easily from your workflows.

See how it is used for Clim'app deploy for instance.

Configure a SSH key and SSH agent🔗

The webfactory-ssh-agent actions allows to configure a SSH private key and SSH agent, in order to fetch from private repositories or deploy to a server.

See how it is used for Clim'app deploy for instance.

Troubleshooting🔗

My steps 'if' statement does not work🔗

⚠️ If your if expression does not contain any of the status functions it will automatically result with success().

— Job status check functions

Given:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
steps:
  - name: Install dependencies & setup project
    id: deps
    run: make install@integration

  - name: Lint Twig
    if: always() && steps.deps.outcome == 'success' # <- not using `always()` would skip the if in favor of `success()`
    run: make lint.twig@integration

  - name: Lint Yaml
    if: always() && steps.deps.outcome == 'success'
    run: make lint.yaml@integration

If the second and third step omits the always() call here, the whole if will not be interpreted and replaced by success().
In this example, this would result into the third step not to be executed if the second failed. With the always() call, the second part will properly be interpreted, so the 3rd step will run even if the 2nd failed, as soon as the deps step succeeded.

Last update: December 20, 2024