GitHub Workflow Patterns

Deployment Workflow Template

For static site deployment to GitHub Pages:

name: Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Critical settings:
- permissions: Required for GitHub Pages deployment
- concurrency: Prevents simultaneous deployments
- cache: 'npm': Caches dependencies automatically

Caching Strategy

Automatic Dependency Caching

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # Automatic npm cache

How it works: Caches node_modules based on package-lock.json hash.

When cache is invalidated: When package-lock.json changes.

Build Output Caching

For expensive build steps:

- uses: actions/cache@v3
  with:
    path: |
      .next/cache
      .astro/cache
    key: ${{ runner.os }}-build-${{ hashFiles('**/*.ts', '**/*.tsx') }}
    restore-keys: |
      ${{ runner.os }}-build-

Use when: Build takes >1 minute and can use previous artifacts.

Optimization Checklist

• [ ] Dependencies cached (cache: 'npm')
• [ ] Build artifacts cached if applicable
• [ ] Fast jobs run first (lint before build)
• [ ] Jobs run in parallel where possible
• [ ] Fail fast enabled for matrix builds
• [ ] Minimal checkout depth if history not needed

Conditional Execution

Run on specific paths

on:
  push:
    paths:
      - 'src/**'
      - 'content/**'
      - 'package.json'

Use when: Large repo, only want to run on relevant changes.

Skip CI

Include [skip ci] in commit message to skip workflow.

Debugging Workflows

Enable Debug Logging

Repository Settings → Secrets → Add:
- ACTIONS_RUNNER_DEBUG: true
- ACTIONS_STEP_DEBUG: true

Print Context

- name: Debug
  run: |
    echo "Event: ${{ github.event_name }}"
    echo "Ref: ${{ github.ref }}"
    echo "SHA: ${{ github.sha }}"

Common Issues

Cache not restoring:
- Verify cache key matches
- Check if cache exists (Actions tab → Cache management)
- Ensure paths are correct

Deployment fails:
- Check permissions are set correctly
- Verify output directory exists and contains files
- Check Pages settings (should be "GitHub Actions")

Build works locally, fails in CI:
- Check Node version matches
- Verify all dependencies in package.json
- Check for environment-specific code

Performance Targets

Aim for:
- Total workflow time: <5 minutes
- Cache hit rate: >80% for dependencies
- Build time: <2 minutes (incremental caching helps)

Measure: Actions tab shows timing breakdown per step.

Matrix Builds

For testing across versions:

strategy:
  matrix:
    node: [18, 20]
    os: [ubuntu-latest, windows-latest]
  fail-fast: true  # Stop all on first failure

runs-on: ${{ matrix.os }}
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}

Use when: Need to verify compatibility across versions/platforms.
Avoid when: Only deploying to single environment (use single config).

Secrets Management

Using Secrets

env:
  API_KEY: ${{ secrets.API_KEY }}

Add secrets: Repository Settings → Secrets and variables → Actions

Never log secrets: GitHub automatically masks secrets in logs, but avoid echo $SECRET.

Workflow Triggers

Common Patterns

# On push to main
on:
  push:
    branches: [main]

# On PR to main
on:
  pull_request:
    branches: [main]

# Manual trigger
on:
  workflow_dispatch:

# Scheduled (cron)
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday

Job Dependencies

Sequential Jobs

jobs:
  build:
    runs-on: ubuntu-latest
    steps: [...]

  deploy:
    needs: build  # Wait for build
    runs-on: ubuntu-latest
    steps: [...]

Parallel Jobs

jobs:
  lint:
    runs-on: ubuntu-latest
    steps: [...]

  test:
    runs-on: ubuntu-latest
    steps: [...]

  # Both run simultaneously

Artifacts

Upload Build Output

- uses: actions/upload-artifact@v3
  with:
    name: build
    path: dist/
    retention-days: 7

Download in Another Job

- uses: actions/download-artifact@v3
  with:
    name: build
    path: dist/

Use when: Passing data between jobs.

Best Practices

1. Fail fast: Put quick checks (lint, type check) before slow builds
2. Cache aggressively: Cache dependencies and build artifacts
3. Minimal permissions: Only grant necessary permissions
4. Pin action versions: Use @v4 or commit SHAs
5. Clear job names: Use descriptive names for debugging
6. Monitor performance: Track workflow duration over time

Quick Wins

Already fast? These optimizations have diminishing returns:
- Parallel jobs (if you only have 2-3 steps)
- Build caching (if builds are <30 seconds)
- Matrix builds (if you only deploy to one environment)

Focus on:
- Dependency caching (always beneficial)
- Fail fast (catch errors early)
- Clear error messages (faster debugging)

Repository Settings

For GitHub Pages deployment:
1. Settings → Pages
2. Source: "GitHub Actions"
3. No branch configuration needed

For custom domain:
1. Add CNAME file to output directory
2. Configure DNS
3. Add custom domain in Pages settings