Complete Guide to CI/CD with GitHub Actions
Build CI/CD pipelines from scratch with GitHub Actions. Covers workflows, runners, matrix builds, caching, secrets, environments, deployment strategies, and reusable workflows.
Introduction
GitHub Actions is GitHub’s built-in CI/CD platform: it builds, tests, and deploys code directly from your repository, with no external CI server to run. This guide walks you through one real pipeline end to end — lint and test on every pull request, matrix builds across Node versions, dependency caching, a staging deploy, and a gated production release.
By the end you’ll have a complete ci.yml you can drop into a repository, plus the judgment to adapt it: which runner to pick, when a matrix is worth the minutes, how to keep secrets out of logs, and how to stop two deployments from racing each other.
The scope here is the path to production. For copy-paste workflow examples — matrices, secrets, environments, composite actions — see the GitHub Actions recipe. For pipeline theory (trunk-based flow, quality gates, promotion), the CI/CD Pipeline Guide covers the bigger picture.
How a Workflow Works
A workflow is a YAML file in .github/workflows/. Three concepts drive everything: events that trigger it (push, pull_request, schedule, workflow_dispatch), jobs that run in parallel by default on separate runners, and steps inside each job that execute sequentially — either a shell run or a published action via uses.
Simple CI workflow
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: Install dependencies
run: npm ci
- name: Lint
run: npm run lint
- name: Test
run: npm test -- --coverage
- name: Build
run: npm run build
- name: Upload coverage
uses: actions/upload-artifact@v4
with:
name: coverage
path: coverage/
Every piece here earns its place: npm ci installs from the lockfile for reproducible builds, cache: npm on setup-node saves 30-60 seconds per run, and upload-artifact keeps the coverage report downloadable from the run summary — handy when a test passes locally but fails in CI.
Triggers
on:
push:
branches: [main]
paths:
- "src/**"
- "tests/**"
- ".github/workflows/**"
pull_request:
types: [opened, synchronize, reopened]
schedule:
- cron: "0 2 * * *" # Daily at 2 AM UTC
workflow_dispatch: # Manual trigger
inputs:
environment:
description: "Target environment"
required: true
default: staging
type: choice
options:
- staging
- production
release:
types: [published]
The paths filter is the cheapest CI optimization around: a docs-only commit shouldn’t burn ten minutes of tests. pull_request.types defaults to opened, synchronize, reopened, so listing it explicitly is only needed for other types like ready_for_review. Two gotchas worth knowing: scheduled workflows stop running after 60 days of repository inactivity, and workflow_dispatch inputs let you build a manual “deploy to staging” button right in the Actions tab.
Runners
A runner is the machine your job executes on. GitHub-hosted runners are ephemeral VMs — you get a clean machine, it runs your job, and it’s destroyed. Standard ubuntu-latest gives you 4 vCPUs, 16 GB RAM, and 14 GB of SSD, which covers most builds comfortably.
jobs:
test:
runs-on: ubuntu-latest # 4 CPU, 16GB RAM, 14GB SSD
build:
runs-on: ubuntu-22.04 # Pin to specific version
macos:
runs-on: macos-latest # macOS for iOS builds
windows:
runs-on: windows-latest # Windows for .NET builds
Two things drive the choice. Cost: on private repositories, Actions minutes are billed differently per OS — Linux is the cheapest, Windows and macOS burn through your allowance several times faster. Reach for them only when the workload requires it. Tooling: pin ubuntu-22.04 if your build breaks on a newer image instead of trusting the -latest alias to stay put.
Larger runners (GitHub Enterprise)
jobs:
build:
runs-on: ubuntu-latest-large # 16 CPU, 64GB RAM
Self-hosted runners
jobs:
deploy:
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
- name: Deploy
run: ./deploy.sh
Self-hosted makes sense for private-network access, special hardware (GPUs, ARM), or workloads that exceed hosted specs. The trade-off is yours to carry: the machine isn’t ephemeral, so state leaks between runs, and running untrusted pull-request code on your own infrastructure is a real security risk — GitHub itself recommends against self-hosted runners on public forks.
Matrix Builds
A matrix expands one job definition into N parallel jobs across the combinations you declare. This runs tests on three Node versions and three operating systems, minus one exclusion, plus one extra experimental combination:
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18, 20, 22]
os: [ubuntu-latest, macos-latest, windows-latest]
exclude:
- os: macos-latest
node-version: 18
include:
- node-version: 20
os: ubuntu-latest
experimental: true
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
- run: npm ci
- run: npm test
Each combination is a full job with its own runner and its own minutes — a 3×3 matrix is nine jobs. That parallelism is the point, but it costs: a 10-minute suite becomes 90 billed minutes across the matrix. Matrix jobs are capped at 256 per run.
Fail-fast vs continue-on-error
strategy:
fail-fast: false # Don't cancel other matrix jobs on failure
max-parallel: 4 # Limit concurrent jobs
fail-fast: true (the default) cancels the whole matrix when one leg fails — fast feedback, but you lose signal about whether the failure is platform-specific. Set it to false during a compatibility migration, when you actually want to see all the failures at once. Don’t matrix your deploys: deployment is a sequential, environment-scoped concern, not a test-permutation one.
Caching
Caching restores files between runs so jobs don’t re-download the world. setup-node (and its siblings for Python, Go, Java) can cache the package-manager directory with one line:
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm # Automatically caches ~/.npm
For anything else, actions/cache gives you explicit control:
- name: Cache build output
uses: actions/cache@v4
with:
path: |
dist/
.cache/
key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-build-
The key is the cache identity: here it changes whenever package-lock.json does. When the exact key misses, restore-keys fall back to a prefix match — you get last week’s cache instead of nothing. Two limits to remember: a repository keeps at most 10 GB of caches (least-recently-used entries get evicted), and a cache untouched for 7 days is deleted.
Docker layer caching
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build and cache
uses: docker/build-push-action@v5
with:
context: .
push: false
tags: myapp:latest
cache-from: type=gha
cache-to: type=gha,mode=max
type=gha stores Docker layers in the same cache backend — rebuilding an image after a one-line change takes seconds instead of a full rebuild. Use mode=max to cache every layer, not just the final image’s.
Secrets, Variables and Permissions
Secrets are encrypted values injected at runtime — tokens, keys, credentials. Repository secrets are visible to every workflow in the repo; environment secrets are scoped to a deployment environment and can sit behind an approval gate. Variables (vars) are the same mechanism for non-sensitive config like URLs.
steps:
- name: Deploy to production
env:
API_KEY: ${{ secrets.API_KEY }}
DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
run: ./deploy.sh
jobs:
deploy:
runs-on: ubuntu-latest
environment: production # Requires approval
steps:
- name: Deploy
env:
PROD_TOKEN: ${{ secrets.PROD_TOKEN }}
run: ./deploy.sh
steps:
- name: Use variable
env:
API_URL: ${{ vars.API_URL }}
run: echo "Deploying to $API_URL"
GitHub masks registered secret values in logs automatically, but masking only works on the exact string — if you transform it (base64, concatenate, print per-line), the mask misses. Generate and mask dynamic values explicitly:
- name: Generate token
id: token
run: echo "value=$(openssl rand -hex 32)" >> $GITHUB_OUTPUT
- name: Use token
env:
TOKEN: ${{ steps.token.outputs.value }}
run: |
echo "::add-mask::$TOKEN"
curl -H "Authorization: Bearer $TOKEN" https://api.example.com
Restrict GITHUB_TOKEN
Every workflow gets a GITHUB_TOKEN that, by default on many repositories, has broad read/write scope. Cut it down to what the job needs:
permissions:
contents: read # checkout only
packages: write # only for the docker push job
id-token: write # only when using OIDC for cloud auth
Set permissions at the workflow level as a restrictive default, then widen per job. If you deploy to AWS or GCP, prefer OIDC federation over a long-lived cloud secret: id-token: write lets the job mint a short-lived credential against a cloud role — nothing static to leak or rotate.
Environments and Deployment Gates
Environments are named deployment targets with their own secrets, URLs, and protection rules. Chaining deploy-staging → deploy-production with needs gives you a promote pipeline where production never runs on a failed staging deploy:
jobs:
deploy-staging:
runs-on: ubuntu-latest
environment:
name: staging
url: https://staging.example.com
steps:
- uses: actions/checkout@v4
- name: Deploy
run: ./deploy.sh staging
deploy-production:
needs: deploy-staging
runs-on: ubuntu-latest
environment:
name: production
url: https://example.com
steps:
- uses: actions/checkout@v4
- name: Deploy
run: ./deploy.sh production
Required reviewers
Configure in GitHub: Settings → Environments → production → Required reviewers. The workflow pauses until approval — a human gate that shows up in the Actions UI as a pending deployment, with the environment URL attached for one-click verification. You can also add a wait timer to force a soak period before production picks up the job.
Job Dependencies and Concurrency
needs turns a flat list of jobs into a DAG. Lint and test run in sequence, then build waits for both, and deploy only fires on main:
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm run lint
test:
needs: lint # Wait for lint to pass
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm test
build:
needs: [lint, test] # Wait for both
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm run build
deploy:
needs: build
if: github.ref == 'refs/heads/main' # Only on main
runs-on: ubuntu-latest
steps:
- run: ./deploy.sh
Concurrency groups
The missing piece in most hand-rolled pipelines: without concurrency, two pushes to main run two deploys at once, and the last writer wins — possibly overwriting a newer deploy with an older one. A concurrency group serializes runs per branch:
concurrency:
group: deploy-${{ github.ref }}
cancel-in-progress: true
With cancel-in-progress: true, a new push cancels the stale run — ideal for CI where only the latest commit matters. For deployments use cancel-in-progress: false instead: the second deploy queues behind the first rather than killing a production release halfway through.
Reusable Workflows
When the same job logic shows up in several repos — or several workflows in one — extract it as a callable workflow:
# .github/workflows/test-suite.yml
name: Test Suite
on:
workflow_call:
inputs:
node-version:
required: false
type: number
default: 20
secrets:
API_KEY:
required: false
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: npm
- run: npm ci
- run: npm test
env:
API_KEY: ${{ secrets.API_KEY }}
Call it from another workflow as a whole job:
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
jobs:
test:
uses: ./.github/workflows/test-suite.yml
with:
node-version: 22
secrets:
API_KEY: ${{ secrets.API_KEY }}
deploy:
needs: test
runs-on: ubuntu-latest
steps:
- run: ./deploy.sh
A reusable workflow is a whole job — with its own runner, its own needs slot in the DAG. For sharing a few steps inside a job, the right tool is a composite action instead (see the reusable workflows recipe):
# .github/actions/setup-and-test/action.yml
name: 'Setup and Test'
description: 'Install deps and run tests'
inputs:
node-version:
required: false
default: '20'
test-command:
required: false
default: 'npm test'
runs:
using: 'composite'
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
- name: Install dependencies
shell: bash
run: npm ci
- name: Run tests
shell: bash
run: ${{ inputs.test-command }}
Callers use it as a single step: - uses: ./.github/actions/setup-and-test, with their own with: inputs. Composite actions run inside the caller’s job and share its filesystem — no extra runner is spawned.
Conditional Execution
if expressions gate steps or whole jobs on context, and status-check functions let you react to how earlier steps went:
steps:
- name: Only on main
if: github.ref == 'refs/heads/main'
run: ./deploy.sh
- name: Only on PRs
if: github.event_name == 'pull_request'
run: npm run test:e2e
- name: Skip on docs change
if: !contains(github.event.head_commit.message, '[skip ci]')
run: npm test
- name: On failure
if: failure()
run: ./notify-slack.sh
- name: Always run (cleanup)
if: always()
run: ./cleanup.sh
The two you’ll use most: failure() for notify-on-broken-build, and always() for cleanup that must run even after a failure — without it, the step is skipped by default. Note the subtlety: always() also runs on cancelled runs, which is why cancelled() exists as its own check.
Docker Build and Push
The full container flow — buildx for multi-layer caching, metadata-action for sane tags, GHCR as the registry:
jobs:
docker:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/metadata-action@v5
id: meta
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=ref,event=branch
type=sha,prefix={{branch}}-
type=raw,value=latest,enable={{is_default_branch}}
- uses: docker/build-push-action@v5
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
The tag strategy matters more than the build: every push gets a branch-sha12345 tag traceable back to the commit, latest only moves on the default branch, and packages: write is scoped to this job only. Deploying the image afterward is a separate concern — the deployment strategies guide covers rolling, blue-green, and canary patterns.
Putting It Together: A Complete Pipeline
Everything above composes into one workflow. This is the file you actually commit:
# .github/workflows/ci.yml
name: CI/CD
on:
push:
branches: [main]
paths: ["src/**", "tests/**", "package*.json", ".github/workflows/**"]
pull_request:
branches: [main]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
permissions:
contents: read
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run lint
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
node-version: [18, 20, 22]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm
- run: npm ci
- run: npm test
build:
needs: [lint, test]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: dist
path: dist/
retention-days: 7
deploy-staging:
needs: build
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
environment:
name: staging
url: https://staging.example.com
steps:
- uses: actions/download-artifact@v4
with:
name: dist
- run: ./deploy.sh staging
deploy-production:
needs: deploy-staging
runs-on: ubuntu-latest
environment:
name: production # Required reviewers gate this
url: https://example.com
steps:
- uses: actions/download-artifact@v4
with:
name: dist
- run: ./deploy.sh production
Read it as a story: every pull request gets lint plus a three-version test matrix. Main gets the same, then a build whose artifact flows downstream — the staging deploy downloads it instead of rebuilding. Production waits on staging and a human approval. The concurrency group cancels stale PR runs but queues deploys. permissions: contents: read is the only grant the whole file needs.
The pieces you’ll adapt first: swap npm for your stack (setup-python/setup-go have the same cache: convention), add a docker job from the section above if you ship containers, and point ./deploy.sh at whatever your platform actually is — SSH, a cloud CLI, or a GitOps repo where you bump an image tag (see the GitOps with ArgoCD guide for that pattern).
Best Practices
- Pin action versions — use
@v4not@mainto avoid supply chain attacks; for sensitive jobs, pin to a commit SHA - Use
npm cinotnpm install— deterministic installs from lockfile - Cache dependencies — saves 30-60s per job
- Use environments for deployments — required approvals for production
- Set
concurrencygroups — cancel outdated runs on the same branch, queue deploys - Use reusable workflows — DRY your pipeline across repositories
- Minimize secret scope — use environment secrets over repository secrets
- Use
permissionskey — restrict GITHUB_TOKEN to minimum needed - Run tests in parallel — split test suites across matrix jobs
- Use
if: always()for cleanup — ensure resources are cleaned up - Tag Docker images with SHA — trace deployments back to commits
- Use path filters — skip workflows when only docs change
Common Mistakes
- Not pinning action versions —
@maincan introduce breaking changes or malicious code - Using
npm installinstead ofnpm ci— non-deterministic builds - Not setting
concurrency— two pushes race on the same deploy - Overusing
secrets.GITHUB_TOKEN— it comes with broad permissions by default - Not using
environmentfor production deploys — no approval gate - Hardcoding secrets in workflow files — anyone with repo access can see them
- Not caching dependencies — slow builds waste Actions minutes
- Running everything on every push — use path filters to skip irrelevant workflows
- Not using
if: failure()for notifications — failures go unnoticed - Not testing workflows locally — use
actto run workflows before pushing
See Also
- CI/CD Pipeline Guide — pipeline theory, quality gates and promotion flow beyond GitHub Actions.
- GitHub Actions Workflow Examples — the recipe: copy-paste workflows for matrices, secrets, environments, and reusable patterns.
- GitHub Actions Reusable Workflows — focused recipe on
workflow_callpatterns. - Deployment Strategies Guide — rolling, blue-green and canary patterns for the deploy step.
- Testcontainers: Real Dependencies in Integration Tests — test against real services inside the CI job.
External references:
- GitHub Actions billing — official minute quotas, storage limits and larger-runner pricing per plan.
- About GitHub-hosted runners — runner images, hardware specs and the weekly update cadence.
Frequently Asked Questions
What does GitHub Actions cost?
For public repositories, standard GitHub-hosted runners are free. For private repositories, paid plans include a monthly allowance of minutes (2,000 on the Free plan) — and Linux minutes count at 1× while Windows and macOS consume the allowance faster. Self-hosted runners are always free but you pay for the machine.
When should I use a matrix instead of separate jobs?
Use a matrix when the job body is identical and only inputs vary — Node versions, operating systems, test shards. Write separate jobs when the steps differ: a deploy job shares almost nothing with a test job, so forcing it into a matrix just adds if noise.
Reusable workflow or composite action?
A reusable workflow is a whole job: it gets its own runner and its own slot in the needs graph, and it can be called across repositories. A composite action is a bundle of steps that runs inside the caller's job. Share jobs with reusable workflows; share steps with composite actions.
How do I run GitHub Actions locally?
Use act — it runs workflows in Docker containers locally:
# Install act
brew install act
# Run a specific workflow
act -W .github/workflows/ci.yml
# Run with secrets
act -W .github/workflows/ci.yml --secret-file .secrets
How do I stop two deployments from racing?
Put deploys in a concurrency group with cancel-in-progress: false — the second run queues until the first finishes. Reserve cancel-in-progress: true for CI checks where only the latest commit matters.
How do I debug a failing workflow?
- Enable step debug logging: set
ACTIONS_STEP_DEBUG=trueas a repository secret - Enable runner diagnostic logging: set
ACTIONS_RUNNER_DEBUG=true - Use
tmatesession for interactive debugging:
- name: Debug
uses: mxschmitt/action-tmate@v3
if: failure()
timeout-minutes: 30
Related Resources
CI/CD Pipeline Guide: From Commit to Production
A practical guide to building CI/CD pipelines with GitHub Actions, testing gates, deployment strategies, and rollback procedures.
RecipeGitHub Actions Workflow Examples: CI/CD, Matrix & Secrets
How to build and deploy with GitHub Actions using workflows, matrices, caching, secrets, environments, and reusable workflows.
RecipeShare Workflow Logic with GitHub Actions Reusable Workflows
How to create and consume reusable workflows in GitHub Actions, covering inputs, secrets, conditional jobs, matrix strategy, and organization-wide sharing.
GuideDeployment Strategies Compared: Blue-Green, Canary, Rolling
A practical guide to deployment strategies: rolling, blue-green, canary, shadow and feature flags. Minimize risk and rollback time when releasing to production.
GuideComplete Guide to GitOps with ArgoCD
Deploy Kubernetes apps with GitOps and ArgoCD: installation, ApplicationSets, sync strategies, Helm/Kustomize, RBAC, and multi-cluster.
RecipeSetup CI with GitLab Pipelines
How to configure GitLab CI/CD pipelines for testing, building, and deploying applications using .gitlab-ci.yml with stages, jobs, caching, and runners.