# Github Actions

> GitHub Actions workflow authoring for AI coding agents. Analyzes a repo's project type, language, and deployment targets, then generates production-grade CI/CD workflows with security hardening, caching, and optimization. Handles greenfield, brownfield, and audits. Use when the user requests GitHub Actions workflows: CI pipelines, CD deployments, release automation, or scheduled jobs, or when existing workflows need auditing, optimizing, or hardening. Triggers on phrases like "set up CI", "add CI/CD", "deploy on tag", "publish to npm/PyPI", "harden this pipeline", "pin actions to SHA", "OIDC", or "audit my workflows", and when creating or editing files under `.github/workflows/`, `action.yml`/`action.yaml`, or `.github/dependabot.yml`. Also triggers when migrating from GitLab CI, CircleCI, Travis, Jenkins, or Drone to GitHub Actions. Do NOT use for non-GitHub CI systems unless migrating TO GitHub Actions, or for general bash scripting, Makefiles, or local build config.

- Skill: `mohammaddaoudfarooqi/github-actions` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add mohammaddaoudfarooqi/github-actions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mohammaddaoudfarooqi/github-actions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: mohammaddaoudfarooqi (https://skillmd.com/u/mohammaddaoudfarooqi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mohammaddaoudfarooqi/github-actions

---


# GitHub Actions Workflow Authoring

Generate production-grade GitHub Actions workflows from systematic repository
analysis. Every workflow is security-hardened, performance-optimized, and
verified against the codebase.

## Workflow Router

Determine the workflow type before starting. This drives which phases apply,
which templates to use, and whether to write from scratch or edit existing
workflows.

```
Do any GitHub Actions workflows already exist?
  (.github/workflows/*.yml or .github/workflows/*.yaml)
  |
  NO --> GREENFIELD (no workflows exist)
  |       Phases: Discover -> Plan -> Write -> Verify
  |
  YES --> What type of change?
           |
           +-> New feature/service needs a pipeline
           |     --> WORKFLOW ENHANCEMENT (brownfield)
           |     Phases: Discover -> Audit Existing -> Plan (delta) -> Write -> Verify
           |
           +-> Existing workflow needs fixing/updating
           |     --> WORKFLOW UPDATE (brownfield)
           |     Phases: Discover -> Audit Existing -> Plan (delta) -> Write (edit) -> Verify
           |
           +-> Workflows exist but have security/performance issues
           |     --> WORKFLOW AUDIT (brownfield)
           |     Phases: Discover -> Audit Existing -> Plan (assessment) -> Write (edit) -> Verify
           |
           +-> User wants a specific workflow rewritten
           |     --> TARGETED REWRITE (brownfield)
           |     Phases: Discover -> Audit Existing (single workflow) -> Write (replace) -> Verify
           |
           +-> User wants a specific new workflow type
           |     --> TARGETED NEW WORKFLOW
           |     Phases: Discover -> Write (specific) -> Verify
           |
           +-> Migrating from another CI system
                 --> CI MIGRATION
                 Phases: Discover -> Audit Source CI -> Plan -> Write -> Verify
```

**Signal detection:**

| Signal in request | Likely type |
|-------------------|-------------|
| "Add CI", "add GitHub Actions", "set up CI/CD" (no workflows exist) | Greenfield |
| "Add CI", "add pipeline" (workflows already exist) | Workflow Enhancement |
| "Fix the CI", "workflow is broken", "build fails" | Workflow Update |
| "Workflow is slow", "optimize CI", "reduce build time" | Workflow Audit |
| "Security audit", "harden workflows", "pin actions" | Workflow Audit |
| "Rewrite the CI", "redo the pipeline" | Targeted Rewrite |
| "Add deploy workflow", "add release pipeline" | Targeted New Workflow |
| "Add Docker build", "publish to npm/PyPI" | Targeted New Workflow |
| "Migrate from Jenkins/CircleCI/GitLab" | CI Migration |
| "Add a cron job", "scheduled workflow" | Targeted New Workflow |

---

## Phase 0: Discover Repository

**Always run this phase.** Before writing any workflow, build a complete
picture of the project. See
[references/repo-discovery.md](references/repo-discovery.md) for the full
discovery method.

### What to detect

Read README.md/CLAUDE.md and manifest files first, then work through the
deterministic 12-step detection sequence in
[references/repo-discovery.md](references/repo-discovery.md) (with its
file→tool lookup tables) to establish:

1. **Language and ecosystem** and **package manager** (from manifests and
   lockfiles: package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, etc.)
2. **Framework** (Next.js, Django, Spring Boot, Rails, …)
3. **Build system** (Webpack, Vite, Turborepo, Nx, Gradle, Maven, Make, …)
4. **Test setup** and **lint/format tools** (framework, runner command, config)
5. **Containerization** (Dockerfile, docker-compose, Kubernetes manifests)
6. **Infrastructure as Code** (Terraform, Pulumi, CloudFormation, CDK)
7. **Monorepo signals** (workspace configs, Nx/Turborepo/Lerna)
8. **Deployment targets** (cloud/serverless/Vercel/Netlify/Kubernetes config)
9. **Existing CI** (`.github/workflows/*.yml`, plus other systems: `.circleci/`,
   Jenkinsfile, `.gitlab-ci.yml`, `.travis.yml`)
10. **Branch and release strategy** (default branch, protected/release
    branches, tags, GitHub Releases, changelogs, version files)

### Output: Repository Profile

Compile the detected attributes into a mental model (do not write a file
unless requested) using the Composite Profile format in
[references/repo-discovery.md](references/repo-discovery.md#composite-profile).
This profile drives every subsequent phase.

---

## Phase 1: Audit Existing Workflows (Brownfield Only)

**Skip this phase for greenfield projects.**

Before planning or writing anything, understand what workflows already exist
and assess their state.

### Read every existing workflow

For each `.github/workflows/*.yml` file found in Phase 0:

1. **Read it fully.** Parse the YAML structure: triggers, permissions, jobs,
   steps, secrets usage, caching, matrix strategies.
2. **Classify its purpose**: CI (test/lint/build), CD (deploy), Release
   (publish/tag), Maintenance (dependabot, stale issues), Scheduled (cron jobs).
3. **Note its conventions**: naming style, job naming, step naming, comment
   style, environment variable patterns.
4. **Assess security posture**: permissions declared? Actions pinned by SHA?
   Secrets handling? Fork protections? OIDC usage?
5. **Assess performance**: caching used? Unnecessary steps? Job parallelism?
   Matrix strategy? Concurrency groups?

### Existing workflow inventory

Build a mental inventory:

```
Existing Workflow Inventory
  [file path] | [purpose] | [triggers] | [security: good/fair/poor] | [performance: good/fair/poor]
  ci.yml       | CI        | push, PR   | fair (unpinned actions)    | fair (no caching)
  deploy.yml   | CD        | push main  | good (OIDC, pinned)        | good
  ...
```

### What to preserve in brownfield

| Content Type | Example | Preserve? |
|-------------|---------|-----------|
| Working trigger logic | Path filters, branch filters | Always |
| Environment-specific secrets | AWS credentials, deploy tokens | Always |
| Custom scripts/steps | Project-specific build logic | Always |
| Concurrency groups | Existing cancel-in-progress logic | Always |
| Job dependencies | Established `needs:` chains | Default yes |
| Unpinned actions | `uses: actions/checkout@v4` | Replace with SHA pin |
| Overly broad permissions | `permissions: write-all` | Replace with least privilege |
| Duplicated logic | Same steps in multiple workflows | Refactor to reusable |
| Dead workflows | Workflows for removed features | Remove |

**Rule: Working workflows are valuable.** A workflow that runs correctly is
better than a theoretically perfect one that breaks. Preserve working logic
and improve incrementally.

### Brownfield conventions contract

Extract the workflow conventions from existing files and follow them:

- **File naming**: kebab-case? snake_case? What prefix/suffix patterns?
- **Job naming**: How are jobs named? Descriptive or terse?
- **Step naming**: Named steps or anonymous? Style of names?
- **Comment style**: Are inline comments used? YAML comments?
- **Secret naming**: Convention for secret names (SCREAMING_SNAKE, etc.)?
- **Environment patterns**: How environments are used (if at all)?

**Match existing conventions.** Do NOT impose new conventions on a brownfield
project unless the user explicitly requests a style change.

---

## Phase 2: Plan Workflows

### Greenfield planning

Derive a complete CI/CD plan from the repository discovery.

#### Pipeline architecture

Every project needs at minimum:

1. **CI workflow** (pull request validation):
   - Lint/format check
   - Type check (if applicable)
   - Unit tests
   - Build verification

2. **CI workflow** (main branch):
   - Everything in PR CI, plus:
   - Integration tests (if applicable)
   - Artifact building
   - Trigger CD (if applicable)

3. **CD workflow** (if deployment target exists):
   - Build artifacts/containers
   - Deploy to environments (staging, production)
   - Environment protection rules

4. **Release workflow** (if library or publishable):
   - Version bumping
   - Package publishing (npm, PyPI, Maven, crates.io)
   - GitHub Release creation

5. **Maintenance workflows** (recommended):
   - Dependabot configuration
   - Stale issue/PR management
   - Scheduled security scans

#### Workflow plan algorithm

Based on the repository profile from Phase 0:

```
FOR EACH detected language:
  -> Add CI job: setup + install + lint + test + build
  -> Select template from references/workflow-templates.md

IF Dockerfile exists:
  -> Add Docker build/push job
  -> Select registry (GHCR by default)

IF IaC files exist:
  -> Add infrastructure validation job (plan on PR, apply on merge)

IF monorepo detected:
  -> Add change detection job
  -> Make CI jobs conditional on changed paths
  -> See references/pipeline-patterns.md for monorepo patterns

IF deployment target detected:
  -> Add CD workflow with environment protection
  -> See references/pipeline-patterns.md for deployment patterns

IF library (not service):
  -> Add release/publish workflow triggered by tags

ALWAYS:
  -> Apply security hardening (references/security-hardening.md)
  -> Add concurrency groups
  -> Add caching for dependencies
  -> Set explicit permissions (least privilege)
```

#### Plan output

```
Workflow Plan
- .github/workflows/ci.yml — CI pipeline (lint, test, build) on PR + push main
- .github/workflows/deploy.yml — Deploy to staging/prod with environment protection
- .github/workflows/release.yml — Publish package on tag push
- .github/dependabot.yml — Dependency update automation
```

Present the plan to the user for approval before writing.

### Brownfield planning

**Use the workflow inventory from Phase 1.** Do NOT plan from scratch. Plan
only what changes.

#### Workflow Enhancement: Delta plan

When adding a new workflow to an existing set:

1. Identify which EXISTING workflows might be affected (shared secrets,
   concurrency groups, deployment targets)
2. Identify the NEW workflow to create
3. For existing workflows, specify ONLY what changes (if anything)

```
Workflow Delta Plan
- .github/workflows/ci.yml — KEEP (no changes needed)
- .github/workflows/deploy.yml — MODIFY: add staging environment before prod
- .github/workflows/docker.yml — CREATE: Docker build + push to GHCR
```

#### Workflow Audit: Assessment plan

When auditing existing workflows for security/performance:

1. List all issues found in Phase 1 with severity
2. Propose fixes grouped by category (Security > Performance > Maintenance)
3. For each workflow: KEEP (as-is), EDIT (fix issues), REWRITE (replace),
   DELETE (remove dead workflow)
4. Present to user for approval

```
Audit Findings & Plan
  ci.yml:
    - [Critical] Actions not pinned to SHA → EDIT: pin all actions
    - [High] No permissions declared → EDIT: add least-privilege permissions
    - [Medium] No dependency caching → EDIT: add cache configuration
  deploy.yml:
    - [High] Uses long-lived AWS keys → EDIT: migrate to OIDC
    - [Low] No concurrency group → EDIT: add concurrency
  old-ci.yml:
    - [Low] Duplicate of ci.yml → DELETE
```

#### Targeted Rewrite: Single-workflow plan

When the user asks to rewrite a specific workflow:

1. Read the existing workflow fully (done in Phase 1)
2. Identify what to PRESERVE (working trigger logic, secrets, custom scripts)
3. Identify what to REPLACE (insecure patterns, poor performance, outdated actions)
4. Identify what to ADD (missing security, caching, concurrency)
5. Present the plan

```
Rewrite Plan: ci.yml
  PRESERVE: Trigger logic (push/PR), test matrix (Node 18/20), deploy job dependency
  REPLACE:  Unpinned actions (pin to SHA), npm install (use npm ci + caching),
            missing permissions (add least-privilege)
  ADD:      Concurrency group, artifact upload for test reports, type checking step
```

**Get user approval before rewriting.**

#### CI Migration plan

When migrating from another CI system:

1. Read the source CI config (.circleci/config.yml, Jenkinsfile, .gitlab-ci.yml)
2. Map each job/stage to a GitHub Actions equivalent
3. Identify feature gaps (some CI features don't map 1:1)
4. Plan the migration as a set of new workflows

```
Migration Plan: CircleCI → GitHub Actions
  CircleCI build job → .github/workflows/ci.yml (lint + test + build)
  CircleCI deploy job → .github/workflows/deploy.yml (with environment protection)
  CircleCI scheduled scan → .github/workflows/security.yml (cron schedule)
  Gap: CircleCI orbs used → Replace with equivalent GitHub Actions
```

Present the plan to the user for approval before writing.

---

## Phase 3: Write Workflows

### Greenfield: Write from scratch

Write each planned workflow using the appropriate template and security rules.
See [references/workflow-templates.md](references/workflow-templates.md) for
ecosystem-specific templates.
See [references/security-hardening.md](references/security-hardening.md) for
security rules.
See [references/pipeline-patterns.md](references/pipeline-patterns.md) for
CI/CD patterns.

#### Writing sequence

Write workflows in this order:

1. **CI workflow** first (validates that the build/test pipeline works)
2. **CD workflow** (deployment depends on CI)
3. **Release workflow** (publishing depends on build)
4. **Maintenance workflows** (dependabot, security scans)

#### Per-workflow process (greenfield)

For each workflow:

1. **Select template**: Choose from references/workflow-templates.md based
   on language/ecosystem detected in Phase 0.
2. **Customize for project**: Replace template placeholders with actual
   commands, paths, versions from the repository profile.
3. **Apply security hardening**: Follow every rule in
   references/security-hardening.md:
   - Set explicit `permissions:` (least privilege)
   - Pin all actions to full SHA
   - Use OIDC for cloud auth where possible
   - Protect secrets from fork exposure
   - Guard against script injection
4. **Add performance optimization**:
   - Add dependency caching (use setup action's built-in cache where available)
   - Add concurrency groups to cancel stale runs
   - Use matrix strategy for multi-version testing
   - Add path filters to avoid unnecessary runs
5. **Verify YAML syntax**: Ensure valid YAML, proper indentation, correct
   GitHub Actions syntax.
6. **Add inline comments**: Explain non-obvious choices (why a specific
   SHA, why a particular cache key, why a permission).

### Brownfield: Edit existing workflows

**Read before writing.** For every workflow you modify, read it fully first
(already done in Phase 1). Never modify a workflow you haven't read.

#### Per-workflow process (brownfield)

For each workflow being modified:

1. **Re-read the workflow.** Confirm your understanding from Phase 1.
2. **Apply only planned changes.** Follow the delta plan from Phase 2.
   Do NOT restructure, restyle, or "improve" sections outside scope.
3. **Match existing conventions.** Use the same naming style, comment style,
   and patterns discovered in Phase 1.
4. **Preserve working logic.** Trigger conditions, environment variables,
   secrets references, and custom scripts survive unless explicitly marked
   for change.
5. **Verify every edit.** Each changed action version, command, or path must
   be verified against the codebase.
6. **Minimize diff.** Change only what needs changing. Smaller diffs are
   easier to review.

#### Brownfield-specific rules

- **Edit, don't rewrite.** Unless the user requests a rewrite, modify the
  existing workflow surgically. Fix the specific issues; leave working
  steps alone.
- **Match existing style.** If existing workflows use `name: Build and Test`
  for jobs, continue that pattern. Do NOT switch to `name: build-and-test`
  because you prefer it.
- **Preserve structure.** Keep the existing job ordering unless it's part of
  the planned changes.
- **Never silently remove steps.** If a step needs removal, note it in your
  plan and confirm with the user. A step that looks unnecessary may have
  a non-obvious purpose.
- **Refactor only what you're asked to change.** Do NOT improve adjacent
  workflows, fix unrelated issues, or add features not in the plan.

#### Targeted Rewrite process

When rewriting a specific workflow (user explicitly requested):

1. **Create from the approved plan.** Write the new version using the
   PRESERVE/REPLACE/ADD breakdown from Phase 2.
2. **Start from the template** in references/workflow-templates.md, then
   transplant preserved logic into the new structure.
3. **For preserved content**: Keep trigger logic, secrets, and custom
   scripts intact.
4. **For replaced content**: Write fresh from repository analysis.
5. **For added content**: Follow greenfield per-workflow process.
6. **Present the full new workflow for review** before replacing.

### Shared: Workflow structure conventions

Every workflow file follows the same skeleton: explicit `name`, explicit
`on:` triggers (never defaults), a least-privilege `permissions:` block, a
`concurrency:` group (`cancel-in-progress: true`, except deploy/release/IaC
workflows — see [references/pipeline-patterns.md](references/pipeline-patterns.md)),
then `jobs:` whose first step is a SHA-pinned `actions/checkout`. The CI
templates in [references/workflow-templates.md](references/workflow-templates.md)
share this exact header (factored into its "Shared CI header" section); start
from a template rather than reconstructing the skeleton by hand.

### Shared: Action version pinning

**Always pin actions to full commit SHA** (with the version tag as an inline
comment); never use tags or branches. See
[references/security-hardening.md](references/security-hardening.md#action-pinning)
for the rule, rationale, and how to find SHAs.

### Shared: Caching strategy

**Prefer setup-action caching over raw `actions/cache` where available** —
setup actions handle cache paths and keys automatically from the lockfile:

| Ecosystem | Cache Method |
|-----------|-------------|
| Node.js | `actions/setup-node` with `cache: 'npm'` (or `pnpm`/`yarn`) |
| Python | `actions/setup-python` with `cache: 'pip'` (or `pipenv`/`poetry`) |
| Go | `actions/setup-go` (cache on by default) |
| Rust | `Swatinem/rust-cache` (Cargo.lock + rustc version) |
| Java | `actions/setup-java` with `cache: 'gradle'` or `'maven'` |
| Ruby | `ruby/setup-ruby` with `bundler-cache: true` |
| Generic | `actions/cache` with a custom lockfile-hash key |

See [references/pipeline-patterns.md](references/pipeline-patterns.md#caching-strategies)
for cache-key design, Docker layer caching, and the .NET NuGet approach.

### Shared: Dependabot configuration

Always recommend adding `.github/dependabot.yml` to keep both the
`github-actions` ecosystem and project dependencies updated. Use the canonical
example (with the per-ecosystem id mapping) in
[references/workflow-templates.md](references/workflow-templates.md#dependabot-configuration).

---

## Phase 4: Verify Workflows

After writing, verify every workflow against the codebase and GitHub Actions
best practices.

### Verification checklist (all workflows)

Each item pairs a requirement with how to detect a violation:

- [ ] **Valid YAML**: proper indentation, no syntax errors
- [ ] **Triggers correct**: events match intent; watch for `on: push` without a
  branch filter (runs on every push)
- [ ] **Permissions declared**: explicit `permissions:` at workflow or job level
  — a missing block defaults to overly broad access
- [ ] **Least privilege**: no unnecessary write permissions
- [ ] **Actions pinned**: every `uses:` is a full SHA — flag any `@vN` or branch ref
- [ ] **Commands exist**: every `run:` references valid scripts/tools/paths, and
  matches the project's actual tooling (e.g. not `npm test` when the project uses `pnpm`)
- [ ] **Secrets referenced correctly**: all `${{ secrets.* }}` names exist; no
  hardcoded credentials in the file
- [ ] **Caching configured**: dependencies cached where possible — flag a setup
  action used without its `cache:` parameter
- [ ] **Concurrency set**: a `concurrency:` group is present (missing → queue buildup)
- [ ] **Branch filters correct**: triggers reference the real default branch (e.g.
  not `master` when default is `main`)
- [ ] **Path filters appropriate**: `paths:` reference directories that actually exist
- [ ] **Matrix strategy sensible**: tested versions current; language/tool versions
  come from the matrix or config, not hardcoded
- [ ] **Artifact handling correct**: upload/download artifact names are consistent
- [ ] **Environment protection**: deploy jobs reference proper environments
- [ ] **No script injection**: untrusted `${{ github.event.* }}` input is never used
  directly in `run:` blocks

### Additional brownfield verification

- [ ] **Preserved logic intact**: Trigger conditions, secrets, and custom
  scripts from existing workflows were not lost
- [ ] **Conventions maintained**: Naming, commenting, and structure style
  match the rest of the existing workflows
- [ ] **No unplanned changes**: Only the sections identified in the delta
  plan were modified
- [ ] **No steps silently removed**: Every removal was in the approved plan
- [ ] **Diff is minimal**: Changes are surgical, not a full rewrite
  (unless Targeted Rewrite was the chosen workflow type)

### Verification method

For each workflow:

1. **Validate YAML syntax** by reading it carefully for indentation and
   structure issues
2. **Check all referenced paths** exist in the repository (scripts, config
   files, directories)
3. **Verify action references** are valid (action exists, SHA is real)
4. **Verify commands** match the project's actual tools and scripts (check
   package.json scripts, Makefile targets, etc.)
5. **Check secret names** match what the project expects (documented in
   README or existing workflows)
6. **Simulate trigger scenarios** mentally: what happens on PR, push to
   main, tag push, schedule?
7. **(Brownfield) Compare against original** to confirm only planned
   changes were made

The "how to detect" hint on each verification checklist item above names the
common errors to look for (unpinned actions, missing permissions, wrong branch
names, dead path filters, wrong commands, missing cache/concurrency, script
injection, hardcoded versions).

---

## Phase 5: Maintenance Strategy

Workflows rot when they fall behind ecosystem changes. Embed maintenance
practices.

### Workflow-as-code principles

- **Version workflows alongside code.** All workflows live in `.github/workflows/`.
- **Review workflow changes in PRs.** Use CODEOWNERS on `.github/` to require
  review for workflow changes.
- **Keep actions updated.** Use Dependabot for GitHub Actions ecosystem updates.
- **Delete dead workflows.** Unused workflows create confusion and security risk.
- **Document non-obvious choices.** Inline comments explain WHY, not WHAT.

### Automated maintenance (recommend to user)

| Tool | Purpose |
|------|---------|
| Dependabot (github-actions ecosystem) | Auto-update action versions |
| actionlint | Lint workflow files for syntax and best practice issues |
| CODEOWNERS on `.github/` | Require review for workflow changes |
| OpenSSF Scorecard | Automated security assessment of CI/CD practices |
| GitHub branch protection | Require status checks to pass before merge |

### Recommend to user

Suggest adding these where relevant:

1. **Branch protection rules**: Require CI to pass before merge
2. **CODEOWNERS**: Protect `.github/` directory
3. **Dependabot**: Keep actions and dependencies updated
4. **actionlint**: Add as a CI step or pre-commit hook
5. **Environment protection rules**: Require approval for production deploys

---

## Failure Recovery

```
Workflow issue
  |
  +-> Can't determine project type
  |     +-> Read more source files and config
  |     +-> Check build scripts in package.json/Makefile
  |     +-> Ask user for clarification
  |
  +-> Conflicting CI config (multiple systems)
  |     +-> Ask user which system is canonical
  |     +-> Treat GitHub Actions as target; other as reference
  |
  +-> Unsure which actions to use
  |     +-> Prefer official actions (actions/*, github/*)
  |     +-> For ecosystem tools, use most-adopted community action
  |     +-> Check references/workflow-templates.md for recommendations
  |     +-> When in doubt, use raw `run:` commands instead of actions
  |
  +-> Existing workflows are complex but fragile (brownfield)
  |     +-> Preserve working logic first
  |     +-> Never rewrite from scratch unless user requests it
  |     +-> Fix one issue at a time, verify between changes
  |
  +-> Monorepo with unclear service boundaries
  |     +-> Look for workspace configs (package.json workspaces, nx.json, turbo.json)
  |     +-> Check for independent package.json/go.mod files in subdirectories
  |     +-> Ask user to confirm service/package boundaries
  |
  +-> Migration from another CI system
  |     +-> Map concepts: jobs->jobs, stages->jobs with needs, orbs->reusable workflows
  |     +-> Not everything maps 1:1 — document gaps
  |     +-> Prioritize: get CI working first, optimize later
  |
  +-> Conventions in existing workflows conflict with best practices (brownfield)
        +-> Follow existing conventions (consistency > correctness)
        +-> Only change conventions if user explicitly requests it
        +-> Exception: always fix critical security issues (unpinned actions,
            missing permissions, script injection) regardless of convention
```

**Never fabricate action names.** If you're unsure an action exists, use a
raw `run:` command instead. Verify action names against known actions.

**Never hardcode secrets.** Always reference `${{ secrets.* }}`.

**Never write workflows you haven't verified.** Check every command, path,
and action reference against the actual repository.

---

## Anti-Patterns

### Security anti-patterns
- **Unpinned actions**: Using `@v4` instead of `@sha` — supply chain attack vector
- **Missing permissions**: No `permissions:` block — defaults to overly broad access
- **Script injection**: Using `${{ github.event.* }}` directly in `run:` blocks
- **Long-lived credentials**: Storing AWS/GCP keys as secrets instead of using OIDC
- **Fork secret exposure**: Running `pull_request_target` with checkout of PR code
- **Overly broad `GITHUB_TOKEN`**: Granting write permissions when read suffices

### Performance anti-patterns
- **No caching**: Reinstalling dependencies from scratch every run
- **No concurrency groups**: Queue buildup on rapid pushes
- **Monolithic workflows**: One huge workflow instead of parallel jobs
- **Unnecessary triggers**: Running full CI on docs-only changes
- **Missing path filters**: Every push triggers every workflow regardless of changes
- **Excessive matrix**: Testing on 12 OS/version combos when 4 would suffice

### Architecture anti-patterns
- **Workflow sprawl**: 20 small workflow files with overlapping triggers
- **Duplicate logic**: Same steps copy-pasted across workflows (use reusable workflows)
- **Missing `needs:`**: Jobs that should be sequential running in parallel
- **No environment protection**: Deploy to production without approval gates
- **No Dependabot**: Actions and dependencies never updated

### Process anti-patterns
- **Treating first draft as final**: Always verify against the codebase
- **Ignoring existing workflows**: Not reading current workflows before modifying
- **Over-engineering**: Adding complex matrix builds for a single-language project
- **Premature optimization**: Adding self-hosted runners before measuring need

---

## Reference Files

- **Repository discovery**: See [references/repo-discovery.md](references/repo-discovery.md)
  for deterministic repository analysis: language detection, ecosystem
  identification, deployment target detection, and monorepo discovery
- **Workflow templates**: See [references/workflow-templates.md](references/workflow-templates.md)
  for complete YAML templates per ecosystem: Node.js, Python, Go, Rust,
  Java, Docker, Terraform, and monorepo configurations
- **Security hardening**: See [references/security-hardening.md](references/security-hardening.md)
  for permissions model, action pinning with current SHAs, OIDC configuration,
  secret management, fork protection, and script injection prevention
- **Pipeline patterns**: See [references/pipeline-patterns.md](references/pipeline-patterns.md)
  for CI/CD patterns: caching strategies, matrix builds, concurrency groups,
  reusable workflows, monorepo change detection, deployment strategies,
  release automation, and scheduled pipelines