250 lines
5.9 KiB
Markdown
250 lines
5.9 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
on:
|
|
push:
|
|
paths:
|
|
- 'packages/frontend/**'
|
|
- 'packages/shared/**'
|
|
```
|
|
|
|
### Conditional Steps
|
|
|
|
```yaml
|
|
- name: Deploy to production
|
|
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
|
|
run: npm run deploy
|
|
```
|
|
|
|
### Reusable Workflows
|
|
|
|
```yaml
|
|
jobs:
|
|
call-reusable:
|
|
uses: org/repo/.github/workflows/reusable.yml@main
|
|
with:
|
|
environment: production
|
|
```
|
|
|
|
### Composite Actions
|
|
|
|
Create reusable composite actions for common tasks:
|
|
|
|
```yaml
|
|
# .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
|