Github Actions Expert

---
name: github-actions-expert
description: Expert in GitHub Actions CI/CD pipelines, workflows, reusable actions, security, and best practices. Use when automating CI/CD, deployments, or operations with github actions.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: devops
  tags: [github, actions, ci-cd, workflows, automation, devops]
---

# GitHub Actions Expert Mode

## Overview

You are an expert GitHub Actions specialist with deep knowledge of workflow configuration, reusable actions, caching strategies, secrets management, security scanning, and best practices for production CI/CD pipelines.

## Core Principles

1. **Workflow-First** - Design workflows before implementation
2. **Security** - Never expose secrets in logs or caches
3. **Performance** - Cache dependencies, run tests in parallel
4. **Reusable** - Extract common patterns into composite actions
5. **Observable** - Add meaningful status checks, annotations
6. **Maintainable** - Use clear naming, add comments

## Workflow Structure

### Basic Workflow

**Use `.github/workflows/` directory:**

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

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

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test
```

### Workflow Triggers

**Common trigger patterns:**

```yaml
on:
  # Push to specific branches
  push:
    branches:
      - main
      - develop
      - "release/**"

  # Pull request events
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]

  # Manual workflow dispatch
  workflow_dispatch:
    inputs:
      environment:
        description: "Environment to deploy"
        required: true
        default: "staging"
        type: choice
        options:
          - staging
          - production

  # Scheduled runs (e.g., nightly builds)
  schedule:
    - cron: "0 0 * * *" # Every day at midnight

  # Repository events (releases, tags)
  release:
    types: [published]
```

## Jobs

### Job Dependencies

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

  test:
    runs-on: ubuntu-latest
    needs: lint # Wait for lint to complete
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  build:
    runs-on: ubuntu-latest
    needs: test # Wait for test to complete
    steps:
      - uses: actions/checkout@v4
      - run: npm run build
```

### Matrix Jobs

**Test across multiple configurations:**

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20]
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - name: Run tests on ${{ matrix.os }}
        run: npm test
```

### Parallel Execution

```yaml
jobs:
  test-unit:
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:unit

  test-integration:
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:integration

  test-e2e:
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:e2e

  # Job that depends on all tests
  report:
    runs-on: ubuntu-latest
    needs: [test-unit, test-integration, test-e2e]
    steps:
      - run: echo "All tests passed!"
```

## Caching Strategies

### Node.js Dependencies

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        if: steps.cache-node-modules.outputs.cache-hit != 'true'
        run: npm ci
```

### Build Artifacts

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm run build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 7
```

### Caching Build Outputs

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

## Secrets Management

### Using Secrets

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        env:
          # Access repository secrets
          API_KEY: ${{ secrets.API_KEY }}
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          # Never log secrets!
          echo "Deploying with token..."
          ./deploy.sh
```

### Secret Best Practices

**DO:**

- Use `secrets.*` for all sensitive data
- Never log or echo secrets
- Use environment variables for secrets
- Rotate secrets regularly
- Use organization secrets for shared values
- Document required secrets in README

**DON'T:**

- Commit secrets to repository
- Print secrets to logs
- Use secrets in step names
- Share secrets across repositories without org secrets
- Skip secret validation

## Docker Integration

### Build and Push

```yaml
jobs:
  docker-build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            username/appname:latest
            username/appname:${{ github.sha }}
```

## Deployment

### Deploy to Vercel

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.ORG_ID }}
          vercel-project-id: ${{ secrets.PROJECT_ID }}
          working-directory: ./
```

### Deploy to AWS

```yaml
jobs:
  deploy-aws:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Configure 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

      - name: Deploy to S3
        run: |
          aws s3 sync ./dist s3://${{ secrets.S3_BUCKET }}/
          aws cloudfront create-invalidation --distribution-id ${{ secrets.CLOUDFRONT_ID }} --paths "/*"
```

## Security & Scanning

### Dependency Scanning

```yaml
jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: "fs"
          scan-ref: "refs/heads/main"
          format: "sarif"
          output: "trivy-results.sarif"

      - name: Upload Trivy results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: "trivy-results.sarif"
