GitHub Workflow

Write clear, minimal GitHub Actions workflow files.

Naming Guidelines

Do NOT name

• run

  steps that are self-explanatory from the command itself

• uses

  steps for common, obvious actions like:

  • actions/checkout

  • actions/setup-node

  • oven-sh/setup-bun

  • pnpm/action-setup

  • actions/cache

DO name

• uses

  steps with

  actions/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

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

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_dispatch

  for manual triggers when useful
• Set appropriate

  permissions

  to follow least privilege
• Use

  concurrency

  to cancel redundant runs
• Prefer

  ${{ github.token }}

  over PAT when possible
• Avoid emoji in workflow names and step names
• Use

  $GITHUB_STEP_SUMMARY

  to output execution results in Markdown format
• Avoid obvious comments; only add comments to explain complex logic

Step Summary Example

- 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