GitHub Actions Cheat Sheet // Manski's Dev Log

Documentation: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

Default Environment Variables: https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables

GitHub Context: https://docs.github.com/en/actions/learn-github-actions/contexts#github-context

Jobs #

Jobs run in parallel by default.

Run sequentially (use needs):


jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

See also:

Job Runners #

Defined by runs-on in a job:


runs-on: ubuntu-latest
runs-on: windows-latest
runs-on: macos-latest

The runners come with all sort of pre-installed software like .NET or PowerShell.

For the list, see: workflow log → Set up job → Runner Image → Included Software

See also:

Run Job even if Needed Job Failed #

By default, dependent jobs only run if their dependency jobs were successful.

Always run:


jobs:
  build-and-test:
    ...
  test-report:
    needs: build-and-test
    if: ${{ !cancelled() }}

Run if successful or specific step has failed:


jobs:
  build-and-test:
    outputs:
      run_tests_conclusion: ${{ steps.run_tests.conclusion }}
    ...
  test-report:
    needs: build-and-test
    if: ${{ !cancelled() && (needs.build-and-test.result == 'success' || needs.build-and-test.outputs.run_tests_conclusion == 'failure') }}

Triggers #

On push to main:


on:
  push:
    branches:
      - main

On pull requests:


on:
  pull_request:

Manually (see details):


on:
  workflow_dispatch:

Reusable workflows (see details):


on:
  workflow_call:

Don’t use the schedule trigger as this will cause the workflow to be disabled after 60 days of inactivity - and afterward the workflow must be manually reenabled.

See also:

Notifications #

Whether you’re notified about all action runs or just failures, is configured in the notification settings of your account - not on the workflow itself.

Capture Step Output #

Define it via:


      - name: Determine Hugo version
        id: hugo-version
        run: echo 'version=1.2.3' >> $GITHUB_OUTPUT

Use it via:


${{ steps.hugo-version.outputs.version }}

Security Considerations #

The permissions properties defines the permissions for the GITHUB_TOKEN. The default permission may be too permissive. So, it’s a good idea to reduce the necessary permissions as much as possible.
- Also, the default permission differ based on whether the workflow runs for a pull request from a fork or from the same repository.
- Note that a regular build and test workflow usually only needs the contents: read permission.
- For more details, see: https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token
For 3rd party actions (i.e. actions that don’t come from actions/) it’s recommended to use @sha rather than @tag. Reason: If the source repository gets hacked, the attacker can add malicious code (send secrets to they attacker’s server) and change the tag to the commit with the malicious code. If you pin a certain sha, the action is not vulnerable to this type of attack.
- Of course, with this you don’t automatically get newer (good) versions of the action. Make sure to subscribe the action for new releases.
- Technically, if the GITHUB_TOKEN permissions only include read permissions (and if you don’t have any other secrets in your repository), it’s not necessary to do this. But since nothing is every static, doing this even in this scenario is simply another safety net.