github-actions

GitHub Actions Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: github-actions for comprehensive documentation.

Basic CI Workflow

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  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: Run linter
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

With Database

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    env:
      DATABASE_URL: postgresql://test:test@localhost:5432/testdb

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx prisma migrate deploy
      - run: npm test

Deploy Workflow

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel
        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'

Matrix Strategy

jobs:
  test:
    strategy:
      matrix:
        node: [18, 20, 22]
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

Reusable Workflows

# .github/workflows/test.yml
on:
  workflow_call:

jobs:
  test:
    runs-on: ubuntu-latest
    steps: [...]

# Usage in another workflow
jobs:
  call-tests:
    uses: ./.github/workflows/test.yml

When NOT to Use This Skill

Skip this skill when:

• Using GitLab CI/CD (.gitlab-ci.yml) - different syntax
• Using Jenkins, CircleCI, Travis CI - different platforms
• Setting up local development environments - use docker-compose skill
• Building Docker images only (no CI needed) - use docker skill
• Working with Bitbucket Pipelines - different platform

Anti-Patterns

Anti-Pattern	Problem	Solution
No permission restrictions	Security risk, excessive access	Set minimal permissions: per job
Using action tags like @v1	Breaking changes on updates	Pin to SHA: @60edb5dd545a775178f52524783378180af0d1f8
Secrets in logs	Credential exposure	Never echo secrets, use env: only
No timeout set	Runaway jobs consuming minutes	Set timeout-minutes: 15 on jobs
Caching nothing	Slow builds, wasted time	Cache dependencies with actions/cache
Running on every commit	Wasted CI minutes	Use paths: filters or pull_request: only
Hardcoded versions	Inconsistent environments	Use matrix strategy or env vars
No artifact retention limit	High storage costs	Set retention-days: 7 on artifacts
Storing secrets in code	Security breach	Use GitHub Secrets, never commit
No branch protection	Bypassing CI checks	Require status checks in branch rules

Quick Troubleshooting

Issue	Diagnosis	Fix
Workflow doesn't trigger	Wrong event, branch filter	Check on: triggers and branch names
Job fails silently	Script errors ignored	Don't use `
Cache never hits	Cache key changing	Use stable keys: hashFiles('**/package-lock.json')
"Resource not accessible"	Wrong permissions	Add required permissions: to job
Secrets not available in PR	Forks don't have access	Use pull_request_target (carefully) or skip secret steps
Artifact upload fails	Path doesn't exist	Check build output path, use if: always()
Matrix job failures	One config fails all	Use fail-fast: false to continue other jobs
Workflow takes too long	No caching, sequential jobs	Add caching, parallelize with needs:
"Context access might be invalid"	Wrong context syntax	Use ${{ }} syntax, check context availability
Can't trigger another workflow	No token permission	Use PAT or GITHUB_TOKEN with write permissions

Production Readiness

Security Best Practices

# Secure workflow
name: CI

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

permissions:
  contents: read
  pull-requests: write

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      # Pin actions to SHA for security
      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
        with:
          node-version: '20'

      # Use environment secrets
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: |
          # Never echo secrets
          ./deploy.sh

Caching Strategy

jobs:
  build:
    steps:
      - uses: actions/checkout@v4

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

      # Custom caching
      - 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-

      # Turbo cache for monorepos
      - name: Cache Turbo
        uses: actions/cache@v4
        with:
          path: .turbo
          key: ${{ runner.os }}-turbo-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-

Artifact Management

jobs:
  build:
    steps:
      - name: Build
        run: npm run build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-${{ github.sha }}
          path: dist/
          retention-days: 7

  deploy:
    needs: build
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: build-${{ github.sha }}
          path: dist/

Environment Protection

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment:
      name: production
      url: https://example.com
    concurrency:
      group: production-deploy
      cancel-in-progress: false

Error Handling

jobs:
  build:
    steps:
      - name: Run tests
        id: tests
        continue-on-error: true
        run: npm test

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: coverage/

      - name: Check test status
        if: steps.tests.outcome == 'failure'
        run: |
          echo "Tests failed"
          exit 1

      - name: Notify on failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {"text": "Build failed: ${{ github.repository }}"}
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

Dependabot Configuration

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      development-dependencies:
        patterns:
          - "@types/*"
          - "eslint*"
          - "prettier*"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Release Workflow

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm run build

      - name: Create Release
        uses: softprops/action-gh-release@v2
        with:
          files: dist/*
          generate_release_notes: true

Monitoring Metrics

Metric	Target
Build success rate	> 95%
Build duration	< 10min
Cache hit rate	> 80%
Deployment frequency	As needed

Checklist

• Minimal permissions declared
• Actions pinned to SHA
• Secrets not exposed in logs
• Caching configured
• Timeouts set
• Error notifications
• Environment protection rules
• Dependabot enabled
• Branch protection rules
• Concurrency controls

Reference Documentation

• Caching
• Secrets