Manual deployments are the #1 source of production incidents. After automating CI/CD pipelines for 40+ engineering teams, I'm sharing the exact architecture I use — from code commit to live production — using GitHub Actions. This tutorial gives you a real, production-ready pipeline, not just a hello-world demo.
What We'll Build
By the end of this guide you'll have a pipeline that automatically:
- Runs unit tests and linting on every pull request
- Builds and pushes a Docker image to a container registry
- Deploys to staging on merge to
develop - Deploys to production on merge to
mainwith manual approval - Sends Slack/email notifications on success and failure
- Rolls back automatically if health checks fail
Step 1: Repository Structure
First, organize your repository to support CI/CD cleanly:
your-app/
├── .github/
│ └── workflows/
│ ├── ci.yml # Runs on every PR
│ └── deploy.yml # Runs on main/develop merge
├── src/
├── tests/
├── Dockerfile
└── docker-compose.yml
Step 2: CI Workflow (Pull Request Checks)
Create .github/workflows/ci.yml. This runs on every PR, blocking merge if anything fails:
name: CI — Test & Lint
on:
pull_request:
branches: [main, develop]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run linting
run: npm run lint
- name: Run unit tests
run: npm test -- --coverage
- name: Upload coverage
uses: codecov/codecov-action@v4
Pro Tip: Set branch protection rules to require this CI workflow to pass before merging. This prevents broken code from ever reaching main. Go to Settings → Branches → Add rule → "Require status checks".
Step 3: Docker Build & Push
Add a job to build your Docker image and push to Docker Hub or Amazon ECR:
docker:
runs-on: ubuntu-latest
needs: test
if: github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_TOKEN }}
- uses: docker/build-push-action@v5
with:
push: true
tags: yourorg/app:${{ github.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max
Security: Never hardcode credentials. Use GitHub Secrets (Settings → Secrets → Actions). Tag images with the Git SHA for full traceability — never overwrite the
latest tag in production.Step 4: Environment-Based Deployment
Deploy to staging automatically, but gate production behind a manual approval:
deploy-staging:
needs: docker
environment: staging
runs-on: ubuntu-latest
steps:
- name: Deploy to staging
run: |
ssh deployer@staging.yourapp.com \
"docker pull yourorg/app:${{ github.sha }} && \
docker-compose up -d"
deploy-production:
needs: deploy-staging
environment:
name: production
url: https://yourapp.com
runs-on: ubuntu-latest
# This requires manual approval in GitHub UI
steps:
- name: Deploy to production
run: ./scripts/deploy.sh production ${{ github.sha }}
Step 5: Health Check & Automatic Rollback
Always verify your deployment succeeded. If the health check fails, automatically roll back:
health-check:
needs: deploy-production
runs-on: ubuntu-latest
steps:
- name: Wait for startup
run: sleep 20
- name: Health check
id: health
run: |
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
https://yourapp.com/health)
echo "status=$STATUS" >> $GITHUB_OUTPUT
[ "$STATUS" = "200" ] || exit 1
- name: Rollback on failure
if: failure()
run: ./scripts/rollback.sh ${{ github.sha }}
Step 6: Slack Notifications
Keep your team informed automatically:
- name: Notify Slack
if: always()
uses: slackapi/slack-github-action@v1.25.0
with:
payload: |
{
"text": "${{ job.status == 'success' && '✅' || '❌' }} Deploy ${{ job.status }}!\nApp: yourapp.com\nCommit: ${{ github.sha }}"
}
env:
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
Full Pipeline Summary
PR Opens
Test + Lint
Docker Build
Staging
Approval
Production
Common Pitfalls to Avoid
- Using
latesttags — always use image digest or commit SHA - No secrets rotation — rotate credentials quarterly and use OIDC where possible
- Skipping staging — every deploy must pass through a staging environment
- No rollback plan — define and test your rollback procedure before go-live