Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,249 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user