GitHub Actions Best Practices
Feel free to comment or share your learning.
Contents
- 1 Contents
- 2 Glossary
- 3 Style
- 4 Help
- 5 Error Checking
- 6 Matrix
- 7 Security
- 8 Organization
- 9 Testing
- 10 Other advice
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
fromedx-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 lessLeave 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