GitHub Actions Engineer

CI/CD specialist creating and maintaining GitHub Actions workflows for automated testing and deployment.

Quick Reference

Property	Value
Domain	DevOps
FORGE Stage	3 (BUILD)
Version	1.0.0
Output Types	Workflow YAML, documentation

Overview

Use this agent when you need to:

Generate CI workflows for new repositories
Create deployment workflows for Railway
Set up PR validation and checks
Configure caching and parallelization
Implement security scanning (CodeQL, dependency review)
Document required secrets and setup

The GitHub Actions Engineer creates optimized CI/CD workflows with security best practices, intelligent caching, and efficient job parallelization.

Core Capabilities

Workflow Generation

Create complete CI/CD workflow YAML files with test, lint, build, and deploy jobs

Job Optimization

Design efficient job matrices, parallelization strategies, and dependency caching

Secret Management

Document required secrets without exposure, with setup instructions

Branch Protection

Define rules for protected branches and PR requirements

When to Use

Creating CI pipeline for a new SO1 repository

Setting up automated deployment to Railway

Adding PR validation (title, size, changesets)

Implementing security scanning workflows

Optimizing existing workflows (caching, parallelization)

Documenting secrets and GitHub Actions setup

Not suitable for:

GitLab CI, CircleCI, or other CI systems
Manual deployment processes
Non-GitHub repositories

Usage Examples

Full CI Workflow
Railway Deployment
PR Validation

Complete CI pipeline with lint, test, build, and security scanning:

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

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

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

env:
  NODE_VERSION: '20'
  PNPM_VERSION: '9'

jobs:
  # Lint and Type Check
  lint:
    name: Lint & Type Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with:
          version: ${{ env.PNPM_VERSION }}
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm typecheck

  # Unit Tests
  test:
    name: Test
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - uses: actions/setup-node@v4
        with:
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm test -- --coverage
      - uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

  # Build
  build:
    name: Build
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - uses: actions/setup-node@v4
        with:
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: actions/upload-artifact@v4
        with:
          name: build
          path: dist/

  # Security Scan
  security:
    name: Security Scan
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/analyze@v3
        with:
          languages: typescript

Result: Parallelized CI pipeline with lint, test, build running concurrently, plus security scanning.

Automated deployment workflow with staging and production environments:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

jobs:
  # Auto-deploy to staging on main push
  deploy-staging:
    name: Deploy to Staging
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment:
      name: staging
      url: https://api-staging.so1.io
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @railway/cli
      - run: railway up --service api --environment staging
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
      - name: Verify deployment
        run: |
          sleep 30
          curl -f https://api-staging.so1.io/health || exit 1

  # Manual production deployment
  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    if: github.event.inputs.environment == 'production'
    environment:
      name: production
      url: https://api.so1.io
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @railway/cli
      - run: railway up --service api --environment production
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN_PROD }}
      - run: |
          sleep 30
          curl -f https://api.so1.io/health || exit 1

Result: Automatic staging deployments on main branch, manual production deployments via workflow dispatch.

PR checks for title validation, size labeling, and changesets:

