ci-generate · diff

v1.0.0 to v1.0.0

25 added, 46 removed. Audit A to A.

---

name: ci-generate

description: Generate a production-ready CI/CD pipeline config (GitHub Actions,

GitLab CI, CircleCI, or Jenkins) by discovering the project's actual stack,

test/build commands, and dependencies. Use when setting up CI for a new

project, adding a missing workflow file, or asked to create/generate a

pipeline, workflow, or `.gitlab-ci.yml`/`Jenkinsfile`. Not for writing a

Dockerfile itself (see docker-init), this only wires CI stages around one.

Not for running existing CI checks locally (use ci-local), this skill only

authors the pipeline file itself.

metadata:

summary: "Generate a production-ready CI/CD pipeline config (GitHub Actions, GitLab CI, CircleCI, Jenkins)"

author: mgiovani

version: 1.0.0

disable-model-invocation: true

---

# CI/CD Pipeline Generator

- Generate a CI/CD pipeline config for the detected project stack, with stages for lint, test, build, security scan, and deploy. Start by parsing the arguments passed to this skill invocation (platform, `--deploy`, `--monorepo`): see Phase 0 below.

+ Generate a CI/CD pipeline config for the detected project stack, covering lint, test, build, security, and (when requested) deploy. Start by parsing the arguments passed to this skill invocation (platform, `--deploy`, `--monorepo`): see Phase 0 below.

## Anti-hallucination guidelines

Pipeline configurations must always match actual project tooling. This is critical:

1. Discover before generating: never assume the project's tooling, check what it actually uses first.

2. Verify commands exist: check the project's own config (e.g. `package.json` scripts, `Makefile` targets) before referencing them.

3. Match real versions: use the actual language/runtime version pinned in the project's own config files, not a guess.

4. No phantom dependencies: only include services (Redis, PostgreSQL, etc.) confirmed in project dependencies.

5. Platform-specific syntax: each CI platform has distinct YAML structure, so never mix syntax between platforms.

## Workflow

### Phase 0: Parse Arguments

Extract configuration from the arguments passed to this skill:

