GitHub Workflow
Write clear, minimal GitHub Actions workflow files.
Naming Guidelines
Do NOT name
- •
runsteps that are self-explanatory from the command itself - •
usessteps for common, obvious actions like:- •
actions/checkout - •
actions/setup-node - •
oven-sh/setup-bun - •
pnpm/action-setup - •
actions/cache
- •
DO name
- •
usessteps withactions/github-script(explain what the script does) - •Complex multi-line shell scripts (summarize the purpose)
- •Steps where the intent is not obvious from the code
Examples
Good
yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun run build
- run: bun test
- name: Post build status to Slack
uses: actions/github-script@v7
with:
script: |
const webhook = process.env.SLACK_WEBHOOK;
// ... complex logic
Bad
yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Setup Bun
uses: oven-sh/setup-bun@v2
- name: Install dependencies
run: bun install
- name: Build project
run: bun run build
- name: Run tests
run: bun test
Best Practices
- •Pin action versions with full SHA or major version tag (
@v4, not@main) - •Use
workflow_dispatchfor manual triggers when useful - •Set appropriate
permissionsto follow least privilege - •Use
concurrencyto cancel redundant runs - •Prefer
${{ github.token }}over PAT when possible - •Avoid emoji in workflow names and step names
- •Use
$GITHUB_STEP_SUMMARYto output execution results in Markdown format - •Avoid obvious comments; only add comments to explain complex logic
Step Summary Example
yaml
- name: Report test results
run: |
echo "## Test Results" >> $GITHUB_STEP_SUMMARY
echo "| Suite | Passed | Failed |" >> $GITHUB_STEP_SUMMARY
echo "|-------|--------|--------|" >> $GITHUB_STEP_SUMMARY
echo "| Unit | 42 | 0 |" >> $GITHUB_STEP_SUMMARY