github-actions-pipeline-builder.md
11,6 KB • MD • jun. 18, 2026 06:54
---
name: github-actions-pipeline-builder
description: Build production CI/CD pipelines with GitHub Actions. Implements matrix builds, caching, deployments, testing, security scanning. Use for automated testing, deployments, release workflows.
Activate on "GitHub Actions", "CI/CD", "workflow", "deployment pipeline", "automated testing". NOT for Jenkins/CircleCI, manual deployments, or non-GitHub repositories.
allowed-tools: Read,Write,Edit,Bash
metadata:
category: DevOps & Site Reliability
tags:
- github
- actions
- pipeline
- github-actions
- ci/cd
pairs-with:
- skill: devops-automator
reason: GitHub Actions is one of the primary CI/CD platforms that DevOps automation targets
- skill: docker-containerization
reason: Container builds and registry pushes are the most common GitHub Actions workflow steps
- skill: git-workflow-expert
reason: Git branching strategies determine pipeline trigger rules and deployment gates
- skill: test-automation-expert
reason: Automated test suites run as CI pipeline stages with matrix builds and caching
---
# GitHub Actions Pipeline Builder
Expert in building production-grade CI/CD pipelines with GitHub Actions that are fast, reliable, and secure.
## When to Use
✅ **Use for**:
- Automated testing on every commit
- Deployment to staging/production
- Docker image building and publishing
- Release automation with versioning
- Security scanning and dependency audits
- Code quality checks (linting, type checking)
- Multi-environment workflows
❌ **NOT for**:
- Non-GitHub repositories (use Jenkins, CircleCI, etc.)
- Complex pipelines better suited for dedicated CI/CD tools
- Self-hosted runners (covered in advanced patterns)
## Quick Decision Tree
```
Does your project need:
├── Testing on every PR? → GitHub Actions
├── Automated deployments? → GitHub Actions
├── Matrix builds (Node 16, 18, 20)? → GitHub Actions
├── Secrets management? → GitHub Actions secrets
├── Multi-cloud deployments? → GitHub Actions + OIDC
└── Sub-second builds? → Consider build caching
```
---
## Technology Selection
### GitHub Actions vs Alternatives
**Why GitHub Actions in 2024**:
- **Native integration**: No third-party setup
- **Free for public repos**: 2000 minutes/month for private
- **Matrix builds**: Test multiple versions in parallel
- **Marketplace**: 10,000+ pre-built actions
- **OIDC support**: Keyless cloud deployments
**Timeline**:
- 2019: GitHub Actions released
- 2020: Became standard for OSS projects
- 2022: OIDC support for secure cloud auth
- 2024: De facto CI/CD for GitHub repos
### When to Use Alternatives
| Scenario | Use | Why |
|----------|-----|-----|
| Self-hosted GitLab | GitLab CI | Native integration |
| Complex enterprise workflows | Jenkins | More flexible |
| Bitbucket repos | Bitbucket Pipelines | Native integration |
| Extremely large repos (>10GB) | BuildKite | Better for monorepos |
---
## Common Anti-Patterns
### Anti-Pattern 1: No Dependency Caching
**Novice thinking**: "Install dependencies fresh every time for consistency"
**Problem**: Wastes 2-5 minutes per build installing unchanged dependencies.
**Wrong approach**:
```yaml
# ❌ Slow: Downloads all dependencies every run
- name: Install dependencies
run: npm install
```
**Correct approach**:
```yaml
# ✅ Fast: Cache dependencies, only download changes
- name: Cache node_modules
uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- name: Install dependencies
run: npm ci # Faster than npm install
```
**Impact**: Reduces install time from 3 minutes → 30 seconds.
**Timeline**:
- Pre-2020: Most workflows had no caching
- 2020+: Caching became standard
- 2024: Setup actions include built-in caching
---
### Anti-Pattern 2: Duplicate YAML (No Matrix Builds)
**Problem**: Copy-paste workflows for different Node versions.
**Wrong approach**:
```yaml
# ❌ Duplicated workflows
jobs:
test-node-16:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 16
- run: npm test
test-node-18:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
- run: npm test
test-node-20:
# ... same steps again
```
**Correct approach**:
```yaml
# ✅ DRY: Matrix build
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [16, 18, 20]
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- run: npm ci
- run: npm test
```
**Benefits**: 66% less YAML, tests run in parallel.
---
### Anti-Pattern 3: Secrets in Code
**Problem**: Hardcoded API keys, tokens visible in repo.
**Symptoms**: Security scanner alerts, leaked credentials.
**Correct approach**:
```yaml
# ✅ Use GitHub Secrets
- name: Deploy to production
env:
API_KEY: ${{ secrets.PRODUCTION_API_KEY }}
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY }}
run: |
./deploy.sh
```
**Setting secrets**:
1. Repo Settings → Secrets and variables → Actions
2. New repository secret
3. Name: `PRODUCTION_API_KEY`, Value: `sk-...`
**Timeline**:
- Pre-2022: Some teams committed .env files
- 2022+: GitHub secret scanning blocks commits with keys
- 2024: OIDC eliminates need for long-lived credentials
---
### Anti-Pattern 4: No Failure Notifications
**Problem**: CI fails silently, team doesn't notice for hours.
**Correct approach**:
```yaml
# ✅ Slack notification on failure
- name: Notify on failure
if: failure()
uses: slackapi/slack-github-action@v1
with:
payload: |
{
"text": "❌ Build failed: ${{ github.event.head_commit.message }}",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Build Failed*\n<${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View logs>"
}
}
]
}
env:
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
```
---
### Anti-Pattern 5: Running All Tests on Every Commit
**Problem**: Slow feedback loop (10+ minute test suites).
**Symptom**: Developers avoid committing frequently.
**Correct approach**:
```yaml
# ✅ Fast feedback: Run subset on PR, full suite on merge
on:
pull_request:
branches: [main]
push:
branches: [main]
jobs:
quick-tests:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- run: npm run test:unit # Fast: 2 minutes
full-tests:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- run: npm run test # Slow: 10 minutes (unit + integration + e2e)
```
**Alternative**: Use changed-files action to run only affected tests.
---
## Implementation Patterns
### Pattern 1: Basic CI Pipeline
```yaml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: 18
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run linter
run: npm run lint
- name: Run type check
run: npm run typecheck
- name: Run tests
run: npm test
- name: Build
run: npm run build
```
### Pattern 2: Multi-Environment Deployment
```yaml
name: Deploy
on:
push:
branches:
- main # → staging
- production # → production
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ github.ref_name }} # staging or production
steps:
- uses: actions/checkout@v3
- name: Deploy to ${{ github.ref_name }}
run: |
if [ "${{ github.ref_name }}" == "production" ]; then
./deploy.sh production
else
./deploy.sh staging
fi
env:
API_KEY: ${{ secrets.API_KEY }}
DATABASE_URL: ${{ secrets.DATABASE_URL }}
```
### Pattern 3: Release Automation
```yaml
name: Release
on:
push:
tags:
- 'v*' # Trigger on version tags (v1.0.0)
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write # Required for creating releases
steps:
- uses: actions/checkout@v3
- name: Build artifacts
run: npm run build
- name: Create GitHub Release
uses: softprops/action-gh-release@v1
with:
files: |
dist/**
body: |
## What's Changed
See CHANGELOG.md for details.
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Publish to npm
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```
### Pattern 4: Docker Build & Push
```yaml
name: Docker
on:
push:
branches: [main]
jobs:
build-and-push:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
- name: Login to DockerHub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
push: true
tags: |
myapp:latest
myapp:${{ github.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max
```
---
## Production Checklist
```
□ Dependency caching configured
□ Matrix builds for multiple versions
□ Secrets stored in GitHub Secrets (not code)
□ Failure notifications (Slack, email, etc.)
□ Deploy previews for pull requests
□ Staging → Production promotion workflow
□ Release automation with versioning
□ Docker layer caching enabled
□ CODEOWNERS file for required reviews
□ Branch protection rules enabled
□ Status checks required before merge
□ Security scanning (Dependabot, CodeQL)
```
---
## When to Use vs Avoid
| Scenario | Use GitHub Actions? |
|----------|---------------------|
| GitHub-hosted repo | ✅ Yes |
| Need matrix builds | ✅ Yes |
| Deploying to AWS/GCP/Azure | ✅ Yes (with OIDC) |
| GitLab repo | ❌ No - use GitLab CI |
| Extremely large monorepo | ⚠️ Maybe - consider BuildKite |
| Need GUI pipeline builder | ❌ No - use Jenkins/Azure DevOps |
---
## References
- `/references/advanced-caching.md` - Cache strategies for faster builds
- `/references/oidc-deployments.md` - Keyless cloud authentication
- `/references/security-hardening.md` - Security best practices
## Scripts
- `scripts/workflow_validator.ts` - Validate YAML syntax locally
- `scripts/action_usage_analyzer.ts` - Find outdated actions
## Assets
- `assets/workflows/` - Ready-to-use workflow templates
---
**This skill guides**: CI/CD pipelines | GitHub Actions workflows | Matrix builds | Caching | Deployments | Release automation