How to Implement GitHub Actions CI/CD

GitHub Actions is GitHub's integrated CI/CD platform that automates build, test, and deployment workflows directly from your repository. With its powerful workflow syntax and extensive marketplace of actions, GitHub Actions has become a go-to choice for modern DevOps. This guide covers implementing production CI/CD pipelines from a senior developer's perspective.

Why GitHub Actions

GitHub Actions offers compelling advantages:

1. Native Integration: Built into GitHub; no external services
2. YAML Configuration: Version-controlled workflows
3. Marketplace: Thousands of pre-built actions
4. Matrix Builds: Test across multiple environments
5. Free Tier: Generous minutes for public and private repos

Workflow Basics

Workflow File Structure

Workflows live in .github/workflows/*.yml:

name: CI Pipeline
# Triggers
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
workflow_dispatch: # Manual trigger
# Environment variables
env:
NODE_VERSION: '20'
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Build
run: npm run build

Trigger Events

on:
# Push to specific branches
push:
branches:
- main
- 'release/**'
paths:
- 'src/**'
- 'package.json'
paths-ignore:
- '**.md'
- 'docs/**'
# Pull requests
pull_request:
branches: [main]
types: [opened, synchronize, reopened]
# Scheduled (cron)
schedule:
- cron: '0 2 * * *' # Daily at 2 a.m. UTC
# Manual trigger with inputs
workflow_dispatch:
inputs:
environment:
description: 'Deploy environment'
required: true
default: 'staging'
type: choice
options:
- staging
- production
# Release published
release:
types: [published]
# Another workflow completed
workflow_run:
workflows: ["Build"]
types: [completed]

Complete Node.js CI/CD

name: Node.js CI/CD
on:
push:
branches: [main]
pull_request:
branches: [main]
env:
NODE_VERSION: '20'
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- run: npm ci
- run: npm run lint
test:
runs-on: ubuntu-latest
needs: lint
services:
postgres:
image: postgres:15
env:
POSTGRES_USER: test
POSTGRES_PASSWORD: test
POSTGRES_DB: test
ports:
- 5432:5432
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- run: npm ci
- name: Run tests
run: npm test
env:
DATABASE_URL: postgresql://test:test@localhost:5432/test
build:
runs-on: ubuntu-latest
needs: test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- run: npm ci
- run: npm run build
- name: Upload build artifacts
uses: actions/upload-artifact@v4
with:
name: build
path: dist/
retention-days: 7
deploy-staging:
runs-on: ubuntu-latest
needs: build
if: github.ref == 'refs/heads/main'
environment: staging
steps:
- uses: actions/checkout@v4
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: build
path: dist/
- name: Deploy to staging
run: |
# Deployment script
echo "Deploying to staging..."
env:
DEPLOY_KEY: ${{ secrets.STAGING_DEPLOY_KEY }}
deploy-production:
runs-on: ubuntu-latest
needs: deploy-staging
if: github.ref == 'refs/heads/main'
environment: production
steps:
- uses: actions/checkout@v4
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: build
path: dist/
- name: Deploy to production
run: |
echo "Deploying to production..."
env:
DEPLOY_KEY: ${{ secrets.PRODUCTION_DEPLOY_KEY }}

Docker Build and Push

name: Docker Build
on:
push:
branches: [main]
tags: ['v*']
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
jobs:
build-and-push:
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: Log in to Container Registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
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

Matrix Testing

name: Matrix Tests
on: [push, pull_request]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node: [18, 20, 22]
exclude:
- os: windows-latest
node: 18
include:
- os: ubuntu-latest
node: 20
coverage: true
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- run: npm ci
- run: npm test
- name: Upload coverage
if: matrix.coverage
uses: codecov/codecov-action@v3

Secrets and Environment Variables

Using Secrets

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy
run: ./deploy.sh
env:
API_KEY: ${{ secrets.API_KEY }}
DATABASE_URL: ${{ secrets.DATABASE_URL }}
- name: Mask sensitive output
run: |
echo "::add-mask::${{ secrets.API_KEY }}"
# Further usage won't show the value in logs

Environment Protection

jobs:
deploy-production:
runs-on: ubuntu-latest
environment:
name: production
url: https://example.com
steps:
- name: Deploy
run: ./deploy.sh
# Secrets from the 'production' environment
env:
API_KEY: ${{ secrets.API_KEY }}

Caching

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Node.js with npm cache
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
# Custom cache
- name: Cache dependencies
uses: actions/cache@v4
with:
path: |
~/.npm
node_modules
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci

Reusable Workflows

Define Reusable Workflow

.github/workflows/reusable-deploy.yml:

name: Reusable Deploy
on:
workflow_call:
inputs:
environment:
required: true
type: string
artifact-name:
required: true
type: string
secrets:
deploy-key:
required: true
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ inputs.environment }}
steps:
- uses: actions/download-artifact@v4
with:
name: ${{ inputs.artifact-name }}
- name: Deploy
run: ./deploy.sh
env:
DEPLOY_KEY: ${{ secrets.deploy-key }}

Use Reusable Workflow

name: CI/CD
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm run build
- uses: actions/upload-artifact@v4
with:
name: dist
path: dist/
deploy-staging:
needs: build
uses: ./.github/workflows/reusable-deploy.yml
with:
environment: staging
artifact-name: dist
secrets:
deploy-key: ${{ secrets.STAGING_KEY }}
deploy-production:
needs: deploy-staging
uses: ./.github/workflows/reusable-deploy.yml
with:
environment: production
artifact-name: dist
secrets:
deploy-key: ${{ secrets.PRODUCTION_KEY }}

Composite Actions

.github/actions/setup-project/action.yml:

name: 'Setup Project'
description: 'Setup Node.js and install dependencies'
inputs:
node-version:
description: 'Node.js version'
default: '20'
runs:
using: 'composite'
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: 'npm'
- run: npm ci
shell: bash
- run: npm run build --if-present
shell: bash

Usage:

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/setup-project
with:
node-version: '20'
- run: npm test

Conditional Execution

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Run only on the main branch
- name: Deploy
if: github.ref == 'refs/heads/main'
run: ./deploy.sh
# Run on success
- name: Notify success
if: success()
run: echo "Build succeeded"
# Run on failure
- name: Notify failure
if: failure()
run: echo "Build failed"
# Always run
- name: Cleanup
if: always()
run: ./cleanup.sh
# Complex conditions
- name: Production deploy
if: |
github.ref == 'refs/heads/main' &&
github.event_name == 'push' &&
!contains(github.event.head_commit.message, '[skip deploy]')
run: ./deploy-prod.sh

Key Takeaways

1. Version your workflows: Treat .github/workflows like production code
2. Use caching: Speed up builds with dependency caching
3. Protect environments: Require approvals for production deployments
4. Reuse workflows: The DRY principle applies to CI/CD too
5. Fail fast in PRs: Quick feedback on pull requests
6. Secure secrets: Use environment-specific secrets and protection rules

GitHub Actions provides a powerful, flexible CI/CD platform—invest time in well-structured workflows, and they'll serve your team reliably.