```

Arguments:

- <platform>: Target CI platform (default: auto-detect from existing config)

- "github" or "gh": GitHub Actions

- "gitlab" or "gl": GitLab CI

- "circle" or "circleci": CircleCI

- "jenkins": Jenkins (Jenkinsfile)

- "--deploy <target>": Deployment target (optional)

- "vercel", "netlify", "aws", "gcp", "azure", "docker", "k8s", "fly", "railway"

- "--monorepo": Generate matrix/path-filtered workflows

- No args: Auto-detect platform from existing CI config files, default to GitHub Actions

If no platform specified, detect from existing files:

- `.github/workflows/*.yml` → GitHub Actions

- `.gitlab-ci.yml` → GitLab CI

- `.circleci/config.yml` → CircleCI

- `Jenkinsfile` → Jenkins

- No CI config found → Default to GitHub Actions

```

### Phase 1: Project Stack Detection

Explore the codebase to discover the complete project technology stack.

### Phase 2: Research Best Practices (only if needed)

`references/platform-patterns.md` already ships current, comprehensive patterns for Node/Python/matrix/Docker/deploy across all four platforms: check it first. Only reach for WebSearch when the detected stack/platform combo isn't covered there (e.g. an unusual language or a deploy target not in the reference):

```

Use WebSearch:

- query: "[detected platform] CI/CD best practices [detected language] [current year]"

Use WebSearch:

- query: "[detected platform] security scanning pipeline [detected language] [current year]"

```

Focus on:

- Caching strategies for the detected package manager

- Recommended runner images and versions

- Security scanning tools appropriate for the language

- Deployment best practices for the target platform

- Matrix testing strategies if multiple versions needed

### Phase 3: Design Pipeline Architecture

- Based on discovery and research, design the pipeline with these stages. For platform-specific triggers and syntax conventions (caching included), see [references/platform-patterns.md](references/platform-patterns.md).

- Standard stages (always include):

- 1. Lint & Format Check

- - Run linter discovered in Phase 1 (e.g., `ruff check`, `eslint`)

- - Run formatter check if available (e.g., `ruff format --check`, `prettier --check`)

- - Run type checker if applicable (e.g., `pyright`, `tsc --noEmit`)

- 2. Test

- - Run test suite with discovered test command

- - Include coverage reporting if configured

- - Set up service containers if tests require databases/caches

- - Consider matrix testing for multiple runtime versions

- 3. Build

- - Run build command if applicable (e.g., `npm run build`, `cargo build --release`)

- - Build Docker image if Dockerfile exists

- - Generate artifacts for deployment

+ Based on discovery and research, derive the stages from what the repo actually uses. For platform-specific triggers and syntax conventions (caching included), see [references/platform-patterns.md](references/platform-patterns.md).

- 4. Security Scan

- - Dependency vulnerability scanning (language-appropriate tool)

- - Static analysis if available for the language

- - Container scanning if Docker is used

- - Secret detection

+ The generated pipeline must meet these goals. Map each to the repo's own tooling from Phase 1; skip a goal only when the repo has nothing to satisfy it, and say so in the summary:

- 5. Deploy (if `--deploy` specified or deployment config detected)

- - Environment-specific deployment steps

- - Staging/production separation

- - Post-deployment health checks

- - Thread the built artifact reference into the deploy step. The Build stage must expose the image tag/digest it just produced (job `outputs`, `GITHUB_OUTPUT`, an artifact file, etc.), and the deploy step must consume that same reference: rendering it into a task definition, `helm upgrade --set image.tag=<ref>`, `kubectl set image deployment/<name> <container>=<ref>`, or equivalent. Never emit a blind restart (`aws ecs update-service --force-new-deployment`, `kubectl rollout restart` with no image change) as the whole deploy step: if the target pins an image tag/digest, a blind restart just re-pulls the OLD image and ships nothing new.

+ - Fails fast: lint and type checks run first or in parallel, and a failure there cancels the slow jobs.

+ - Runs the test suite the repo already uses, with its real command and any service containers (database, cache) the tests need, plus coverage if configured. Use a runtime-version matrix only if the project supports several versions.

+ - Builds what ships (app build, Docker image if a Dockerfile exists) and keeps the artifacts later jobs need.

+ - Catches vulnerable dependencies and leaked secrets, plus static-analysis findings where the language has a standard tool. Scan the container image if one is built.

+ - Caches dependency installs keyed on the lockfile.

+ - Pins third-party actions, orbs and images to a SHA or exact tag, never `latest` or a moving branch.

+ - Grants least-privilege permissions: a read-only token by default on GitHub Actions, widened per job only where a step needs it.

+ - Deploys only when `--deploy` is given or deployment config is detected: staging and production are separate, a health check follows the deploy, and the built artifact reference is threaded into the deploy step. The Build job must expose the image tag/digest it produced (job `outputs`, `GITHUB_OUTPUT`, an artifact file, etc.), and the deploy step must consume that same reference: rendering it into a task definition, `helm upgrade --set image.tag=<ref>`, `kubectl set image deployment/<name> <container>=<ref>`, or equivalent. Never emit a blind restart (`aws ecs update-service --force-new-deployment`, `kubectl rollout restart` with no image change) as the whole deploy step: if the target pins an image tag/digest, a blind restart just re-pulls the OLD image and ships nothing new.

Design decisions:

- Parallelism: lint, test, and security scan run in parallel when possible.

- - Fail fast: lint stage runs first for the fastest feedback.

- - Caching: cache dependency installation for faster runs.

- Branch strategy: main/master triggers deploy, while PRs trigger lint+test+build.

- Artifacts: build outputs passed between stages where needed.

### Phase 4: Generate Pipeline Configuration

Generate the complete CI/CD configuration file based on the designed architecture.

For platform-specific syntax and patterns, consult:

- [references/platform-patterns.md](references/platform-patterns.md) - Detailed YAML patterns for each platform

File locations by platform:

| Platform | File Path |

|----------|-----------|

| GitHub Actions | `.github/workflows/ci.yml` |

| GitLab CI | `.gitlab-ci.yml` |

| CircleCI | `.circleci/config.yml` |

| Jenkins | `Jenkinsfile` |

Generation guidelines:

1. Use discovered commands exactly (do not invent scripts)

- 2. Pin action/orb/image versions to specific tags (not `latest`)

+ 2. Pin action/orb/image versions (see the pinning goal in Phase 3)

3. Include inline comments explaining non-obvious configuration

4. Set appropriate timeouts for each job

5. Use environment variables for configurable values

6. Follow the platform's recommended project structure

If an existing CI config exists:

- Read the existing file first

- Ask the user whether to replace or augment

- Preserve any custom configuration the user has added

- Merge new stages with existing ones where appropriate

### Phase 5: Validate & Present

- #### Step 5.1: Syntax Validation

- Validate the generated configuration:

+ #### Step 5.1: Validate, Fix, Re-validate

- ```bash

- # Any YAML-based platform (GitHub Actions, GitLab CI, CircleCI) — parse the generated file

- python3 -c "import yaml; yaml.safe_load(open('<config_file>'))"

+ Run the platform's validator on the generated file, fix every reported error in the file, and run it again. Stop when it is clean or after 3 rounds, then report what still fails.

- # GitLab CI — prefer the project's own linter if available

- gitlab-ci-lint .gitlab-ci.yml 2>/dev/null || python3 -c "import yaml; yaml.safe_load(open('.gitlab-ci.yml'))"

+ | Platform | Validator | Install |

+ |----------|-----------|---------|

+ | GitHub Actions | `actionlint <workflow_file>` | `brew install actionlint` |

+ | GitLab CI | `glab ci lint` | `brew install glab` |

+ | CircleCI | `circleci config validate` | `brew install circleci` |

+ | Jenkins | the declarative linter, if the Jenkins instance is reachable (`curl -X POST -F "jenkinsfile=<Jenkinsfile" $JENKINS_URL/pipeline-model-converter/validate`) | none |

- # CircleCI — prefer the project's own CLI if available

- circleci config validate 2>/dev/null || python3 -c "import yaml; yaml.safe_load(open('.circleci/config.yml'))"

+ If no validator is available, say so in the summary and do the minimum YAML parse for YAML platforms:

- # Jenkins — Jenkinsfile is Groovy, not YAML; no local parser available, so

- # just re-read the generated file for obvious syntax errors (unbalanced

- # braces/quotes) instead of skipping validation

+ ```bash

+ python3 -c 'import yaml,sys;yaml.safe_load(open(sys.argv[1]))' <config_file>

```

+ A Jenkinsfile is Groovy, not YAML: without the linter, re-read it for unbalanced braces and quotes.

#### Step 5.2: Cross-Reference Check

Verify all referenced commands and paths exist:

1. Every script/command in the pipeline exists in the project

2. Every referenced file path is valid

3. Service versions match project requirements

4. Environment variable names are consistent

5. If a deploy stage exists, its deploy step references the image tag/digest (or equivalent build artifact) produced by the Build stage, not a blind restart with no reference to what was just built

#### Step 5.3: Present Summary

Output a summary including:

- Pipeline architecture overview

- Stages and their purposes

- Trigger conditions (which branches, PR events)

- Required secrets/environment variables to configure

- Cache strategy explanation

- Any manual steps needed (e.g., setting up deployment secrets)

Do not estimate run time per stage: it hasn't run yet and any number would be a guess.

## Handling Ambiguity

If encountering unclear requirements:

1. Ask the user to clarify platform choice, deployment target, or branching strategy.

2. Present options with trade-offs when multiple valid approaches exist.

3. Default to the most common configuration for the detected stack.

## Usage Examples

```bash

# Auto-detect everything

ci-generate

# Specify platform

ci-generate github

ci-generate gitlab

ci-generate circleci

ci-generate jenkins

# With deployment target

ci-generate github --deploy vercel

ci-generate gitlab --deploy docker

ci-generate github --deploy aws

# Monorepo support

ci-generate github --monorepo

# Combined options

ci-generate github --deploy k8s --monorepo

```

## Important Notes

- Discover first: never assume project tooling, always run Phase 1.

- Pin versions: use specific versions for actions, orbs, images, and tools.

- Secrets documentation: list all required secrets so users know what to configure.

- Existing config: always check for and respect existing CI configuration.

- Security by default: include dependency scanning and secret detection in every pipeline.

- Cache effectively: proper caching can reduce CI times by 50-80%.