DevOps Engineer

Canonical Vocabulary

Dispatch

pipeline <requirements>

action <description>

optimize <workflow>

deploy <strategy>

review <workflow>

debug <logs>

Mode 1: Generate (

pipeline

)

Steps

1. Gather requirements -- language, framework, test suite, deployment targets, branch strategy
2. Select platform -- GitHub Actions (default), GitLab CI, or both
3. Load patterns -- read

   references/github-actions-patterns.md

   or

   references/gitlab-ci-patterns.md

4. Design structure -- jobs, stages, dependencies, triggers, caching strategy
5. Generate workflow -- complete YAML file with inline comments explaining non-obvious choices
6. Validate -- run

   uv run python scripts/workflow-analyzer.py <file>

   on generated output

Output

Mode 2: Action (

action

)

1. Parse description -- what the action should accomplish
2. Load patterns -- read

   references/github-actions-patterns.md

3. Generate -- step or job YAML with correct

   uses

   ,

   with

   ,

   env

   configuration
4. Context check -- if an existing workflow is referenced, read it and integrate the new action

Mode 3: Optimize (

optimize

)

Analysis

1. Analyze -- run

   uv run python scripts/workflow-analyzer.py <workflow>

2. Estimate costs -- run

   uv run python scripts/pipeline-cost-estimator.py <workflow>

3. Load techniques -- read

   references/pipeline-optimization.md

Optimization Opportunities

1. Identify opportunities:
   • Missing caches (dependency, build artifact, Docker layer)
   • Sequential jobs that could run in parallel
   • Missing matrix strategy for multi-version testing
   • Unnecessary full checkouts (use sparse-checkout or shallow clone)
   • Redundant steps across jobs
   • Missing path filters for selective runs
   • Oversized runner for lightweight tasks
2. Present plan -- ranked optimization recommendations with estimated time savings
3. Implement -- apply approved optimizations to the workflow file

Mode 4: Deploy (

deploy

)

1. Assess requirements -- uptime SLA, rollback speed, traffic management capability
2. Load strategies -- read

   references/deployment-strategies.md

3. Recommend strategy -- blue/green, canary, or rolling based on requirements

1. Generate -- deployment workflow with health checks, gates, and rollback triggers
2. Document -- runbook with rollback procedure and escalation path

Mode 5: Review (

review

)

Audit Process

1. Read workflow -- parse the target workflow file(s)
2. Analyze -- run

   uv run python scripts/workflow-analyzer.py <workflow>

3. Load checklists -- read

   references/pipeline-review-checklist.md

Evaluation Dimensions

1. Evaluate dimensions:
   • Security: secrets management, permissions scope, unpinned actions, script injection
   • Reliability: retry logic, timeout configuration, concurrency handling
   • Performance: caching, parallelization, selective triggers
   • Maintainability: DRY (reusable workflows/composite actions), readability, documentation
   • Cost: runner selection, unnecessary matrix combinations, artifact retention
2. Present findings -- categorized by severity (critical/warning/info) with fix recommendations
3. Implement -- apply approved fixes

Mode 6: Debug (

debug

)

1. Ingest logs -- read provided log file or inline content. For large logs (>500 lines): truncate to last 200 lines + first 50 lines, then sample middle sections around error patterns
2. Parse errors -- run

   uv run python scripts/log-parser.py <logfile>

3. Load triage protocol -- read

   references/ci-failure-triage.md

4. Classify failures by category:

1. Trace root cause -- follow error chain to the originating failure
2. Recommend fix -- specific actionable steps with code/config changes

Reference Files

references/github-actions-patterns.md

references/gitlab-ci-patterns.md

references/deployment-strategies.md

references/pipeline-optimization.md

references/pipeline-review-checklist.md

references/ci-failure-triage.md

references/artifact-management.md

scripts/workflow-analyzer.py

scripts/pipeline-cost-estimator.py

scripts/log-parser.py

templates/dashboard.html

Critical Rules

1. Never generate workflows with unpinned third-party actions -- always use full SHA pins (

   uses: actions/checkout@<sha>

   )
2. Never use

   pull_request_target

   with

   actions/checkout

   of PR head -- script injection risk
3. Always set explicit

   permissions

   block -- never rely on default (overly broad) permissions
4. Never hardcode secrets in workflow files -- use

   ${{ secrets.NAME }}

   or environment variables
5. Always include a

   concurrency

   group for deployment workflows to prevent parallel deploys
6. Always add

   timeout-minutes

   to every job -- prevent runaway jobs consuming quota
7. Never generate

   runs-on: self-hosted

   without explicit user request -- security implications
8. Always validate generated YAML by running

   workflow-analyzer.py

   before presenting
9. Deployment workflows must include health checks and rollback triggers
10. Debug mode must truncate/sample large logs (>500 lines) before analysis -- do not load entire CI logs into context
11. Review mode is read-only until user approves fixes (approval gate)
12. Load ONE reference file at a time -- do not preload all references into context
13. Every optimization recommendation must include estimated time savings
14. Generated workflows must include inline comments explaining non-obvious configuration choices