github-actions

name	github-actions
description	GitHub Actions CI/CD workflow configuration. Use when setting up automated testing, deployment, or continuous integration for GitHub repositories.

Purpose

Automate build, test, and deployment workflows directly from GitHub repositories.

When to Use

• Setting up CI/CD pipelines
• Automating tests on push/PR
• Deploying to production
• Running scheduled jobs
• Automating code quality checks

Workflow Basics

Workflow File Location

.github/
└── workflows/
    ├── ci.yml
    ├── deploy.yml
    └── scheduled.yml

Basic Workflow Structure

name: Workflow Name
on: [push, pull_request]
jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello World"

Common Triggers

Push and Pull Request

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

Manual Trigger

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy'
        required: true
        default: 'staging'

Scheduled (Cron)

on:
  schedule:
    - cron: '0 0 * * *' # Daily at midnight UTC

Path Filters

on:
  push:
    paths:
      - 'src/**'
      - 'package.json'

Common Jobs

Install and Test (Node.js)

name: CI

on: [push, pull_request]

jobs:
  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 test
      - run: npm run build

Install and Test (Python)

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
      
      - run: pip install -r requirements.txt
      - run: pytest

Lint and Format

name: Lint

on: [push, pull_request]

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
      - run: npm run format:check

Build Docker Image

name: Docker Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: docker/setup-buildx-action@v3
      
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      
      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest

Deploy to Vercel

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

Deploy to AWS

name: Deploy to AWS

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1
      
      - run: npm ci
      - run: npm run build
      - run: aws s3 sync ./dist s3://my-bucket

Multi-Stage Workflows

Test Then Deploy

name: CI/CD

on:
  push:
    branches: [main]

jobs:
  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 test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - run: echo "Deploying..."

Matrix Testing

name: Test Matrix

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 21]
        os: [ubuntu-latest, windows-latest, macos-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

Caching

Cache npm Dependencies

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

Custom Cache

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-

Cache Build Artifacts

- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      dist
    key: ${{ runner.os }}-build-${{ github.sha }}
    restore-keys: |
      ${{ runner.os }}-build-

Secrets Management

Using Secrets

- run: |
    echo "API_KEY=${{ secrets.API_KEY }}" >> .env
    npm run build

Required Secrets

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check secrets
        run: |
          if [ -z "${{ secrets.API_KEY }}" ]; then
            echo "API_KEY secret is required"
            exit 1
          fi

Environment Variables

Setting Environment Variables

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NODE_ENV: production
      API_URL: https://api.example.com
    steps:
      - run: echo $NODE_ENV

From Job Output

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
    steps:
      - id: version
        run: echo "version=1.0.0" >> $GITHUB_OUTPUT

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Version ${{ needs.build.outputs.version }}"

Artifacts

Upload Build Output

- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: dist/

Download Artifact

- uses: actions/download-artifact@v4
  with:
    name: build-output
    path: ./dist

Common Actions

Checkout

- uses: actions/checkout@v4
  with:
    fetch-depth: 0 # Full history

Setup Node.js

- uses: actions/setup-node@v4
  with:
    node-version: '20'
      cache: 'npm'

Setup Python

- uses: actions/setup-python@v5
  with:
    python-version: '3.11'
    cache: 'pip'

Setup Docker

- uses: docker/setup-buildx-action@v3

Setup AWS Credentials

- uses: aws-actions/configure-aws-credentials@v4
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-east-1

Conditional Execution

Run on Specific Branch

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying main branch"

Run on Tag

jobs:
  release:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - run: echo "Creating release"

Skip on Draft PR

jobs:
  test:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - run: echo "Testing PR"

Status Badges

Workflow Status Badge

![CI](https://github.com/username/repo/workflows/CI/badge.svg)

Custom Badge

![Build Status](https://img.shields.io/github/actions/workflow/status/username/repo/ci.yml)

Best Practices

Workflow Design

• Keep workflows simple and focused
• Use matrix for testing multiple configurations
• Cache dependencies to speed up builds
• Use secrets for sensitive data
• Set appropriate timeouts
• Use specific action versions (not @latest)

Performance

• Use caching for dependencies
• Parallelize independent jobs
• Use self-hosted runners for large projects
• Minimize artifact sizes
• Use conditional execution

Security

• Pin action versions
• Use OIDC for cloud authentication
• Limit permissions with permissions field
• Review third-party actions
• Keep secrets encrypted
• Use environment protection rules

Common Patterns

Monorepo

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: [frontend, backend, shared]
    steps:
      - uses: actions/checkout@v4
      - working-directory: ./packages/${{ matrix.package }}
        run: npm ci && npm test

Release Workflow

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    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: softprops/action-gh-release@v1
        with:
          files: dist/*

Dependency Update

name: Dependency Update

on:
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx npm-check-updates -u
      - run: npm install
      - run: npm test
      - uses: peter-evans/create-pull-request@v6
        with:
          title: 'Update dependencies'
          body: 'Automated dependency update'

Troubleshooting

View Workflow Logs

• Go to Actions tab in repository
• Click on workflow run
• Expand job to see logs

Debug Failed Workflows

- name: Debug
  run: |
    echo "Runner OS: ${{ runner.os }}"
    echo "Event: ${{ github.event_name }}"
    echo "Ref: ${{ github.ref }}"

Re-run Workflow

• Click on failed workflow
• Click "Re-run jobs" button

Enable Debug Logging

Add secret ACTIONS_STEP_DEBUG with value true

Scripts

.github/workflows/ci.yml

name: CI

on: [push, pull_request]

jobs:
  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 test
      - run: npm run lint
      - run: npm run build

.github/workflows/deploy.yml

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    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
      - run: echo "Deploying to production"