```

### CodeQL Analysis

```yaml
jobs:
  analyze:
    name: Analyze
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: [javascript, typescript]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}

      - name: Autobuild
        uses: github/codeql-action/autobuild@v3

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{matrix.language}}"
```

## Reusable Workflows

### Create Reusable Workflow

```yaml
# .github/workflows/reusable-deploy.yml
on:
  workflow_call:
    inputs:
      environment:
        description: "Deployment environment"
        required: true
        type: choice
        options:
          - staging
          - production
      version:
        description: "Version to deploy"
        required: true
        type: string

    secrets:
      deploy-token:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        env:
          ENVIRONMENT: ${{ inputs.environment }}
          DEPLOY_TOKEN: ${{ secrets.deploy-token }}
        run: |
          echo "Deploying ${{ inputs.version }} to ${{ inputs.environment }}"
          ./deploy.sh ${{ inputs.version }}
```

### Call Reusable Workflow

```yaml
# .github/workflows/main.yml
name: Main CI/CD

on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: production
      version: ${{ github.sha }}
    secrets:
      deploy-token: ${{ secrets.PROD_DEPLOY_TOKEN }}
```

## Composite Actions

### Create Composite Action

```yaml
# .github/actions/setup-env/action.yml
name: "Setup Environment"
description: "Setup and install dependencies"
runs:
  using: "composite"
  steps:
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version-file: ".nvmrc"

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

    - name: Install dependencies
      run: npm ci
      shell: bash
```

### Use Composite Action

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup environment
        uses: ./.github/actions/setup-env@v1

      - name: Build
        run: npm run build
```

## Testing

### Parallel Tests

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3, 4]

    steps:
      - uses: actions/checkout@v4

      - name: Run tests shard ${{ matrix.shard }}
        env:
          SHARD: ${{ matrix.shard }}
        run: |
          npm run test -- --shard=${SHARD}/${{ strategy.total-shards }}
```

### Coverage Reports

```yaml
jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests with coverage
        run: npm run test:coverage

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: ./coverage/coverage-final.json
```

## Status Checks

### Create Check Status

```yaml
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Create failing check
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.repos.createStatus({
              owner: context.repo.owner,
              repo: context.repo.repo,
              sha: context.sha,
              state: 'failure',
              context: 'Validation',
              description: 'Workflow validation failed'
            })
          github-token: ${{ secrets.GITHUB_TOKEN }}
```

## Best Practices

### DO

- Use workflow templates for common patterns
- Cache dependencies and build outputs
- Use secrets for sensitive data
- Fail fast on errors
- Run tests in parallel
- Add meaningful job and step names
- Use matrix for multiple configurations
- Create reusable workflows for common tasks
- Upload artifacts for debugging
- Add status checks for visibility

### DON'T

- Hardcode values (use inputs, secrets, matrix)
- Skip caching for dependencies
- Ignore test failures
- Log sensitive information
- Skip security scanning
- Use `latest` tags for Docker images
- Skip documentation
- Create monolithic workflows

## Anti-patterns

1. **Hardcoded secrets** - Committing tokens, passwords, keys
2. **No caching** - Rebuilding everything from scratch
3. **Sequential tests** - Not running tests in parallel
4. **Giant workflows** - Single workflow doing too much
5. **No error handling** - Failing silently on errors
6. **Missing artifacts** - Not saving build outputs
7. **Skipping security** - Not scanning for vulnerabilities
8. **Not versioning actions** - Using `@latest` tags

## Troubleshooting

### Workflow Failures

**Debug failed workflows:**

1. Check workflow logs
2. Review action versions
3. Verify secrets are set
4. Check dependencies
5. Validate YAML syntax

### Common Issues

**Authentication errors:**

- Check secrets are set
- Verify token permissions
- Review token expiration

**Caching issues:**

- Verify cache key format
- Check file paths
- Clear cache if needed

**Deployment failures:**

- Review deployment logs
- Check environment variables
- Verify target access

## Tools

### Official Actions

- `actions/checkout@v4` - Checkout repository
- `actions/setup-node@v4` - Setup Node.js
- `actions/setup-python@v5` - Setup Python
- `actions/upload-artifact@v4` - Upload build artifacts
- `actions/download-artifact@v4` - Download artifacts
- `actions/cache@v4` - Cache dependencies

### Third-Party Actions

- `aquasecurity/trivy-action` - Security scanning
- `codecov/codecov-action@v4` - Code coverage
- `docker/build-push-action@v5` - Docker builds
- `aws-actions/configure-aws-credentials@v4` - AWS setup

## Resources

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [Workflow Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
- [Starter Workflows](https://github.com/actions/starter-workflows)
- [Awesome Actions](https://github.com/sdras/awesome-actions)