# .github/workflows/pr-check.yml
name: PR Check

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  # Validate PR title (Conventional Commits)
  pr-title:
    name: Validate PR Title
    runs-on: ubuntu-latest
    steps:
      - uses: amannn/action-semantic-pull-request@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          types: |
            feat
            fix
            docs
            refactor
            test
            chore

  # Add size label
  size-label:
    name: Add Size Label
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: codelytv/pr-size-labeler@v1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          xs_max_size: 10
          s_max_size: 100
          m_max_size: 500
          l_max_size: 1000

  # Check for changeset
  changeset:
    name: Changeset Check
    runs-on: ubuntu-latest
    if: ${{ !contains(github.head_ref, 'dependabot') }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: changesets/action@v1
        with:
          publish: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Result: Enforces PR standards with title validation, automatic size labeling, and changeset checks.

Outputs

Workflow Files

# .github/workflows/ci.yml - Main CI pipeline
# .github/workflows/deploy.yml - Deployment workflow
# .github/workflows/pr-check.yml - PR validation

Secrets Documentation

# Required GitHub Secrets

| Secret | Purpose | Where to Get |
|--------|---------|--------------|
| `RAILWAY_TOKEN` | Railway deployments | Railway dashboard → Account → Tokens |
| `CODECOV_TOKEN` | Coverage uploads | Codecov dashboard → Repository Settings |
| `SLACK_WEBHOOK_URL` | Deployment notifications | Slack App → Incoming Webhooks |
| `NPM_TOKEN` | Package publishing | npm account → Access Tokens |

## Setup Instructions

1. Go to repository Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Add each secret with the name and value from your provider
4. For environment-specific secrets (staging/production), create them under Environments

Caching Strategies

# pnpm cache
- uses: pnpm/action-setup@v3
  with:
    version: 9
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'pnpm'

# Turbo cache
- uses: actions/cache@v4
  with:
    path: .turbo
    key: turbo-${{ github.sha }}
    restore-keys: turbo-

# Docker layer cache
- uses: docker/build-push-action@v5
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

FORGE Gate Compliance

Entry Gates (Pre-conditions)

Repository structure and tech stack known

The agent needs to understand the repository structure (monorepo vs single package), programming language, and package manager (npm, pnpm, yarn).

Test commands documented

Test commands must be defined in package.json scripts (e.g., npm test, pnpm test:unit).

Deployment targets identified

If CD is needed, deployment targets (Railway, Vercel, etc.) and environments must be specified.

Exit Gates (Post-conditions)

CI workflow created and passing

The .github/workflows/ci.yml file is created with test, lint, and build jobs, and all jobs pass on initial run.

CD workflow created if applicable

If deployment is required, .github/workflows/deploy.yml is created with proper environment configurations.

Secrets documented

All required secrets are documented in README.md or CONTRIBUTING.md with instructions on how to obtain and configure them.

Branch protection rules documented

Recommended branch protection rules (require PR, require status checks) are documented for repository administrators.

Integration Points

Veritas Prompts

Consumed Prompts
Produced Prompts

Prompt ID	Purpose
`vrt-h8i9j0k1`	GitHub Actions best practices (workflow structure, caching, security patterns)
`vrt-l2m3n4o5`	Security scanning guidelines (CodeQL configuration, SAST tools, dependency review)

When novel CI/CD patterns are discovered:

{
  "id": "vrt-ci-pattern-001",
  "category": "task",
  "status": "draft",
  "content": "Optimized pnpm caching strategy for monorepos",
  "outputPath": "veritas/agent-prompts/devops/ci-pattern-001.json"
}

Target Repositories

All SO1 repositories are CI/CD targets:

so1-io/so1-control-plane-api - Hono backend
so1-io/so1-console - Next.js frontend
so1-io/so1-shared - Shared TypeScript types
so1-io/so1-agents - Agent definitions
so1-io/veritas - Prompt library

Agent	Relationship	Use Case
Railway Deployer	Downstream	Triggered by CD workflow for deployments
Pipeline Auditor	Peer	Reviews generated workflows for security and efficiency
Hono Backend	Creates	Defines the test/build commands used in CI
Next.js Frontend	Creates	Defines the test/build commands used in CI

Source Files

View Agent Source

Repository: so1-io/so1-agents
Path: agents/devops/github-actions.md
Version: 1.0.0

Common Patterns

Matrix Builds

Test across multiple Node.js versions and operating systems:

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

Concurrency Control

Prevent duplicate workflow runs:

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

Required Permissions

Grant minimal permissions for security:

permissions:
  contents: read        # Clone repository
  pull-requests: write  # Comment on PRs
  checks: write         # Update check status

Common Workflow Errors

Error	Cause	Resolution
Workflow syntax error	Invalid YAML	Use GitHub Actions workflow linter
Permission denied	Missing permissions block	Add `permissions:` with required scopes
Cache miss	Wrong cache key pattern	Update cache key to include lock file hash
Timeout	Job running too long	Split into parallel jobs or increase `timeout-minutes`

Next Steps:

Agents Overview

Orchestration

Automation

Engineering

DevOps

Documentation

Prompts

Incident

GitHub Actions Engineer

GitHub Actions Engineer

Quick Reference

Overview

Core Capabilities

Workflow Generation

Job Optimization

Secret Management

Branch Protection

When to Use

Usage Examples

Outputs

Workflow Files

Secrets Documentation

Caching Strategies

FORGE Gate Compliance

Entry Gates (Pre-conditions)

Exit Gates (Post-conditions)

Integration Points

Veritas Prompts

Target Repositories

Source Files

View Agent Source

Common Patterns

Matrix Builds

Concurrency Control

Required Permissions

Common Workflow Errors

Agents Overview

Orchestration

Automation

Engineering

DevOps

Documentation

Prompts

Incident

​GitHub Actions Engineer

​Quick Reference

​Overview

​Core Capabilities

Workflow Generation

Job Optimization

Secret Management

Branch Protection

​When to Use

​Usage Examples

​Outputs

​Workflow Files

​Secrets Documentation

​Caching Strategies

​FORGE Gate Compliance

​Entry Gates (Pre-conditions)

​Exit Gates (Post-conditions)

​Integration Points

​Veritas Prompts

​Target Repositories

​Related Agents

​Source Files

View Agent Source

​Common Patterns

​Matrix Builds

​Concurrency Control

​Required Permissions

​Common Workflow Errors

GitHub Actions Engineer

Quick Reference

Overview

Core Capabilities

When to Use

Usage Examples

Outputs

Workflow Files

Secrets Documentation

Caching Strategies

FORGE Gate Compliance

Entry Gates (Pre-conditions)

Exit Gates (Post-conditions)

Integration Points

Veritas Prompts

Target Repositories

Related Agents

Source Files

Common Patterns

Matrix Builds

Concurrency Control

Required Permissions

Common Workflow Errors