GitHub Actions from Scratch — Your First CI/CD Pipeline in 10 Minutes
You just pushed code to GitHub. Wouldn't it be great if tests ran automatically, a Docker image got built, and the app deployed itself — all without you touching a single server? That is exactly what GitHub Actions does, and you can set it up faster than you think.
Workflow Anatomy: Where Everything Lives
GitHub Actions workflows live inside your repository. Every workflow is a YAML file inside .github/workflows/.
your-repo/
├── .github/
│ └── workflows/
│ ├── ci.yml # Runs tests on every push
│ ├── deploy.yml # Deploys to production
│ └── nightly.yml # Scheduled nightly builds
├── src/
├── tests/
└── package.json
The hierarchy is: Workflow > Jobs > Steps. A workflow contains one or more jobs. Each job contains a sequence of steps. Steps either run shell commands or use pre-built actions.
Your First Workflow
Create .github/workflows/ci.yml and push it. That is literally all it takes.
name: CI Pipeline
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Run linter
run: npm run lint
- name: Run tests
run: npm test
- name: Build
run: npm run build
Push this file and go to the Actions tab in your repo. You will see it running. That is your first CI pipeline — tests run on every push and every PR.
Triggers: When Workflows Run
GitHub Actions supports a rich set of triggers. Here are the ones you will use most:
on:
# Run on push to specific branches
push:
branches: [main, develop]
paths:
- 'src/**' # Only run when source code changes
- '!docs/**' # Ignore doc changes
# Run on pull requests
pull_request:
branches: [main]
types: [opened, synchronize, reopened]
# Run on a schedule (cron syntax, UTC)
schedule:
- cron: '0 6 * * 1' # Every Monday at 6 AM UTC
# Manual trigger with inputs
workflow_dispatch:
inputs:
environment:
description: 'Deploy to which environment?'
required: true
default: 'staging'
type: choice
options:
- staging
- production
# Trigger when a release is published
release:
types: [published]
Runners: Where Your Code Executes
jobs:
build:
# GitHub-hosted runners (free for public repos)
runs-on: ubuntu-latest # Also: ubuntu-22.04, ubuntu-24.04
# runs-on: windows-latest # Windows Server
# runs-on: macos-latest # macOS (more expensive)
# Self-hosted runners (your own machines)
# runs-on: self-hosted
# runs-on: [self-hosted, linux, x64, gpu]
GitHub-hosted runners give you 2-core machines with 7 GB RAM. For public repos, they are completely free. For private repos, you get 2,000 minutes/month free on the Free plan.
Secrets and Environment Variables
Never hardcode credentials. Use GitHub Secrets instead.
jobs:
deploy:
runs-on: ubuntu-latest
# Environment-level secrets and protection rules
environment: production
env:
# Plain environment variables
NODE_ENV: production
API_URL: https://api.example.com
steps:
- uses: actions/checkout@v4
- name: Deploy to server
env:
# Reference secrets from Settings > Secrets
SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
run: |
echo "$SSH_KEY" > deploy_key
chmod 600 deploy_key
ssh -i deploy_key user@server "cd /app && git pull && npm run build"
Set secrets in your repo: Settings > Secrets and variables > Actions > New repository secret.
Matrix Builds: Test Across Versions
Matrix builds let you test across multiple versions, operating systems, or configurations in parallel.
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node-version: [18, 20, 22]
exclude:
- os: macos-latest
node-version: 18 # Skip Node 18 on macOS
fail-fast: false # Don't cancel other jobs if one fails
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
- run: npm ci
- run: npm test
This creates 8 parallel jobs (3 OS x 3 versions minus 1 exclusion). Each one runs independently.
Caching Dependencies
Without caching, npm install downloads the internet on every run. Caching fixes that.
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm' # Built-in caching for npm/yarn/pnpm
- run: npm ci # Uses cache — 30s instead of 2 min
- run: npm test
- run: npm run build
# For custom caching (e.g., build artifacts)
- name: Cache build output
uses: actions/cache@v4
with:
path: |
dist
.next/cache
key: build-${{ runner.os }}-${{ hashFiles('src/**') }}
restore-keys: |
build-${{ runner.os }}-
Artifacts: Save Build Outputs
Artifacts let you save files from a job and download them later or pass them between jobs.
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm run build
- name: Upload build artifact
uses: actions/upload-artifact@v4
with:
name: build-output
path: dist/
retention-days: 7
deploy:
needs: build # Run after build job
runs-on: ubuntu-latest
steps:
- name: Download build artifact
uses: actions/download-artifact@v4
with:
name: build-output
path: dist/
- name: Deploy to server
run: |
ls -la dist/
# Deploy the pre-built artifacts
Real-World Example: Docker Build and Push
name: Docker Build & Push
on:
push:
branches: [main]
tags: ['v*']
jobs:
docker:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=ref,event=branch
type=semver,pattern={{version}}
type=sha,prefix=
- name: Build and push
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
Reusable Workflows
Stop copying the same CI config across 20 repos. Create reusable workflows.
# .github/workflows/reusable-node-ci.yml (in a shared repo)
name: Reusable Node.js CI
on:
workflow_call:
inputs:
node-version:
required: false
type: string
default: '20'
secrets:
NPM_TOKEN:
required: false
jobs:
ci:
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
- run: npm run build
Then call it from any repo:
# .github/workflows/ci.yml (in your project repo)
name: CI
on: [push, pull_request]
jobs:
ci:
uses: your-org/shared-workflows/.github/workflows/reusable-node-ci.yml@main
with:
node-version: '20'
secrets:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
Pro Tips
1. Use concurrency to cancel outdated runs. When you push twice quickly, cancel the first run:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
2. Use job outputs to pass data between jobs:
jobs:
version:
runs-on: ubuntu-latest
outputs:
tag: ${{ steps.tag.outputs.value }}
steps:
- id: tag
run: echo "value=v$(date +%Y%m%d.%H%M%S)" >> "$GITHUB_OUTPUT"
deploy:
needs: version
runs-on: ubuntu-latest
steps:
- run: echo "Deploying ${{ needs.version.outputs.tag }}"
3. Gate production deploys with environments and approvals. In Settings > Environments, create a production environment with required reviewers. The workflow will pause and wait for approval before deploying.
GitHub Actions has over 20,000 community actions on the Marketplace. Before writing a custom step, search — someone has probably already built it.
Next in our DevOps series, we will explore Jenkins Pipeline — Declarative, Scripted, and Blue Ocean — and compare it head-to-head with GitHub Actions.