github-actions

GitHub Actions Skill

Design and implement GitHub Actions workflows for CI/CD automation.

When to Use This Skill

Keywords: github actions, ci/cd, workflow, pipeline, build, deploy, continuous integration, continuous deployment, yaml workflow, job, step, runner, matrix, reusable workflow

Use this skill when:

• Creating new GitHub Actions workflows
• Reviewing existing workflow files
• Designing CI/CD pipelines for repositories
• Setting up build/test/deploy automation
• Implementing reusable workflow patterns

MANDATORY: Documentation-First Approach

Before creating workflows:

1. Verify syntax via MCP servers (context7 for GitHub Actions docs)
2. Check for existing patterns in the repository
3. Use official actions where possible (actions/checkout, actions/setup-node, etc.)

Workflow Structure Overview

name: Workflow Name

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

permissions:
  contents: read

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Step name
        run: echo "Hello"

Key Concepts

Triggers (on)

Trigger	Use Case
push	Run on every push to specified branches
pull_request	Run on PR events
workflow_dispatch	Manual trigger
schedule	Cron-based scheduling
workflow_call	Called by other workflows (reusable)

Job Configuration

Setting	Purpose
runs-on	Runner environment (ubuntu-latest, windows-latest, macos-latest)
needs	Job dependencies
if	Conditional execution
strategy.matrix	Matrix builds
environment	Deployment environment with protection rules

Common Actions

Action	Purpose
actions/checkout@v4	Checkout repository
actions/setup-node@v4	Setup Node.js
actions/setup-python@v5	Setup Python
actions/setup-dotnet@v4	Setup .NET
actions/cache@v4	Cache dependencies
actions/upload-artifact@v4	Upload build artifacts

Best Practices

Security

permissions:
  contents: read  # Minimal permissions

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4  # Pin to specific version

Caching

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

Matrix Builds

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

Reusable Workflows

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'
    secrets:
      NPM_TOKEN:
        required: false

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm test

Calling reusable workflow:

jobs:
  call-test:
    uses: ./.github/workflows/reusable-test.yml
    with:
      node-version: '20'
    secrets: inherit

Workflow Patterns

PR Validation

name: PR Validation
on:
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  build:
    needs: [lint, test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build

Release Workflow

name: Release
on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: dist/*
          generate_release_notes: true

Common Issues

Issue	Solution
Permission denied	Add permissions block with required access
Action not found	Check action version and repository
Cache not working	Verify key pattern matches file paths
Job dependency failed	Check needs references and job names

MCP Research

For current GitHub Actions patterns:

perplexity: "GitHub Actions best practices 2026"
context7: "github-actions" (for official documentation)

Version History

• v1.0.0 (2026-01-17): Initial release

---

Last Updated: 2026-01-17