GitHub Actions Expert Companion

Design, optimize, and secure GitHub Actions CI/CD workflows with supply-chain hardening, matrix strategies, and reusable patterns.

When to Use This Agent

Choose this agent when you need to:

• Build production CI/CD pipelines with security-hardened configs, least-privilege permissions, and pinned action SHAs
• Optimize workflow execution through caching, matrix parallelization, and conditional jobs to reduce billable minutes
• Implement reusable workflow libraries and composite actions standardizing CI/CD across an organization

Consider alternatives when:

• Your CI/CD runs on Jenkins, GitLab CI, or CircleCI and you need platform-specific guidance
• You need to manage self-hosted runner infrastructure rather than author workflow YAML

Quick Start

Configuration

Copy
name: github-actions-expert-companion
type: agent
category: ci-cd

Example Invocation

Copy
claude agent:invoke github-actions-expert-companion "Create secure CI for a Node.js monorepo with matrix testing"

Example Output

Copy
name: CI Pipeline
on:
  pull_request:
    branches: [main]
permissions:
  contents: read
  checks: write
jobs:
  test:
    strategy:
      matrix:
        node: [18, 20, 22]
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@11bd719 # v4.2.2 (SHA pinned)
      - uses: actions/setup-node@1d0ff46 # v4.2.0
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci && npm test -- --coverage

Core Concepts

GitHub Actions CI/CD Overview

Aspect	Details
Triggers	push, pull_request, schedule, workflow_dispatch with path and branch filters controlling execution
Job orchestration	Parallel by default; needs for dependencies; matrix strategy multiplies across parameter combos
Security model	GITHUB_TOKEN with granular permissions, environment protection rules, OIDC federation for cloud
Caching	actions/cache and tool-specific caches store dependency trees, reducing install times 60-90%
Reusable workflows	workflow_call trigger enables standardized pipelines consumed across repositories

Workflow Architecture

+----------------+     +------------------+     +----------------+
| Event Trigger  | --> | Workflow File    | --> | Job Matrix     |
| (push, PR,     |     | (.github/        |     | Expansion      |
|  schedule)     |     |  workflows/)     |     | (os x version) |
+----------------+     +------------------+     +----------------+
        |                       |                       |
        v                       v                       v
+----------------+     +------------------+     +----------------+
| Runner         | --> | Step Execution   | --> | Artifact &     |
| Provisioning   |     | (actions, shell) |     | Cache Storage  |
+----------------+     +------------------+     +----------------+

Configuration

Parameter	Type	Default	Description
default_runner	string	ubuntu-latest	Default runner label for jobs
pin_actions	bool	true	Replace version tags with full commit SHA references
cache_strategy	enum	npm	Caching approach: npm, yarn, pnpm, pip, gradle, custom
permissions_mode	enum	restrictive	Token default: restrictive (explicit per-job) or permissive
artifact_retention	int	5	Days to retain uploaded artifacts

Best Practices

1. Pin actions to full commit SHAs - Tags can be moved to malicious code; SHA references are cryptographically fixed. Use @11bd71901bbe... instead of @v4.

2. Apply least-privilege permissions - Set workflow-level permissions to read-only and grant additional scopes only to jobs that need them.

3. Cache dependencies aggressively - Use built-in cache options in setup-node and similar actions. Generate keys from lockfile hashes for automatic invalidation.

4. Use reusable workflows - Centralize scanning, linting, and deployment in a shared repo as workflow_call workflows so every team follows the same gates.

5. Gate deployments with environments - Configure required reviewers, wait timers, and branch protection for human approval before production.

Common Issues

1. Cache key misses - Overly specific keys invalidate every run. Use lockfile hashes as primary key with fallback restore-key prefixes.

2. Matrix failures masked - continue-on-error hides real breakages. Use fail-fast: false instead to run all combinations while reporting failures.

3. Secret exposure from forks - pull_request from forks lacks secrets. Use pull_request_target carefully, checking out base ref only to prevent exfiltration.