gh-hopeoverture-worldbuilding-app-skills-plugins-github-actions-ci-workflow/skills/github-actions-ci-workflow/references/github-actions-best-practices.md

GitHub Actions Best Practices

Workflow Optimization

Caching Strategies

1. Dependency Caching

   • Always cache package manager dependencies
   • Use lock file hashes as cache keys
   • Include fallback restoration keys for partial matches
   • Example: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

2. Build Artifact Caching

   • Cache framework-specific build directories (.next/cache, .nuxt, etc.)
   • Include source file hashes in cache key for invalidation
   • Use separate caches for different build targets

3. Cache Size Management

   • Keep cache sizes under 10GB per repository
   • Regularly clean up unused caches
   • Split large caches into multiple smaller caches

Job Parallelization

1. Matrix Builds

   • Test across multiple Node.js versions
   • Run tests in parallel across different OS
   • Split test suites into separate jobs

2. Job Dependencies

   • Use needs to create job dependency chains
   • Run independent jobs in parallel
   • Share artifacts between dependent jobs

Performance Tips

1. Reduce Checkout Time

   • Use shallow clones: fetch-depth: 1
   • Only checkout when necessary
   • Skip submodules if not needed

2. Optimize Installation

   • Use frozen lockfiles to skip dependency resolution
   • Enable package manager caching
   • Consider using pnpm for faster installs

3. Conditional Execution

   • Skip jobs based on file changes using paths filter
   • Use if conditions to skip unnecessary steps
   • Exit early when possible

Security Best Practices

Secrets Management

1. Store Sensitive Data Securely

   • Use GitHub Secrets for credentials
   • Never log secrets or expose in URLs
   • Use environment-specific secrets

2. Token Permissions

   • Use minimal required permissions
   • Prefer GITHUB_TOKEN over personal access tokens
   • Set explicit permissions in workflow file

3. Dependency Security

   • Pin action versions to specific commits
   • Enable Dependabot for action updates
   • Review third-party action code

Access Control

1. Environment Protection

   • Use environment protection rules for production
   • Require manual approval for critical deployments
   • Limit who can approve deployments

2. Branch Protection

   • Require status checks before merge
   • Enable branch protection rules
   • Prevent force pushes to main branch

Deployment Strategies

Preview Deployments

1. Per-PR Previews

   • Deploy each PR to unique preview URL
   • Comment URL on PR for easy access
   • Clean up when PR is closed

2. Preview Environment Configuration

   • Use separate environment variables
   • Connect to preview database/services
   • Enable debug logging

Production Deployments

1. Blue-Green Deployment

   • Deploy to new environment
   • Run smoke tests
   • Switch traffic when verified

2. Rollback Strategy

   • Keep previous deployment available
   • Tag successful deployments
   • Automate rollback on failure

3. Deployment Gates

   • Manual approval for production
   • Require successful CI before deploy
   • Schedule deployments during maintenance windows

Monitoring and Debugging

Workflow Monitoring

1. Status Badges

   • Add status badges to README
   • Monitor workflow success rates
   • Track deployment frequency

2. Notifications

   • Set up Slack/Discord notifications
   • Alert on deployment failures
   • Send deployment summaries

Debugging Workflows

1. Enable Debug Logging

   • Set ACTIONS_STEP_DEBUG secret to true
   • Use ::debug:: commands in scripts
   • Review workflow run logs

2. Test Locally

   • Use act to run workflows locally
   • Test workflow changes in fork
   • Validate YAML syntax before commit

Common Patterns

Monorepo Support

on:
  push:
    paths:
      - 'packages/frontend/**'
      - 'packages/shared/**'

Conditional Steps

- name: Deploy to production
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  run: npm run deploy

Reusable Workflows

jobs:
  call-reusable:
    uses: org/repo/.github/workflows/reusable.yml@main
    with:
      environment: production

Composite Actions

Create reusable composite actions for common tasks:

# .github/actions/setup-node/action.yml
name: Setup Node.js
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: '20'
        cache: 'npm'
    - run: npm ci
      shell: bash

Cost Optimization

1. Reduce Workflow Minutes

   • Cache aggressively
   • Skip unnecessary jobs
   • Use self-hosted runners for high-volume repos

2. Efficient Runners

   • Use smallest runner size that meets requirements
   • Self-host runners for private repos
   • Schedule resource-intensive jobs during off-peak

3. Artifact Management

   • Set appropriate retention days
   • Clean up old artifacts
   • Compress artifacts before upload

Framework-Specific Tips

Next.js

• Cache .next/cache directory
• Set NEXT_TELEMETRY_DISABLED=1
• Use next build output for deployment
• Configure ISR revalidation appropriately

Vite

• Cache node_modules/.vite directory
• Enable build caching
• Use vite build for production builds

Testing

• Run unit and integration tests in parallel
• Upload test results and coverage
• Use matrix builds for cross-browser testing
• Consider Playwright for E2E tests

Troubleshooting

Common Issues

1. Cache Not Restoring

   • Verify cache key matches
   • Check cache size limits
   • Ensure paths are correct

2. Permission Errors

   • Check GITHUB_TOKEN permissions
   • Verify repository settings
   • Review branch protection rules

3. Timeout Errors

   • Increase job timeout
   • Split into smaller jobs
   • Optimize dependencies

4. Build Failures

   • Check environment variables
   • Verify Node.js version
   • Review dependency compatibility