github-actions

What this skill does

# GitHub Actions Skill

Master GitHub Actions for CI/CD pipelines, automated testing, deployments, and repository automation. This skill covers workflow syntax, triggers, jobs, matrix builds, caching, artifacts, reusable workflows, and secrets management.

## When to Use This Skill

### USE when:
- Building CI/CD pipelines for GitHub repositories
- Automating tests across multiple OS/language versions
- Creating release and deployment workflows
- Publishing packages to npm, PyPI, Docker Hub
- Automating issue triage and PR management
- Scheduling periodic maintenance tasks
- Building reusable workflow components
- Implementing GitOps deployment patterns

### DON'T USE when:
- Repository not hosted on GitHub (use Jenkins, GitLab CI)
- Need complex DAG-based workflow orchestration (use Airflow)
- Require visual workflow design (use n8n, Activepieces)
- Self-hosted runners not available for compute-intensive tasks
- Need real-time event processing (use dedicated message queues)

## Prerequisites

### GitHub Repository Setup
```bash
# Create workflow directory
mkdir -p .github/workflows

# Verify GitHub CLI installed
gh --version

# Authenticate with GitHub
gh auth login

# Check workflow permissions
gh api repos/{owner}/{repo}/actions/permissions
```

### Local Testing with act
```bash
# Install act for local workflow testing
# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Verify installation
act --version

# Run workflow locally
act -l                    # List available workflows
act push                  # Simulate push event
act pull_request          # Simulate PR event
act -j build              # Run specific job
```

### Workflow Linting
```bash
# Install actionlint
brew install actionlint   # macOS
go install github.com/rhysd/actionlint/cmd/actionlint@latest  # Go

# Lint workflows
actionlint .github/workflows/*.yml

# YAML validation
pip install yamllint
yamllint .github/workflows/
```

## Core Capabilities

### 1. Basic Workflow Structure

```yaml
# .github/workflows/ci.yml
name: CI Pipeline

# Workflow triggers
on:
  push:
    branches: [main, develop]
    paths:
      - 'src/**'
      - 'tests/**'
      - 'pyproject.toml'
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      debug:
        description: 'Enable debug mode'
        required: false
        type: boolean
        default: false

# Environment variables for all jobs
env:
  PYTHON_VERSION: '3.11'
  NODE_VERSION: '20'
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# Concurrency control
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Workflow permissions
permissions:
  contents: read
  packages: write
  pull-requests: write

jobs:
  lint:
    name: Code Quality
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          cache: 'pip'

      - name: Install linters
        run: |
          pip install ruff mypy

      - name: Run linting
        run: |
          ruff check src/
          ruff format --check src/

      - name: Type checking
        run: mypy src/ --ignore-missing-imports

  test:
    name: Test Suite
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          cache: 'pip'

      - name: Install dependencies
        run: |
          pip install -e ".[dev]"

      - name: Run tests
        run: |
          pytest tests/ -v --cov=src --cov-report=xml --cov-report=html

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage.xml
          fail_ci_if_error: true

  build:
    name: Build Package
    needs: test
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install build tools
        run: pip install build

      - name: Get version
        id: version
        run: |
          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
          echo "version=$VERSION" >> $GITHUB_OUTPUT

      - name: Build package
        run: python -m build

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist-${{ steps.version.outputs.version }}
          path: dist/
          retention-days: 5
```

### 2. Matrix Builds for Cross-Platform Testing

```yaml
# .github/workflows/matrix-test.yml
name: Cross-Platform Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test-matrix:
    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
    runs-on: ${{ matrix.os }}

    strategy:
      fail-fast: false
      max-parallel: 4
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ['3.10', '3.11', '3.12']
        include:
          # Additional configuration for specific combinations
          - os: ubuntu-latest
            python-version: '3.12'
            coverage: true
          # Experimental Python version
          - os: ubuntu-latest
            python-version: '3.13-dev'
            experimental: true
        exclude:
          # Skip Windows + Python 3.10 (known issues)
          - os: windows-latest
            python-version: '3.10'

    continue-on-error: ${{ matrix.experimental || false }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'
          cache-dependency-path: |
            pyproject.toml
            requirements*.txt

      - name: Install dependencies (Unix)
        if: runner.os != 'Windows'
        run: |
          pip install -e ".[dev]"

      - name: Install dependencies (Windows)
        if: runner.os == 'Windows'
        run: |
          pip install -e ".[dev]"
        shell: pwsh

      - name: Run tests
        run: |
          pytest tests/ -v --tb=short
        env:
          CI: true
          PLATFORM: ${{ matrix.os }}

      - name: Run tests with coverage
        if: matrix.coverage
        run: |
          pytest tests/ -v --cov=src --cov-report=xml

      - name: Upload coverage
        if: matrix.coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage.xml

  test-summary:
    name: Test Summary
    needs: test-matrix
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Check matrix results
        run: |
          if [ "${{ needs.test-matrix.result }}" == "failure" ]; then
            echo "Some matrix jobs failed"
            exit 1
          fi
          echo "All matrix jobs passed"
```

### 3. Caching Strategies

```yaml
# .github/workflows/caching.yml
name: Build with Caching

on: [push, pull_request]

jobs:
  build-with-cache:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Python pip cache
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
          cache-dependency-path: |
            requirements.txt
            requirements-dev.txt

      # Node modules cache
      - name: Set up Node.js
        uses: act