/
GitHub Actions Best Practices

GitHub Actions Best Practices

Owned by Ned Batchelder (Deactivated)
Last updated: Nov 17, 2023 by Brian Smith
5 min read

Feel free to comment or share your learning.

Contents

Glossary

  • Workflow: A collection of jobs defined in a .yml file, with associated triggers (on:).

  • Job: A named set of steps, run in a certain environment (runs-on:).

  • Step: A task within a job.

Style

General

  • 2-space indents. Use .editorconfig from edx-lint.

  • The file extension should be .yml, not .yaml.

  • Use YAML dash-syntax for lists, even for one-item lists. This makes it easier to add/remove items without adjusting other lines.

Workflows

  • Give every workflow a name. Use title casing: Nightly Unit Tests. Keep the name short, 4-5 words or less. Any longer, and GitHub will truncate them in the UI like the PR check interface.

  • Name the workflow file the same as the workflow name, except lower case with dashes: nightly-unit-tests.yml

Jobs

  • Use snake_case for the job’s ID. For example python_38_unit_tests:

  • Give every job a name. Use sentence casing: Python 3.8 unit tests. Keep the name short, 4-5 words or less

  • Leave a blank line between jobs.

Steps

  • Give every step a name. Use sentence casing: Build and upload the results report. These can be longer than 5 words.

  • Leave a blank line between steps.

Commands

  • Always use YAML multi-line strings for shell commands, to simplify quoting:

    • Instead of this:

      • # BAD! This won't parse! run: bash -c "./do.py --extra \"{'offset': '2023-06-14T04:20:00'}\""

    • Use this:

      • run: | bash -c "./do.py --extra \"{'offset': '2023-06-14T04:20:00'}\""

Example

name: "Nightly Unit Tests" on: push: branches: - "**/*nightly*" schedule: # Run at 2:22am early every morning Eastern time (6/7:22 UTC) # https://crontab.guru/#22_7_%2a_%2a_%2a - cron: "22 7 * * *" workflow_dispatch: defaults: run: shell: bash permissions: contents: read