reusable-workflow-patterns

Reusable Workflow Patterns

This skill provides the catalog, template, and documentation standards used by the Reusable Workflow Builder agent to detect cross-platform CI/CD patterns and produce standardized GitHub Actions reusable workflows.

Supported CI/CD systems for pattern discovery

Pattern categories

• 🏗️ Build — npm/Maven/Docker/language-specific build processes
• 🧪 Test — unit, integration, E2E, security, performance testing
• 🚀 Deploy — cloud (AWS/Azure/GCP), containers, serverless, infrastructure
• 🔒 Security — SAST/DAST, dependency scanning, compliance checks
• 📊 Quality — code coverage, linting, quality gates

Selection criteria

A pattern becomes a reusable workflow when it shows:

• High frequency — 10+ repositories
• Significant complexity — 5+ steps
• Low variation — standardizable
• Clear parameters — configurable inputs

Scan scope

The user controls the scope of analysis. Three modes are supported and can be freely combined:

Always respect the stated scope — never crawl repos or orgs not explicitly provided.

Pattern-recognition workflow

Adapt these steps to the input scope:

1. Scope resolution — never guess a scope. Resolve in this order:

   • Local paths — if the user supplied directories of checked-out repos, use glob/grep over **/.github/workflows/*.yml and *.yaml. Actions accepts both, so searching only one silently misses workflows. This is the only fully offline path; prefer it in regulated environments.

   • Explicit org-name/repo-name entries — use directly, no enumeration.

   • org-name entries — enumerate only after the capability probe in migration-core reports NETWORK_OK:

     gh api "orgs/ORG/repos?per_page=100" --paginate --jq '.[] | select(.archived|not) | .full_name'
     

     --paginate walks every page, so the result is the complete visible set. Do not substitute gh repo list --limit N — it stops at N, and a truncated list makes the frequency analysis below wrong in a way that looks right. If pagination fails partway, stop and report it rather than analysing a partial set.

   • Deduplicate if a repo appears both via org scan and explicit reference.

   • If no scope can be resolved, stop and ask — do not invent one.

2. Universal pipeline discovery — search each repo for CI/CD files across all supported systems (see table above).

3. Cross-platform content analysis — retrieve and parse configurations.

4. Universal pattern extraction — identify common structures and steps.

5. Cross-system frequency analysis — count pattern occurrences across the resolved repo set.

   • When scope is a single repo or a small explicit list, lower the frequency threshold (see Selection criteria) — a pattern present in 3+ files within a monorepo is still worth extracting.

6. Translation scoring — rank by frequency, complexity reduction, and GitHub Actions conversion feasibility.

7. Platform mapping — map equivalent concepts to GitHub Actions.

Reusable workflow template

name: Reusable Node.js Build Workflow
on:
  workflow_call:
    inputs:
      node-version:
        description: 'Node.js version to use'
        required: false
        default: '18'
        type: string
      build-command:
        description: 'Custom build command'
        required: false
        default: 'npm run build'
        type: string
    outputs:
      build-success:
        description: 'Build success status'
        value: ${{ jobs.build.outputs.success }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # ✅ Only verified actions from trusted publishers
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: 'npm'
      - run: npm install
      - run: ${{ inputs.build-command }}

Output file rules

For every reusable workflow produced, create exactly two files:

1. .github/workflows/reusable-<name>.yml — the reusable workflow (workflow_call trigger only)
2. docs/<name>-usage.md — the usage documentation (one per workflow, 1:1)

Never create: README.md, WORKFLOWS.md, consolidated docs, scripts (.sh, .bat, .ps1, .py, .js), custom actions, caller workflows, or workflow templates.

Usage documentation template

Each docs/<name>-usage.md must contain:

# Reusable [Workflow Name] Usage Guide

## Pattern Analysis Summary
- **Frequency**: Found in X repositories across Y organizations
- **Source CI/CD Systems**: [List systems: GitHub Actions, GitLab CI, Jenkins, etc.]
- **Complexity Reduction**: [Explain how this replaces X previous steps]

## Migration Benefits
- **From GitLab CI**: [If applicable, before/after]
- **From Jenkins**: [If applicable, before/after]
- **From Azure DevOps**: [If applicable, before/after]
- **Standardization**: [Consistency improvements]

## Basic Usage Example
```yaml
name: Example Workflow
on: [push, pull_request]

jobs:
  job-name:
    uses: ./.github/workflows/reusable-[name].yml
    with:
      param1: 'value1'
      param2: 'custom-value'
```

## Advanced Usage Example
```yaml
name: Production Workflow
on:
  push:
    branches: [main]

jobs:
  job-name:
    uses: ./.github/workflows/reusable-[name].yml
    with:
      param1: 'production-value'
      param2: 'advanced-setting'
    secrets:
      SECRET_NAME: ${{ secrets.SECRET_NAME }}
```

## Input Parameters Reference
| Parameter | Description   | Required | Default     | Example    |
| --------- | ------------- | -------- | ----------- | ---------- |
| param1    | [Description] | Yes      | -           | `'value'`  |
| param2    | [Description] | No       | `'default'` | `'custom'` |

## Output Reference
| Output  | Description   | Type   |
| ------- | ------------- | ------ |
| output1 | [Description] | string |

## Migration Examples
### From GitLab CI
**Before (.gitlab-ci.yml):**
```yaml
[Show original GitLab CI configuration]
```

**After (GitHub Actions):**
```yaml
[Show how to use this reusable workflow instead]
```

### From Jenkins
**Before (Jenkinsfile):**
```groovy
[Show original Jenkins configuration]
```

**After (GitHub Actions):**
```yaml
[Show how to use this reusable workflow instead]
```

## Best Practices
- [Specific best practices for using this workflow]
- [Security considerations]
- [Performance tips]

Quality and security requirements

• Verified publishers only: prioritize actions/*, azure/*, aws-actions/*, google-github-actions/*
• Latest stable versions of all actions, pinned to commit SHA (see migration-core guardrails)
• Trigger: workflow_call only
• Location: .github/workflows/reusable-<name>.yml
• Validation: every workflow must pass actionlint