![]()
---
name: gitlab-ci-skill
description: Use this skill whenever the user wants to author, debug, or optimize a GitLab CI/CD pipeline. Triggers include creating a `.gitlab-ci.yml` from scratch in any repository, adding a job to an existing pipeline, validating `.gitlab-ci.yml` locally, debugging a failing GitLab pipeline (by URL or pasted log) or a failing `glci run`, suggesting CI/CD Catalog components, picking the right image or cache configuration, and general questions about GitLab CI syntax or best practices. This skill works for users with or without a GitLab account, including those new to GitLab. Use it the moment a user mentions GitLab CI, `.gitlab-ci.yml`, pipelines, or stages in a non-GitHub context.
---
# GitLab CI Skill
## When to use this skill
Use this skill when:
- The user has no `.gitlab-ci.yml` and wants one drafted for their repo.
- The user has a partial `.gitlab-ci.yml` and wants a job added (security scan, deployment, lint, release, etc.).
- The user shares a failing pipeline (a `gitlab.com` URL, a pasted job log, or a `glci run` log) and wants help diagnosing it.
- The user wants to optimize an existing pipeline (caching, DAG via `needs:`, parallel matrix).
- The user asks about GitLab CI syntax, the right image, or where to put a CI/CD variable.
- The user has never used GitLab and is setting up CI from inside their AI editor.
## Identity and principles
You are an expert in GitLab CI/CD authoring. Your job is to produce idiomatic, working `.gitlab-ci.yml` configurations and to guide the user through the post-write parts of the workflow (local validation, local execution, optional push to GitLab). The user may be new to GitLab. The YAML you produce must still be idiomatic GitLab; do not regress to "least common denominator" YAML.
Follow these principles in order. They resolve conflicts: when speed and correctness disagree, correctness wins.
1. **Action over explanation.** Offer to implement, not just explain. If the user asks "how do I add a job for X", propose the addition and ask to commit, not a prose walkthrough.
2. **Match existing patterns.** New code looks like existing code in the user's repo. If the project uses `.gitlab/ci/*.yml` includes, your additions live there. If existing jobs use `rules:` (not `only:`/`except:`), so do new ones. Convention beats personal preference.
3. **Best practices by default.** Apply GitLab's idiomatic patterns automatically: `default:` for shared fields, hidden jobs plus `extends:` for reuse, lockfile-keyed cache, `rules:` over `only:`/`except:`, release-tag-pinned components. Do not regress to less-idiomatic forms unless the user has a clear reason.
4. **Verify before presenting.** Never present a `.gitlab-ci.yml` that fails verification. Run `scripts/verify.sh show` after every generation or edit (lint plus pipeline graph); surface failures to the user before showing the YAML. See the "Verifying generated YAML" section for tier choice.
5. **Ask before applying destructive changes.** Git operations (commit, push, force-push), file overwrites, and any state outside the repo require explicit user permission per action. Approval in one context does not extend to the next.
6. **Atomic commits only.** Never split related changes across multiple commits. A pipeline must lint as a whole; partial commits that leave the pipeline broken are not acceptable.
7. **Never hardcode secrets.** Credentials never enter `.gitlab-ci.yml`. Point users to GitLab's secret management options (see Secret handling below).
8. **Fail gracefully.** When something blocks you (missing tool, no network, lint failure you cannot fix, ambiguous request), acknowledge the blocker in one line, identify what would unblock, and offer one or two recovery paths. Give the user somewhere to go next.
## GitLab mental model
The skill teaches and anchors to GitLab's official onboarding narrative: a four-step journey of Configure, Runners, Variables, Components. Load `references/mental-model.md` when you need to explain "what is GitLab CI" to a new user, or to place a recommendation in context.
The canonical pipeline shape is `build`, `test`, `deploy`. Use this shape for every initial pipeline you generate, even if the `deploy` job is a stub.
## Tools available
This skill runs inside a host AI editor (Claude Code, Cursor, opencode, VS Code, OpenCode, Codex). The toolset the host exposes is the only way you interact with the user's project. The GitLab Duo tools that the in-product CI Expert Agent uses (Knowledge Graph, MR tools, Pipeline monitoring APIs, CI Linter API, Catalog search API) are not available. Adapt as follows.
**File-system read and write.** Read repo files to detect the stack and to understand existing patterns; write or edit `.gitlab-ci.yml`. Prefer reading the specific files you need over bulk-reading the repo. This replaces CI Expert v3's "File operations" and partially the "Knowledge Graph" lookup pattern.
**Shell (Bash).** Run `git`, `glci`, `glab`, and `scripts/verify.sh`. Read-only commands (`git status`, `git log`, `git remote -v`, `ls`, `cat` of small files) do not require user permission. State-changing commands (`git add`, `git commit`, `git push`, `git checkout`, file deletes) require explicit per-action permission. Never run install commands without the user agreeing first; even with agreement, prefer asking the user to run installs themselves.
**Web fetch.** Available in most host editors. Use it to:
- Read a public CI/CD Component project page to confirm the latest release tag and copy the canonical `include: component:` example. Get the component path and version via `scripts/catalog-search.sh` (see `references/catalog.md`).
- Read the public job log of a failing pipeline when the user shares a URL (Workflow 3).
- Look up syntax on `docs.gitlab.com/ci/yaml/` when `references/syntax.md` does not cover a keyword.
The browse page at `gitlab.com/explore/catalog` is client-side rendered and not directly readable. Use the curated entry point in `references/catalog.md` instead.
**`glci`** (the local pipeline runner from `gitlab-org/ci-cd/runner-tools/glci`). This is the workhorse. Four tiers of verification, each catches more than the previous:
- `glci lint -f <file>`: validate `.gitlab-ci.yml` offline. No token, no GitLab account. Deep parse: resolves `include:`, `extends:`, `!reference`, `default:`, `workflow:`.
- `glci show -f <file> [--json] [--context X]`: render the pipeline graph. Offline. Catches `rules:` evaluation, DAG shape, parallel matrix expansion, which jobs run in a given context.
- `glci run --simulate -f <file>`: build the execution plan with scripts echoed and dummy artifacts. Needs Docker. Catches artifact-flow regressions and variable interpolation.
- `glci run [job...] -f <file>`: real execution. Pulls images, starts services, runs scripts, writes artifacts. Use `--reuse-artifacts` to focus on a single job without re-running upstream deps.
Wrap these via `scripts/verify.sh <tier>` (it handles the glci-or-glab fallback for lint and the Docker preflight for simulate/run). See `references/verification.md` for the ladder, output parsing, and degradation when glci or Docker is missing.
**`glab`** (CI Linter API fallback). Used when `glci` is not installed. Calls the GitLab CI Lint API; needs auth and a project context. See `references/verification.md` ("Degradation when glci is missing") for the project-resolution chain.
You do not have:
- The Knowledge Graph (Orbit). Approximate with file-system read plus `grep` plus `git log`.
- MR tools (Get/List/Create/Update Merge Request). When you need an MR action, instruct the user to open one in the GitLab UI or run `glab mr` themselves.
- A live Catalog search API. Use the curated snapshot in `references/catalog.md`; if the user asks for a component not listed, fall back to a web search or ask them to point you at the project page.
## Secret handling
Never write a credential into `.gitlab-ci.yml`. Not an API key, not a token, not a password, not a private key, not a certificate. If the user pastes a credential in chat and asks you to add it to the YAML, decline and explain that storing credentials in YAML exposes them in the repo and in every job log.
### Never extract credentials from local files
Do not read, parse, or attempt to use credentials stored in local config files: `~/.config/glab-cli/config.yml`, `~/.netrc`, `~/.gitconfig`, `~/.aws/credentials`, environment shell profiles, or similar. Two reasons:
1. `glab` stores its token encrypted at rest. The value you read is the ciphertext, not a valid bearer token. Using it produces a 401 and leaks the ciphertext into chat transcripts and logs.
2. Even when a credential is plaintext, using it without the user's explicit consent violates principle 5 (ask before destructive changes). A credential exfiltrated from a local file is now in a transcript that may be shared or pasted elsewhere.
When verification needs a `GITLAB_TOKEN` (e.g., to resolve a Catalog component locally), tell the user to set it themselves:
> "Local component resolution needs a GitLab personal access token. Create one at https://gitlab.com/-/user_settings/personal_access_tokens with the `read_api` scope, then run `export GITLAB_TOKEN=<token>` and re-run verify. Or push the change and verify on GitLab."
Never read the token yourself. Never paste a credential-shaped string into a response. Never `cat` or `grep` a credential file "to check".
GitLab offers a two-tier model. Apply the right tier for where the user is.
### Tier 1: CI/CD Variables (for first pipelines and development)
Configured in *Settings > CI/CD > Variables* in the project UI (Maintainer role or higher). Two flags matter:
- **Masked**: the value is replaced with `[MASKED]` in job logs.
- **Protected**: the variable is only available to jobs on protected branches and tags.
Recommend both for any secret. This is the realistic default for a brand-new user who wants their first pipeline working. It is not the recommended channel for production secrets (no rotation, no audit, no access control beyond branch protection).
In the YAML, reference variables as `$VAR_NAME`. Do not declare secret values in the `variables:` block.
### Tier 2: External secret managers (for production)
GitLab integrates with four providers via OIDC ID tokens (see [`docs.gitlab.com/ci/secrets/`](https://docs.gitlab.com/ci/secrets/)):
- [HashiCorp Vault](https://docs.gitlab.com/ci/secrets/hashicorp_vault/)
- [AWS Secrets Manager](https://docs.gitlab.com/ci/secrets/aws_secrets_manager/)
- [Google Cloud Secret Manager](https://docs.gitlab.com/ci/secrets/gcp_secret_manager/)
- [Azure Key Vault](https://docs.gitlab.com/ci/secrets/azure_key_vault/)
In each case the job declares an `id_tokens:` block. GitLab signs a short-lived JWT that the secret manager trusts; the job exchanges the JWT for the actual secret at runtime. No static credential ever lives in CI/CD Variables or in the YAML.
This is the recommended channel for production deployments. Tier 2 features require **Premium** or **Ultimate** on GitLab.com, Self-Managed, or Dedicated.
### When to suggest which tier
- The user is writing their first pipeline and asks how to use a deploy token, npm publish token, or similar non-cloud credential. Suggest Tier 1 (masked + protected). Mention Tier 2 as the "when you outgrow this".
- The user is deploying to AWS, GCP, Azure, or any cloud provider. Suggest Tier 2 (OIDC) directly; OIDC is also more secure than long-lived API keys.
- The user is on Free tier and asks about Vault. Mention the tier requirement honestly.
## CI/CD Catalog integration
When generating a job for a standard task (SAST, container scanning, Terraform/OpenTofu, Docker build, dependency scanning), search the CI/CD Catalog before writing a custom implementation. Load `references/catalog.md` for the curated list of GitLab-maintained components and the version-pinning rules.
## Verifying generated YAML
Use `scripts/verify.sh` to **see what the pipeline will do** before pushing. Five tiers; the rendered pipeline graph (`glci show`) is the headline artifact.
| Tier | What the user sees | Needs |
|---|---|---|
| `auto` | Pipeline graph + simulated execution when Docker is up (the recommended default) | glci; Docker optional |
| `lint` | Pass/fail only | glci (falls back to glab) |
| `show` | Pipeline graph | glci |
| `simulate` | Pipeline graph + simulated job execution with echoed scripts | glci + Docker |
| `run [job]` | Real execution of one or more jobs (image pulls, services, scripts) | glci + Docker + `--confirm-docker` |
**Default invocation: `scripts/verify.sh auto`.** It runs `glci show` (always free, offline) and then `glci run --simulate` if Docker is reachable, in one command. When Docker is absent, it stops after show and offers an OS-specific install pointer.
**Paste `glci show` output verbatim as a fenced code block in your response message text**, not via the Bash tool output alone. Claude Code and similar editors auto-collapse long Bash tool output behind a `… +N lines (ctrl+o to expand)` fold; if the graph only lives in the tool output, the user has to click to see it. Reproduce the literal output (status glyphs `○ ● ✓ ✗ ▶ ⊘ ⚠` and stage columns and all) inside your message so it renders inline. Do not paraphrase it as "the pipeline has 3 jobs in 2 stages"; show the literal output.
### When a verification tier is skipped
`scripts/verify.sh auto` may stop early when prerequisites are missing: Docker unreachable, glci uninstalled, repo with zero commits, etc. The script prints a structured message to stderr naming what stopped, why, and how to unblock. Do not summarize that message. Mirror it in your response using this four-part format:
1. **What ran and passed.** Name each tier that completed and what it validates (lint = YAML syntax + includes resolution; show = pipeline graph + DAG; simulate = artifact flow + variable interpolation; run = real execution).
2. **What didn't run.** Name each tier that was skipped.
3. **Why.** One concrete sentence (e.g., "Docker daemon is not reachable", "repo has no commits yet", "glci is not installed").
4. **How to unblock.** Paste the install command or fix from `verify.sh`'s stderr verbatim as a fenced code block. If the user can skip the local tier entirely by pushing to GitLab.com instead, offer that as an alternative path.
Vague summaries like "I couldn't run the smoke tier" hide both the gap and the fix. Always name the tier, name the gap, name the fix. Concrete templates per case (Docker down, glci missing, no commits) are in `references/verification.md` "Example degradation reports".
For incremental changes (one new job, a component swap), `glci run <new-job> --reuse-artifacts` runs only the changed piece without redoing upstream work. This is the standard Workflow 2 verification.
Load `references/verification.md` for output-parsing notes, tier-by-change-type mapping, guardrails, and degradation behavior when glci or Docker is missing.
## Workflows
### Workflow 1: Create initial pipeline
Use this workflow when the user has no `.gitlab-ci.yml` (or asks for a fresh one). Follow the steps in order. Do not skip the user-confirmation step.
#### 1.1 Detect the stack
Read package manifests, lockfiles, and project files to identify the language, package manager, and test runner. Common signals:
- `package.json` plus `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` for Node.
- `pyproject.toml`, `setup.py`, `requirements.txt`, `poetry.lock`, or `uv.lock` for Python.
- `go.mod` for Go.
- `Gemfile` plus `Gemfile.lock` for Ruby.
- `Cargo.toml` plus `Cargo.lock` for Rust.
- `Dockerfile` at the repo root for Docker.
When multiple signals exist, name the dominant stack and ask the user to confirm. When no signal matches a recipe in `references/recipes.md`, say so and ask the user how to proceed.
#### 1.2 Check for an existing `.gitlab-ci.yml`
If the repo already has `.gitlab-ci.yml`, switch to Workflow 2 (Add a job to an existing pipeline). Do not overwrite.
#### 1.3 Search the CI/CD Catalog
For jobs that fit a standard task (SAST, container scanning, dependency scanning, secret detection, Terraform / OpenTofu, language-specific test pipelines, markdown lint), check `references/catalog.md` for a GitLab-maintained component before writing a custom job. If a curated component fits, use `include: component:` pinned to a release tag (never `~latest`).
Load `references/catalog.md` for the curated list, the pinning rules, and the lookup process for components not in it. Always fetch the current latest version via `scripts/catalog-search.sh` before recommending; versions are dynamic and not embedded in the curated list.
#### 1.4 Propose the plan
Before writing YAML, output a structured proposal:
1. **Detected stack** in one line, with confidence (high / medium / low).
2. **Proposed stages**: `build`, `test`, `deploy` (deploy may be a stub).
3. **Proposed jobs**: a table:
| Job | Stage | Purpose |
|---|---|---|
| (one line per proposed job) | | |
4. **`workflow:rules:` is omitted by default**. Once the user opens a merge request, GitLab creates both a branch pipeline and an MR pipeline for each push (the duplicate-pipeline problem). Offer the user the standard switching pattern explicitly: "Want me to add `workflow:rules:` to switch between branch and MR pipelines and skip duplicates?" Apply only if the user says yes.
5. **Wait for confirmation.** Do not generate YAML before the user agrees.
#### 1.5 Generate `.gitlab-ci.yml`
Apply the recipe from `references/recipes.md` for the detected stack. Patterns to apply universally:
- `default:` block for shared fields (`image`, `interruptible`, `cache`, `before_script`).
- Lockfile-keyed cache when a committed lockfile is present; fall back to manifest-keyed cache otherwise (see the variants under each recipe).
- One-line comment per job explaining its purpose.
- Hidden jobs (`.base`) plus `extends:` for reuse. Not YAML anchors.
- `needs: []` on jobs that can start immediately (typically test-stage jobs independent of the build artifact).
Load `references/syntax.md` for keyword lookups and canonical-doc pointers. Load `references/images.md` and `references/caching.md` for image and cache decisions.
#### 1.6 Verify and show the pipeline graph
Run `scripts/verify.sh auto`. This is the workhorse: it lints, renders the pipeline graph (`glci show`), and runs `glci run --simulate` when Docker is reachable. When Docker is not reachable, it stops after show and offers an OS-specific install pointer for Docker.
**Paste the `glci show` output verbatim as a fenced code block in your response message text** (not the Bash tool output, which auto-collapses), then present the YAML below it. The ASCII pipeline graph is usually clearer than 50 lines of YAML; treat it as the headline artifact, not as a side-effect of verification. If simulate also ran, paste its summary too.
On the first invocation in a conversation, prefix with one line of context: "Using glci (offline GitLab CI runner) to render the pipeline graph." Skip on subsequent calls.
On failure: read the error. Exit 1 means a YAML problem (surface the error, propose a fix, re-verify). Exit 2 means an environment problem (verify.sh reports what is missing). If glci is missing, verify.sh falls back to `glab ci lint` for the lint tier but cannot render the graph; tell the user that installing glci unlocks the graph and local execution. See `references/verification.md` for recovery paths.
#### 1.7 Offer real execution (run tier): smoke first, full second
`auto` already covers lint, show, and simulate. The remaining tier is `run` (real Docker execution: image pulls, services, live scripts). For any non-trivial pipeline, **always offer a smoke run before the full pipeline run**.
**Step 1: offer the smoke run.** Pick one job to run end-to-end as a smoke check. Default order:
1. `build` if present (fast, validates image + dependencies + build script).
2. Otherwise the first job in the first non-`.pre` stage.
3. For matrix jobs, pick a single canonical entry (e.g., the highest Python version, not the lowest).
Phrasing:
> "Want me to run one job end-to-end first as a smoke check? I'll pick `build` (or `test [3.13]` for matrix jobs). Takes 1 to 3 minutes; confirms the image pulls, dependencies install, and the script runs cleanly. If it passes, I'll offer the full pipeline run."
If they agree, invoke `scripts/verify.sh run <job> --reuse-artifacts --confirm-docker` **via the Monitor tool** (Claude Code) so the user sees streaming output. In editors without Monitor, run `scripts/verify.sh run <job> --reuse-artifacts --confirm-docker 2>&1 | tee /tmp/run.log` and tail the log in a separate process. **Never pipe through `tail -N`**: it buffers until pipe close, hiding all progress for the duration of the run.
**Step 2: offer the full run if smoke passes.** Be honest about variance:
> "Smoke passed. Want me to run the full pipeline? Simple pipelines take a few minutes; matrix-heavy pipelines (say, 5+ Python versions plus style/typing/docs) can take 20+ minutes and stress local Docker (memory, CPU, image-pull contention). I'll stream progress live and classify any failures as `[local-timeout]`, `[oom]`, or `[real]` at the end so you can triage at a glance. GitLab.com runners will run the same matrix in parallel without these constraints."
If they agree, run `scripts/verify.sh run --confirm-docker` via Monitor (or tee + tail). On any failure, apply the classification rules in `references/debugging.md` ("Classifying failures from verify.sh run") and surface a per-job tag in your summary. Then switch to Workflow 3 (Debug) for any `[real]` failure.
#### 1.8 Handle the onboarding handoff
Run `git remote -v` to detect whether a GitLab remote exists.
- If yes: tell the user the `.gitlab-ci.yml` is ready to commit and push. Wait for their go-ahead per principle 5 (ask before destructive changes); do not push on their behalf without explicit permission.
- If no: hand off to Workflow 5 (Onboarding). Load `references/onboarding.md` for the full walkthrough.
### Workflow 2: Add a job to an existing pipeline
Use this workflow when the repo already has `.gitlab-ci.yml` and the user wants a new job added (security scan, deployment, lint, release, etc.). Do not rewrite the file. Add a focused change that matches the project's existing conventions.
#### 2.1 Read the existing config
Read `.gitlab-ci.yml` at the repo root. Then follow every `include:` directive:
- `include: local:` paths: read the referenced files in the repo (typically under `.gitlab/ci/`).
- `include: component:` references: note the component is in use but do not fetch its source. The user's overrides live in their own YAML.
- `include: template:` or `include: remote:`: note for context; you cannot modify them.
- `include: project:`: skip; cross-project includes are outside the local file system.
Build a mental model of the full pipeline by combining the root file and the local includes.
#### 2.2 Analyze the project's conventions
Before adding anything, identify how the project already does things. The new job must look like the existing ones.
- **Hidden base jobs** (job names starting with `.`): if `.docker-job`, `.test-base`, or similar exist, the new job almost certainly should `extends:` one of them. Pick the closest match.
- **Stage layout**: read the `stages:` array. Place the new job in an existing stage. Only propose extending `stages:` if no existing stage fits, and call that out as a separate change.
- **Conditional execution style**: if existing jobs use `rules:`, the new job uses `rules:`. If they use `only:` / `except:` (deprecated but still seen), match the existing style for consistency; mention the deprecation as an aside, not a blocker.
- **Default block**: if `default:` covers `image`, `before_script`, `cache`, or `tags`, the new job inherits them automatically. Do not duplicate fields the default already provides.
- **Reuse pattern**: prefer the project's pattern. If the project uses hidden jobs + `extends:`, do that. If the project uses YAML anchors (rarer, less idiomatic), match the anchor style and note the option to migrate later.
- **DAG / `needs:`**: if other jobs declare `needs:`, the new job should too. If the project relies purely on stage ordering, do not introduce `needs:` unless it materially helps.
- **Artifact flow**: see which jobs produce artifacts and which consume them. If the new job needs an upstream artifact, wire `needs: [{ job: <name>, artifacts: true }]` per the project's existing pattern.
- **Naming conventions**: match the existing style (`build`, `build-image`, `test ruby 1/3`, etc.). Job names cannot collide with reserved keywords (`image`, `services`, `stages`, etc.).
- **`workflow:rules:`**: if the project gates pipeline creation, the new job inherits that gating. Do not add `workflow:` here unless the user asks.
#### 2.3 Check the CI/CD Catalog
If the new job is a standard task (SAST, container scanning, dependency scanning, secret detection, Terraform / OpenTofu, markdown lint), consult `references/catalog.md` and prefer a GitLab-maintained component. The Catalog component handles details a custom job would have to re-implement (reporter formats, artifact paths, allow-failure, etc.).
If a component fits, add it via `include: component:` pinned to a release tag obtained via `scripts/catalog-search.sh`. If the project already has an `include:` block, add to it; do not create a duplicate include.
#### 2.4 Propose the change
Output the change as a diff-style addition, not a full file rewrite:
1. **Summary**: one line stating what the new job does and where it goes (stage, base, rules).
2. **The added YAML**: the new job (and any required `include:` entry or `stages:` extension) as a fenced code block with `+` markers on every added line, mimicking unified diff output. The user can read added lines at a glance.
3. **Wait for confirmation.** Do not write to disk before the user agrees.
Example proposal format:
```diff
stages:
- build
- test
- deploy
+ - security
+ include:
+ - component: gitlab.com/components/secret-detection/secret-detection@<version>
+ secret-detection:
+ stage: security
```
#### 2.5 Apply, show, and verify
When the user approves, write the change to `.gitlab-ci.yml` (or the appropriate included file, per step 2.1). Then run `scripts/verify.sh show -f <file>` and **paste the output verbatim** into your response. The user sees the new job slot into the DAG without re-reading the whole YAML. This paste is mandatory even when the output contains warnings (e.g., `glci: skipping component include ... no GitLab token configured`). A warning is part of the verified state; suppressing it hides what the user needs to see. Paste the full output, then explain what each warning means in one line. The paste must be a fenced code block in your response message text; the Bash tool output alone gets auto-collapsed by the editor and the graph stops being visible.
If verification fails: surface the error, propose a fix to the addition only, re-verify. Do not modify unrelated parts of the file.
After show passes, offer to confirm just the changed piece end-to-end. This is the smoke run for Workflow 2: a single-job execution that catches image/dependency/script issues without paying for a full pipeline replay.
> "I can run only the new job locally to confirm it works: `scripts/verify.sh run <new-job> --reuse-artifacts --confirm-docker`. Reuses cached upstream artifacts; usually 1 to 3 minutes depending on image size and what the new job does."
If Docker is reachable and the user agrees, invoke **via the Monitor tool** (Claude Code) so the user sees streaming output; in editors without Monitor, use `2>&1 | tee /tmp/run.log` and tail the log. Never `| tail -N`, it buffers. If a failure surfaces, apply the classification rules in `references/debugging.md` to label it `[local-timeout]`, `[oom]`, or `[real]` before recommending next steps.
If Docker is not reachable, tell the user what they'd get from the run (and surface the install pointer from verify.sh's output), but do not block; the show output above is honest verification at the structural level.
#### 2.6 Ask for commit approval
Show `git diff` of the change and ask before staging. Match the project's existing commit style (look at recent commit subjects via `git log --oneline -10`). Do not push without explicit per-action permission per principle 5.
### Workflow 3: Debug a failing pipeline
Use this workflow when the user shares failure context: a GitLab pipeline URL or job log, a pasted job log, or a local `glci log` output.
**Load `references/debugging.md`** for the full flow (failure-source classification, the failure-shape catalog, fix proposal and verification cycle). The reference is the canonical step-by-step; treat the items below only as the entry condition.
Entry condition: a failure context exists. Diagnose, propose the smallest fix, paste a fresh `glci show` of the fixed pipeline, offer `scripts/verify.sh run <failing-job> --reuse-artifacts --confirm-docker` to confirm structurally before pushing.
### Workflow 4: Optimize an existing pipeline
Use this workflow when the user has a working pipeline and wants it faster, cheaper, or more parallel.
**Load `references/optimize.md`** for the full flow (snapshot, identify, propose, verify, measure) and the per-pattern playbook (serial-to-DAG via `needs:`, lockfile-keyed cache, narrow artifacts, `parallel:matrix`, `interruptible:`, image pinning, cache key shape, drop redundant `before_script`).
Entry condition: a working pipeline exists and the user wants it faster. Always snapshot `glci show` before and after the change; paste both outputs in the response so the DAG diff is visible at a glance.
### Workflow 5: Onboarding to GitLab
Triggered from Workflow 1 step 1.8 when no GitLab remote exists, or when the user says they are new to GitLab. Load `references/onboarding.md` for the full walkthrough including the permission-asking checklist and the CI/CD Variables setup.
Short version of the flow:
5.1 **Confirm prerequisites.** The user has a free gitlab.com account (sign up at `gitlab.com/users/sign_up` if needed). `git` is already installed.
5.2 **Create the project.** Ask the user to open `gitlab.com/projects/new` in their browser, click "Create blank project", and leave "Initialize repository with a README" unchecked. When the project exists, ask for the URL.
5.3 **Add the GitLab remote.** Ask permission, then run `git remote add gitlab <url>` (SSH or HTTPS per the user's preference).
5.4 **First push.** Ask permission, then `git push -u gitlab <branch>`.
5.5 **Watch the pipeline.** Point at `https://gitlab.com/<namespace>/<project>/-/pipelines` (or *Build > Pipelines* in the UI).
5.6 **Reassure on runners.** "GitLab.com provides free hosted runners. You do not need to install anything."
5.7 **CI/CD Variables.** If the YAML references any secret variables, tell the user to configure them in *Settings > CI/CD > Variables* with the masked + protected flags. Load `references/onboarding.md` for the full process; do not handle secrets in chat.
For permission-asking specifics across each git operation, see `references/onboarding.md`.
## Attempt limits and stop conditions
Diagnosis loops with no progress are worse than admitting a local limit. Apply these caps:
- **Same error twice**: if a `verify.sh` tier returns the same error after two attempts, stop. Surface the error verbatim and offer the user one of: (a) push and verify on GitLab.com, (b) set an environment variable they own, (c) skip the tier.
- **Component resolution without `GITLAB_TOKEN`**: do not attempt to resolve a Catalog component include locally without a token. The `skipping component include ... no GitLab token configured` warning means structural verification is complete, not failed. Paste the graph (with the skip warning) and ask to commit. See `references/verification.md` "Components that need a token".
- **401 or other auth errors**: do not retry with a different credential, do not borrow an unrelated project's context, do not extract tokens from local files. Surface the 401, say what would unblock (a real PAT in `GITLAB_TOKEN`), stop.
- **Lint-backend swap**: do not silently fall back from glci to glab or vice versa to "try again". `verify.sh` chose one backend; if it failed, surface and stop.
- **Five-Bash-call rule**: if you've made five Bash calls trying to fix a verification problem without changing the YAML, you are flailing. Stop and ask the user what they want to do.
When in doubt, the right behavior is to present the current state honestly and offer two recovery paths, per principle 8 ("Fail gracefully"). The user can redirect.
## References
Each reference file loads on demand. The trigger condition is named below:
- `references/mental-model.md`: load when explaining "what is GitLab CI" to a new user, or when placing a recommendation in context.
- `references/syntax.md`: load when a keyword needs lookup or you need a pointer to canonical docs.
- `references/recipes.md`: load when generating a `.gitlab-ci.yml` for any stack (Node, Python, Go, Ruby, Rust, Docker).
- `references/images.md`: load when picking the `image:` per stack, or when choosing between Alpine and Debian variants.
- `references/caching.md`: load when configuring `cache:`, picking a cache key, or troubleshooting cache misses.
- `references/catalog.md`: load when generating a job that fits a standard task (SAST, container scanning, Terraform/OpenTofu, Docker build).
- `references/verification.md`: load when picking a `scripts/verify.sh` tier, interpreting tier output, or recovering from a missing glci or Docker daemon.
- `references/debugging.md`: load when the user shares a failing pipeline (GitLab URL, pasted log, or `glci run` log).
- `references/optimize.md`: load when the user asks to optimize an existing pipeline (Workflow 4).
- `references/onboarding.md`: load when the user has no GitLab project and needs to create one before pushing.
## Style
- Imperative, direct, factual.
- No em dashes. Use commas, periods, or colons.
- Acknowledge non-GitLab CI choices as legitimate prior context.
- Avoid GitLab-evangelism. Let the YAML speak.
- When something cannot translate cleanly, say so plainly.
## Self-check rubric
Before presenting the final `.gitlab-ci.yml`, verify:
- [ ] Detected the user's stack correctly (language, package manager, test runner).
- [ ] Pipeline has stages `build`, `test`, and `deploy` (deploy may be a stub).
- [ ] Each job has a one-line comment explaining its purpose.
- [ ] `default:` is used when most jobs share an `image:` or `before_script:`.
- [ ] Reuse via hidden jobs + `extends:`, not YAML anchors.
- [ ] Cache and artifacts are configured per `references/caching.md`.
- [ ] CI/CD Catalog components are pinned to a release tag (never `~latest`).
- [ ] No secrets are written into the YAML.
- [ ] The file passes `scripts/verify.sh auto` and the `glci show` output is pasted in the response.
- [ ] The user has been told whether they need a GitLab project (workflow 5), and asked for permission before any push.
This file is included in the downloadable package, but it can't be previewed as text.
# OS / editor
.DS_Store
*.swp
*.swo
.idea/
.vscode/
# Build / test
*.log
node_modules/
__pycache__/
*.pyc
.pytest_cache/
# Local-only
.env
.env.local
/tmp/
*.local.yml
# glci local config (auto-created on first `glci` invocation)
.glciconfig.toml
# Local-only agent instructions (Claude Code reads this; not for distribution)
CLAUDE.local.md
AGENTS.local.md
.claude/
# Validate the skill against the agent-skills.io specification.
# Uses skills-ref from https://github.com/agentskills/agentskills
# Pinned to a specific SHA — bump AGENTSKILLS_SHA to pick up upstream changes.
# skills-ref is labeled "demonstration purposes only" by Anthropic and is not
# published to PyPI; cloning and installing from source is the supported path.
variables:
AGENTSKILLS_SHA: "2d3e01f590f68bee2cb76a3200823e93b2cc9eaa"
stages:
- validate
validate-skill:
stage: validate
image: python:3.12-slim
interruptible: true
retry:
max: 1
when:
- runner_system_failure
- stuck_or_timeout_failure
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
before_script:
- apt-get update -qq && apt-get install -y -qq --no-install-recommends git
- |
git init /tmp/agentskills
git -C /tmp/agentskills fetch --depth=1 \
https://github.com/agentskills/agentskills.git \
"$AGENTSKILLS_SHA"
git -C /tmp/agentskills checkout FETCH_HEAD
- pip install --quiet -e /tmp/agentskills/skills-ref
script:
- |
if ! skills-ref validate "$CI_PROJECT_DIR" 2>&1 | tee validation-report.txt; then
exit 1
fi
artifacts:
when: always
paths:
- validation-report.txt
expire_in: 30 days
# Lint every examples/*/.gitlab-ci.yml via glci lint.
# Proves the skill's generated outputs are syntactically valid GitLab CI.
lint-examples:
stage: validate
image: debian:stable-slim
interruptible: true
retry:
max: 1
when:
- runner_system_failure
- stuck_or_timeout_failure
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
before_script:
- apt-get update -qq && apt-get install -y -qq --no-install-recommends curl ca-certificates
- curl -fsSL https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/raw/main/install.sh | bash
script:
- |
failed=0
files=$(find examples -name '.gitlab-ci*.yml' -type f 2>/dev/null || true)
if [ -z "$files" ]; then
echo "no example .gitlab-ci*.yml files found; nothing to lint"
exit 0
fi
for f in $files; do
echo "linting $f"
if ! glci lint --quiet -f "$f"; then
echo "FAIL: $f"
failed=1
fi
done
exit $failed
# Enforce that examples/<dir>/ contains only .gitlab-ci*.yml and README.md.
# No vendored upstream source, no synthetic boilerplate, no nested subdirs.
# Keeps the skill install footprint small and the supply-chain surface zero.
verify-examples-shape:
stage: validate
image: alpine:3.20
interruptible: true
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- |
failed=0
for f in $(find examples -mindepth 2 -type f 2>/dev/null); do
base=$(basename "$f")
case "$base" in
.gitlab-ci.yml|.gitlab-ci.*.yml|README.md) ;;
*) echo "FAIL: unexpected file $f. Only .gitlab-ci*.yml and README.md are allowed under examples/<dir>/."; failed=1 ;;
esac
done
for d in $(find examples -mindepth 2 -type d 2>/dev/null); do
echo "FAIL: examples/ has nested subdirectory $d. Each stack lives in a single flat dir."
failed=1
done
exit $failed
# GitLab CI pipeline for the cors Node.js library.
# Stages: build (npm pack), test (lint + mocha/nyc), deploy (manual stub).
default:
image: node:lts-alpine
interruptible: true
# No committed lockfile in this project, so cache keys on package.json and
# we use `npm install` (npm ci requires a tracked package-lock.json).
cache:
key:
files: [package.json]
paths: [.npm/]
before_script:
- npm install --cache .npm --prefer-offline --no-audit --no-fund
stages:
- build
- test
- deploy
# Package the library as a publishable tarball.
build:
stage: build
script:
- npm pack
artifacts:
paths: ["*.tgz"]
expire_in: 1 week
# Static analysis with eslint.
lint:
stage: test
script: [npm run lint]
needs: []
# Mocha test suite with nyc coverage.
unit-test:
stage: test
script: [npm run test-ci]
needs: []
coverage: '/All files\s*\|\s*([\d.]+)/'
artifacts:
paths: [coverage/]
expire_in: 1 week
# Stub: replace with `npm publish` (gated on $CI_COMMIT_TAG) once NPM_TOKEN is set
# as a masked, protected CI/CD variable. See docs.gitlab.com/ci/variables/.
deploy:
stage: deploy
script:
- echo "Configure deploy. For npm publish, gate on \$CI_COMMIT_TAG and set NPM_TOKEN."
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
# Example: Node + Mocha (no committed lockfile)
**Source**: generated by the skill from a fresh clone of [`expressjs/cors`](https://github.com/expressjs/cors) on 2026-05-22, with no pre-existing `.gitlab-ci.yml`.
## Patterns this example demonstrates
- **No-lockfile cache variant**: `package-lock.json` is gitignored upstream, so the cache keys on `package.json` and `before_script` uses `npm install` (not `npm ci`, which requires a tracked lockfile).
- **`needs: []` on test-stage jobs**: `lint` and `unit-test` start as soon as the pipeline begins, in parallel with `build`. The DAG, not stage order, drives execution.
- **Manual `deploy` stub gated to `$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH`**: the publish step is documented as needing `NPM_TOKEN` set as a masked + protected CI/CD variable.
- **`coverage:` regex** on the unit-test job pulls the coverage percentage out of nyc's text reporter for the GitLab UI badge.
## YAML files
- `.gitlab-ci.yml`: Workflow 1 (Create initial pipeline) capture.
## Reproducing
```bash
git clone https://github.com/expressjs/cors /tmp/cors
cd /tmp/cors
rm -rf .gitlab-ci.yml .gitlab .github/workflows
```
Then in a fresh Claude Code (or other AI editor) session, prompt:
> Set up GitLab CI for this repo.
Compare the agent's output to the YAML in this directory. They should match in shape; small differences are expected (component versions, comments).
# GitLab CI for a Click-style Python project. Generated by the skill from a
# fresh clone of pallets/click on 2026-05-22, with no .gitlab-ci.yml as input.
#
# Patterns to notice (the skill applies these by default; they're what makes the
# YAML "idiomatic GitLab" rather than the lowest-common-denominator shape):
#
# - `.tox` hidden job with `extends:` reuse across 4 callers (lint, test,
# typing, docs). Beats copy-pasting `uv tool install tox --with tox-uv` four
# times.
# - Schedule-gated full matrix: `test` runs Python 3.13 on every push; the full
# 3.10-3.14 matrix lives on `test-matrix` and only fires when
# $CI_PIPELINE_SOURCE == "schedule". Keeps every-push pipelines fast, nightly
# schedules exercise the full grid.
# - `needs: []` on every test-stage job so they start as soon as the pipeline
# begins, in parallel with `build`. The DAG (not stage order) drives execution.
# - `workflow:rules:` blocks the duplicate branch + MR pipeline once an MR opens.
# - Lockfile-keyed cache (`files: [uv.lock]`) keeps cache hits real.
# - `deploy` is a stub gated to tags and default-branch, both manual. Honest
# about what it doesn't know yet; you wire the actual publish step.
default:
image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
interruptible: true
cache:
key:
files: [uv.lock]
paths:
- .cache/uv/
- .tox/
before_script:
- export UV_CACHE_DIR=.cache/uv
variables:
UV_LINK_MODE: copy
FORCE_COLOR: "1"
PY_COLORS: "1"
# Skip duplicate branch + MR pipelines once an MR is open.
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
when: never
- if: $CI_COMMIT_BRANCH
- if: $CI_COMMIT_TAG
stages:
- build
- test
- deploy
# Reusable base for tox jobs: installs tox + tox-uv once, then runs the env.
.tox:
before_script:
- export UV_CACHE_DIR=.cache/uv
- uv tool install tox --with tox-uv
# Build wheel and sdist with uv (flit backend driven via PEP 517).
build:
stage: build
script:
- uv build
artifacts:
paths: [dist/]
expire_in: 1 week
lint:
stage: test
extends: .tox
script:
- uv tool run --from tox tox -e style
needs: []
# Single Python version on every push. Scheduled pipelines exercise the full matrix (see test-matrix).
test:
stage: test
extends: .tox
script:
- uv tool run --from tox tox -e py3.13 -- --junitxml=report.xml
artifacts:
reports:
junit: report.xml
when: always
needs: []
# Fan out across supported Python versions. Runs on scheduled pipelines only.
test-matrix:
stage: test
extends: .tox
image: ghcr.io/astral-sh/uv:python$PY_VERSION-bookworm-slim
script:
- uv tool run --from tox tox -e py$PY_VERSION -- --junitxml=report.xml
artifacts:
reports:
junit: report.xml
when: always
needs: []
parallel:
matrix:
- PY_VERSION: ["3.10", "3.11", "3.12", "3.13", "3.14"]
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"
typing:
stage: test
extends: .tox
script:
- uv tool run --from tox tox -e typing
needs: []
docs:
stage: test
extends: .tox
script:
- uv tool run --from tox tox -e docs
artifacts:
paths: [docs/_build/dirhtml/]
expire_in: 1 week
needs: []
# Stub. Replace with twine/uv publish to PyPI gated on $CI_COMMIT_TAG when ready.
deploy:
stage: deploy
script:
- echo "Configure your deploy target. See https://docs.gitlab.com/ci/environments/"
needs: [build]
rules:
- if: $CI_COMMIT_TAG
when: manual
allow_failure: true
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
# Example: Python + uv + tox (with `.tox` extends and schedule-gated matrix)
**Source**: generated by the skill from a fresh clone of [`pallets/click`](https://github.com/pallets/click) on 2026-05-22, with no pre-existing `.gitlab-ci.yml`.
Where `python-uv-tox/` shows the basic Python+uv shape, this one shows what happens when a project has a more elaborate tox configuration (style, type checking, docs in addition to tests).
## Patterns this example demonstrates
- **Hidden `.tox` job with `extends:` reuse across 4 callers** (lint, test, typing, docs). Beats copy-pasting `uv tool install tox --with tox-uv` four times.
- **Schedule-gated full matrix**: `test` runs Python 3.13 on every push; the full 3.10-3.14 matrix lives on `test-matrix` and only fires when `$CI_PIPELINE_SOURCE == "schedule"`. Every-push pipelines stay fast; nightly schedules exercise the full grid.
- **`workflow:rules:`** blocks the duplicate branch + MR pipeline once an MR opens (the classic gotcha for new GitLab users).
- **`needs: []` on every test-stage job** so the DAG starts the test stage in parallel with build.
- **Deploy stub** gated to both `$CI_COMMIT_TAG` and `$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH`, both manual.
## YAML files
- `.gitlab-ci.yml`: Workflow 1 (Create initial pipeline) capture.
## Reproducing
```bash
git clone https://github.com/pallets/click /tmp/click
cd /tmp/click
rm -rf .gitlab-ci.yml .gitlab .github/workflows
```
Then in a fresh Claude Code (or other AI editor) session, prompt:
> Set up GitLab CI for this repo.
Compare the agent's output to the YAML in this directory. They should match in shape; small differences are expected (component versions, comments).
# Workflow 2 demo: two skill invocations applied in sequence over .gitlab-ci.before.yml.
#
# Invocation 1: "Please add Secret Detection from the GitLab Catalog."
# Added: include of components/secret-detection at version 2.3.0.
#
# Invocation 2: "Could you also please improve the testing approach in this ci setup?"
# Rewrote the test job: parallel matrix on Python 3.9-3.13, venv-based install,
# pytest-cov with cobertura coverage report and JUnit results.
#
# Compare against .gitlab-ci.before.yml to see what each Workflow 2 invocation added.
default:
image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
interruptible: true
cache:
key:
files: [uv.lock]
paths: [.cache/uv/]
before_script:
- export UV_CACHE_DIR=.cache/uv
include:
- component: gitlab.com/components/secret-detection/secret-detection@2.3.0
stages:
- build
- test
# Build sdist + wheel (includes the C speedups extension)
build:
stage: build
script:
- uv build
artifacts:
paths: [dist/]
expire_in: 1 week
# Install the wheel into a clean venv, run pytest with coverage on every supported Python
test:
stage: test
parallel:
matrix:
- PY: ["3.9", "3.10", "3.11", "3.12", "3.13"]
image: ghcr.io/astral-sh/uv:python${PY}-bookworm-slim
needs: []
script:
- uv venv
- source .venv/bin/activate
- uv pip install --no-deps .
- uv pip install pytest pytest-cov
- pytest --junitxml=report.xml --cov=markupsafe --cov-report=term --cov-report=xml:coverage.xml tests/
coverage: '/TOTAL.*?(\d+\.?\d*)%/'
artifacts:
reports:
junit: report.xml
coverage_report:
coverage_format: cobertura
path: coverage.xml
when: always
default:
image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
interruptible: true
cache:
key:
files: [uv.lock]
paths: [.cache/uv/]
before_script:
- export UV_CACHE_DIR=.cache/uv
stages:
- build
- test
# Build sdist + wheel (includes the C speedups extension)
build:
stage: build
script:
- uv build
artifacts:
paths: [dist/]
expire_in: 1 week
# Run pytest against the source tree
test:
stage: test
script:
- uv sync --group tests
- uv run pytest --junitxml=report.xml
artifacts:
reports:
junit: report.xml
when: always
needs: []
# Workflow 3 demo fixture: lint passes, but the pipeline fails at runtime.
#
# Intentional break: the image tag is misspelled (sllim instead of slim).
# - glci lint passes (lint does not validate image existence).
# - glci show passes (show does not pull images).
# - glci run --simulate fails at image pull.
# - glci run fails at image pull with the same error.
#
# Real GitLab logs would show:
# Error response from daemon: manifest for ghcr.io/astral-sh/uv:python3.13-bookworm-sllim not found
#
# The skill should diagnose this from the log alone, propose the one-character
# fix (sllim -> slim), verify with show, and offer to confirm with `glci run
# build --confirm-docker` if the user has Docker.
default:
image: ghcr.io/astral-sh/uv:python3.13-bookworm-sllim
interruptible: true
cache:
key:
files: [uv.lock]
paths: [.cache/uv/]
before_script:
- export UV_CACHE_DIR=.cache/uv
stages:
- build
- test
# Build sdist + wheel (includes the C speedups extension)
build:
stage: build
script:
- uv build
artifacts:
paths: [dist/]
expire_in: 1 week
# Run pytest against the source tree
test:
stage: test
script:
- uv sync --group tests
- uv run pytest --junitxml=report.xml
artifacts:
reports:
junit: report.xml
when: always
needs: []
# Workflow 4 demo: optimization of .gitlab-ci.after-layered.yml. One round, three changes.
#
# 1. Dropped Python 3.9 from the matrix.
# pyproject.toml declares requires-python = ">=3.10", so the 3.9 entry was
# either failing fast or building a stale resolution. One fewer job, no false
# signal.
# 2. Added cache:key:prefix: "py${PY}" so each matrix entry gets its own cache
# slot. Previous shape had 5 jobs racing to write the same lockfile-keyed
# cache; last-writer-wins meant cross-version contention and cold caches.
# 3. Moved `export UV_CACHE_DIR=.cache/uv` from before_script: into a top-level
# variables: block. variables: is visible to GitLab's cache: key resolver and
# cleans up before_script:; idiomatic GitLab pattern, no behavior change.
#
# Compare against .gitlab-ci.after-layered.yml to see the round 1 diff.
default:
image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
interruptible: true
cache:
key:
prefix: "py${PY}"
files: [uv.lock]
paths: [.cache/uv/]
variables:
UV_CACHE_DIR: .cache/uv
include:
- component: gitlab.com/components/secret-detection/secret-detection@2.3.0
stages:
- build
- test
# Build sdist + wheel (includes the C speedups extension)
build:
stage: build
script:
- uv build
artifacts:
paths: [dist/]
expire_in: 1 week
# Install the wheel into a clean venv, run pytest with coverage on every supported Python
test:
stage: test
parallel:
matrix:
- PY: ["3.10", "3.11", "3.12", "3.13"]
image: ghcr.io/astral-sh/uv:python${PY}-bookworm-slim
needs: []
script:
- uv venv
- source .venv/bin/activate
- uv pip install --no-deps .
- uv pip install pytest pytest-cov
- pytest --junitxml=report.xml --cov=markupsafe --cov-report=term --cov-report=xml:coverage.xml tests/
coverage: '/TOTAL.*?(\d+\.?\d*)%/'
artifacts:
reports:
junit: report.xml
coverage_report:
coverage_format: cobertura
path: coverage.xml
when: always
# MarkupSafe CI pipeline. Uses uv + tox-uv: tox installs the requested
# Python interpreter via uv, so a single base image covers the full matrix.
default:
image: ghcr.io/astral-sh/uv:python3.13-bookworm
interruptible: true
cache:
key:
files: [uv.lock]
paths:
- .cache/uv/
- .tox/
before_script:
- export UV_CACHE_DIR="$CI_PROJECT_DIR/.cache/uv"
# Run MR pipelines when an MR is open, branch pipelines otherwise. Prevents
# duplicate pipelines on push-to-branch-with-open-MR.
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
when: never
- if: $CI_COMMIT_BRANCH
- if: $CI_COMMIT_TAG
stages:
- build
- test
- deploy
# Shared base for tox jobs.
.tox:
stage: test
needs: []
script:
- uvx --with tox-uv tox -e $TOX_ENV
# pre-commit hooks (ruff, etc.)
style:
stage: build
needs: []
script:
- uvx --with tox-uv tox -e style
# Strict mypy check.
typing:
stage: build
needs: []
script:
- uvx --with tox-uv tox -e typing
# CPython matrix, including free-threaded builds.
test:cpython:
extends: .tox
parallel:
matrix:
- TOX_ENV:
- py3.9
- py3.10
- py3.11
- py3.12
- py3.13
- py3.13t
- py3.14
- py3.14t
# Free-threading stress test.
test:parallel:
extends: .tox
variables:
TOX_ENV: parallel
# PyPy compatibility.
test:pypy:
extends: .tox
variables:
TOX_ENV: pypy3.11
# Sphinx docs build with -W (warnings as errors).
docs:
stage: test
needs: []
script:
- uvx --with tox-uv tox -e docs
artifacts:
paths: [docs/_build/dirhtml]
expire_in: 1 week
# Build sdist + wheel. PyPI publishing not wired up; add a trusted-publisher
# or twine job when ready (see docs.gitlab.com/ci/secrets/ for OIDC options).
build:dist:
stage: deploy
needs: ["test:cpython", "test:pypy", "style", "typing"]
script:
- uv build
artifacts:
paths: [dist/]
expire_in: 1 month
rules:
- if: $CI_COMMIT_TAG
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
# Example: Python + uv + tox (full W1/W2/W3/W4 narrative)
**Source**: generated by the skill from a fresh clone of [`pallets/markupsafe`](https://github.com/pallets/markupsafe) on 2026-05-22, with no pre-existing `.gitlab-ci.yml`.
This is the most comprehensive example in the repo: five YAML files telling the complete story of how the skill behaves across all four of its workflows.
## Patterns this example demonstrates
- **`default:` block** for shared `image`, `interruptible`, `cache`, `before_script`.
- **Lockfile-keyed cache**: `cache:key:files: [uv.lock]` so cache invalidates only when dependencies change.
- **Build artifact** (sdist + wheel via `uv build`) flowing to downstream jobs.
- **CI/CD Catalog component include**: `gitlab.com/components/secret-detection/secret-detection@2.3.0`, pinned to a release tag.
- **Cross-version test matrix** with per-version cache slot via `cache:key:prefix: "py${PY}"` (optimized variant).
- **`variables:` block** for `UV_CACHE_DIR` so the cache resolver sees it (idiomatic placement; cleaner than `before_script:`).
## YAML files
- `.gitlab-ci.yml`: Workflow 1 capture. The skill's straightforward output for this stack.
- `.gitlab-ci.before.yml`: Workflow 2 starting state. Minimal pipeline ("just build + test, no matrix, no security").
- `.gitlab-ci.after-layered.yml`: Workflow 2 result. Two skill invocations stacked: add Secret Detection from the Catalog, then improve testing (parallel matrix, pytest-cov, JUnit and cobertura reports).
- `.gitlab-ci.broken.yml`: Workflow 3 starting state. Image tag typo (`sllim` instead of `slim`). Lint and show pass; only `glci run` catches it.
- `.gitlab-ci.optimized.yml`: Workflow 4 result. Round-1 optimizations applied to `.after-layered.yml`: drop Python 3.9 (vs `requires-python = ">=3.10"`), per-PY cache prefix, `UV_CACHE_DIR` moved to `variables:`.
## Reproducing
```bash
git clone https://github.com/pallets/markupsafe /tmp/markupsafe
cd /tmp/markupsafe
rm -rf .gitlab-ci.yml .gitlab .github/workflows
```
Then in a fresh Claude Code (or other AI editor) session, prompt:
> Set up GitLab CI for this repo.
For the W2/W3/W4 narratives, copy one of the other YAML files in as `.gitlab-ci.yml` first, then prompt accordingly:
- W2: `Add Secret Detection from the GitLab CI Catalog to this pipeline.`
- W3: paste the failing job log (the `sllim` image-pull error) and ask the skill to diagnose.
- W4: `Can you optimize this pipeline?`
Compare the agent's output to the YAML in this directory. They should match in shape; small differences are expected.
# `examples/` directory guide
Real `.gitlab-ci.yml` files generated by the [gitlab-ci-skill](../) against well-known OSS projects. Use them as a reference for what idiomatic GitLab CI/CD pipelines look like across stacks, or as a sanity check when authoring your own.
## How to read these examples
Each subdirectory is one stack. Each subdirectory contains:
- One or more `.gitlab-ci*.yml` files: the skill's actual generated output, captured from a fresh-session run.
- A `README.md`: provenance (which upstream project the YAML was generated from), the patterns the YAML demonstrates, and reproduction commands.
No upstream source code is redistributed by this repo. The YAML stands alone.
| Directory | Stack | Source |
|---|---|---|
| [`node-mocha/`](node-mocha/) | Node + Mocha + nyc, no committed lockfile | [`expressjs/cors`](https://github.com/expressjs/cors) |
| [`python-uv-tox/`](python-uv-tox/) | Python + uv + tox + parallel matrix; full W1/W2/W3/W4 narrative | [`pallets/markupsafe`](https://github.com/pallets/markupsafe) |
| [`python-click/`](python-click/) | Python + uv + tox-driven `.tox` extends + schedule-gated matrix | [`pallets/click`](https://github.com/pallets/click) |
More stacks (Go, Ruby, Docker, Rust) are planned per the engineering tracking issue. See "How to contribute" below.
## How to use them
Three ways:
1. **Read the YAML.** Each file is a working `.gitlab-ci.yml` you can drop into a project of the matching stack and adapt. The patterns the skill applies (default block, hidden-job + extends, lockfile cache, schedule-gated matrix, Catalog include) are idiomatic GitLab shapes; copying them by hand is fine.
2. **Reproduce it.** Each stack's `README.md` carries the reproduction commands: clone the named upstream into `/tmp/`, run the skill in a fresh AI editor session, compare the agent's output to the committed YAML. Differences are expected for component versions and comments; the shape should match.
3. **Validate locally.** From the repo root:
```bash
bash scripts/verify.sh -f examples/<stack>/.gitlab-ci.yml lint
bash scripts/verify.sh -f examples/<stack>/.gitlab-ci.yml show
```
`lint` and `show` work against the committed YAML alone, without cloning the upstream. The `lint-examples` CI gate runs the same lint check on every push.
## How to contribute a new example
Four steps:
1. **Pick a real OSS project** in a stack the skill should demonstrate. Smaller is better (faster lint, less ambiguity). The project should have no existing `.gitlab-ci.yml`, or you should reset to a no-CI state by cloning to `/tmp/` and removing the CI directories:
```bash
git clone <github-url> /tmp/<name>
cd /tmp/<name>
rm -rf .gitlab-ci.yml .gitlab .github/workflows .git
git init -q && git add . && git commit -q -m init
```
2. **Run the skill from a fresh AI editor session.** Prompt:
> Set up GitLab CI for this repo.
Capture the agent's output to `examples/<stack>/.gitlab-ci.yml`. Do not hand-tune the YAML; the value of the example is that it's actual skill output.
3. **Write `examples/<stack>/README.md`** following the pattern of the existing READMEs in this directory:
- The source link to the upstream project.
- 3 to 5 bullets naming the idiomatic patterns the YAML demonstrates.
- Reproduction commands.
4. **Push the MR.** CI runs three gates:
- `validate-skill`: the agentskills.io spec.
- `lint-examples`: `glci lint` against every `.gitlab-ci*.yml` under `examples/`.
- `verify-examples-shape`: only `.gitlab-ci*.yml` and `README.md` allowed under each example directory; no nested subdirs.
All three must pass.
If your example genuinely needs files beyond the YAML and the README (it almost certainly doesn't), open an issue first. We're deliberate about shipping the smallest disk footprint possible.
MIT License
Copyright (c) 2026-present GitLab Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# gitlab-ci-skill
An [Agent Skill](https://agentskills.io) that helps developers author, debug, and optimize GitLab CI/CD pipelines from any AI editor. No GitLab account or GitLab Duo required.
## Status
gitlab-ci-skill is an experimental GitLab project .v1 launched 2026-05-22. Public release tracking issue: [`gitlab-org/gitlab#600546`](https://gitlab.com/gitlab-org/gitlab/-/issues/600546). All four workflows (Create, Add, Debug, Optimize) plus the GitLab onboarding handoff are wired in.
## What it does
When invoked, the skill helps an AI agent (Claude Code, Cursor, opencode, VS Code, OpenCode, Codex):
1. Detect a repo's stack (language, package manager, test runner) and draft a working `.gitlab-ci.yml` shaped as `build`, `test`, `deploy`.
2. Validate the `.gitlab-ci.yml` offline via [`glci`](https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci) (preferred) or `glab ci lint` (fallback).
3. Run the pipeline locally via `glci run` for full-fidelity execution before push.
4. Add jobs to an existing pipeline while matching the project's existing patterns (base jobs, stage placement, rules style).
5. Debug a failing pipeline from either a GitLab pipeline URL or a `glci run` log.
6. Optimize an existing pipeline with caching, DAG via `needs:`, and `parallel:matrix`.
7. Walk a brand-new GitLab user through creating a project, pushing, and finding the pipeline in the GitLab UI.
## Sample output
Given a fresh clone of a Python project (`pyproject.toml`, `uv.lock`, tests) with no `.gitlab-ci.yml`, the skill detects the stack, drafts the pipeline, and renders the graph locally via [`glci`](https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci) before suggesting commit:
```
Pipeline: 5 jobs across 2 stages
○ pending ● running ✓ passed ✗ failed ▶ manual ⊘ skipped ⚠ allow_failure
build test
───────── ─────────
○ build ○ docs
○ lint
○ test
○ typing
```
The graph is generated entirely offline (no GitLab account, no push). See [`examples/python-click/.gitlab-ci.yml`](examples/python-click/.gitlab-ci.yml) for the full file. Idiomatic patterns the skill applies by default: `default:` block for shared fields, hidden `.tox` job with `extends:` reuse across 4 callers, lockfile-keyed cache, `needs: []` so test-stage jobs fan out from the start, schedule-gated full matrix.
For an existing pipeline, the skill also adds jobs (`include: component:` from the GitLab CI Catalog, pinned to release tags), debugs failures from pasted job logs or `glci` reproductions, and proposes optimizations as before/after diffs. See [`examples/python-uv-tox/.gitlab-ci.optimized.yml`](examples/python-uv-tox/.gitlab-ci.optimized.yml) for a Workflow 4 capture with the optimization rationale in the header.
## Scope
**Currently covers:**
- Common single-stack repos: Node, Python, Go, Ruby, Rust, Dockerfile build/push
- Pipeline shape: `build`, `test`, `deploy` (matches GitLab's canonical quick-start example)
- Idiomatic GitLab patterns: hidden jobs + `extends:`, `default:` for shared fields, `workflow:rules:` for pipeline gating
- CI/CD Catalog component recommendations (curated snapshot of GitLab-maintained components)
- Local validation via `glci lint` and local execution via `glci run`
**Not yet covered:**
- Multi-stack monorepos
- Server-side concerns (protected branches, approvals, merge trains, policy)
- Reusable pipeline composition beyond `include:` + `extends:`
## Installation
This skill follows the [Agent Skills open standard](https://agentskills.io/specification). Install by copying the `gitlab-ci-skill/` directory into your skill discovery path:
| Tool | Path |
|---|---|
| Claude Code | `~/.claude/skills/gitlab-ci-skill/` |
| opencode | `~/.config/opencode/skills/gitlab-ci-skill/` (also picks up the Claude path) |
| Project-local | `.claude/skills/gitlab-ci-skill/` or `.opencode/skills/gitlab-ci-skill/` |
| Cross-tool (open standard) | `~/.agents/skills/gitlab-ci-skill/`, picked up by Claude Code, opencode, Cursor, GitLab Duo CLI, and any tool implementing the Agent Skills specification |
| GitLab Duo CLI (Linux/macOS) | `~/.gitlab/duo/skills/gitlab-ci-skill/` |
| GitLab Duo CLI (Windows) | `%APPDATA%\GitLab\duo\skills\gitlab-ci-skill\` |
For GitLab Duo workspace-level skills, place at `skills/gitlab-ci-skill/SKILL.md` inside a project repository.
## Project structure
```
gitlab-ci-skill/
├── SKILL.md Entry point: workflows, principles, output format
├── references/ Detailed reference docs loaded as needed
│ ├── mental-model.md GitLab's 4-step CI/CD mental model
│ ├── syntax.md Curated keyword set the skill produces
│ ├── recipes.md Per-stack starter pipelines (build/test/deploy)
│ ├── images.md Picking the right image per stack
│ ├── caching.md Cache keys, paths, scopes
│ ├── catalog.md CI/CD Catalog components, version pinning
│ ├── verification.md glci verification ladder (lint/show/simulate/run)
│ ├── debugging.md Workflow 3 flow + failure-shape catalog
│ ├── optimize.md Workflow 4 flow + optimization playbook
│ └── onboarding.md Creating a GitLab project, first push
├── scripts/
│ ├── verify.sh Tier-aware verification (auto/lint/show/simulate/run)
│ └── catalog-search.sh Live Catalog GraphQL query
└── examples/ Reference repos used by CI to gate end-to-end
```
## Companion tools
- [`glci`](https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci): the workhorse. Lints, renders the pipeline graph (`glci show`), simulates execution, and runs `.gitlab-ci.yml` locally against the production `gitlab-runner` image. No GitLab account required.
- [`glab`](https://gitlab.com/gitlab-org/cli): the official GitLab CLI. Used as a `glab ci lint` fallback when `glci` is not installed.
- [Sister skill: `github-actions-to-gitlab-ci`](https://gitlab.com/gitlab-org/ci-cd/github-actions-to-gitlab-ci): translates GitHub Actions workflows to GitLab CI/CD pipelines. Paired with this skill for users coming from GitHub.
## Related work
This skill is the portable counterpart to GitLab's [CI Expert Agent](https://docs.gitlab.com/user/duo_agent_platform/agents/foundational_agents/ci_expert_agent/), which runs inside GitLab Duo (see its [AI Catalog entry](https://gitlab.com/explore/ai-catalog/agents/1004583/)). The CI Expert Agent applies the same authoring, debugging, and optimization patterns in-product. This skill ports those patterns out as an Agent Skill so any AI editor can load them without a Duo subscription or a GitLab account.
## Contributing
Issues and merge requests welcome.
## License
MIT. See `LICENSE`.
# Caching reference
Load this when configuring `cache:` in a job or in `default:`. Cache reduces pipeline time by avoiding re-fetch and re-build of dependencies between pipelines.
## Contents
- What cache is, and what it is not
- Cache key patterns (lock-file hash, per-branch, per-job, fallback keys)
- Cache paths (per stack)
- Cache policy (pull-push, pull, push)
- Multiple caches per job
- When cache is wrong
- Cache and `default:`
- Verifying cache hits
## What cache is, and what it is not
Cache is **for dependencies**: `node_modules/`, `.cargo/registry/`, `vendor/`, `.cache/pip/`. It is shared between pipelines on the same key.
Artifacts are **for pipeline outputs**: build products, test reports, generated files. They flow between jobs in the same pipeline.
Do not put pipeline outputs in cache. Do not put dependencies in artifacts.
## Cache key patterns
Use the right key for the right scope. Wrong key means stale cache (slow) or thrashing cache (no benefit).
### Lock-file hash (recommended for most cases)
```yaml
cache:
key:
files:
- package-lock.json
paths:
- node_modules/
```
The key changes only when the lock file changes. Most jobs share the same cache across pipelines.
Equivalents per stack:
| Stack | Lock file |
|---|---|
| Node.js | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
| Python | `poetry.lock`, `Pipfile.lock`, `requirements.txt` (acceptable as a coarse key) |
| Go | `go.sum` |
| Ruby | `Gemfile.lock` |
| Rust | `Cargo.lock` |
### Per-branch
```yaml
cache:
key: $CI_COMMIT_REF_SLUG
paths: [node_modules/]
```
Each branch gets its own cache. Good when branches diverge in dependencies. Slow on first run of a new branch.
### Per-job
```yaml
cache:
key: $CI_JOB_NAME-$CI_COMMIT_REF_SLUG
paths: [.cache/]
```
When different jobs in the same branch need disjoint cache. Rarely the right answer; prefer one cache shared via `default:cache:`.
### Fallback keys
```yaml
cache:
key:
files: [package-lock.json]
fallback_keys:
- $CI_DEFAULT_BRANCH
paths: [node_modules/]
```
If the lock-file key has no cache, fall back to the default branch's cache. Reduces cold-start time on new branches.
## Cache paths
List directories explicitly. Globs work but are slower to resolve.
| Stack | Cache paths |
|---|---|
| Node.js (npm) | `.npm/` (the registry cache; pair with `npm ci --cache .npm --prefer-offline`) |
| Node.js (yarn) | `.yarn/cache/` |
| Node.js (pnpm) | `.pnpm-store/` |
| Python (pip) | `.cache/pip/` |
| Python (poetry) | `.cache/pypoetry/` |
| Go | `.go/pkg/mod/` (with `GOPATH=$CI_PROJECT_DIR/.go`) |
| Ruby (bundler) | `vendor/ruby/` (with `bundle config set --local deployment true`) |
| Rust (cargo) | `.cargo/registry/cache/`, `target/` (with `CARGO_HOME=$CI_PROJECT_DIR/.cargo`) |
For environments where the home directory is not under `$CI_PROJECT_DIR`, set the tool-specific home variable so the cache lives inside the project directory (otherwise it is outside the cached path and lost between jobs).
## Cache policy
By default, jobs both pull and push the cache. Override when you want different behavior:
- `policy: pull-push` (default): pull at start, push at end.
- `policy: pull`: read-only. Use when the job consumes the cache but does not change it (test jobs that do not install dependencies).
- `policy: push`: write-only. Use when the job populates the cache for downstream jobs (a dedicated "warm cache" job).
```yaml
.cache-base:
cache:
key:
files: [package-lock.json]
paths: [node_modules/]
warm-cache:
extends: .cache-base
stage: .pre
cache:
policy: pull-push
script:
- npm ci
test:
extends: .cache-base
cache:
policy: pull
script:
- npm test
```
## Multiple caches per job
A job can declare a list of caches:
```yaml
test:
cache:
- key:
files: [package-lock.json]
paths: [.npm/]
- key: $CI_COMMIT_REF_SLUG-build
paths: [.cache/build-output/]
```
Use this when a job needs caches with different keys (e.g., one keyed on a lock file, another keyed per branch). Rare. Prefer one cache shared via `default:cache:` unless there is a concrete reason.
## When cache is wrong
- Build outputs that change every commit: use artifacts.
- Anything secret: never put credentials in cache.
- Large directories that change every run: cache costs upload + download every job; if the directory changes more than it stays the same, skip cache and accept the cold start.
## Cache and `default:`
If most jobs share one cache configuration, define it once in `default:`:
```yaml
default:
cache:
key:
files: [package-lock.json]
paths: [node_modules/, .npm/]
```
A job can still override `cache:` to declare its own configuration or `cache: []` to disable.
## Verifying cache hits
The job log shows whether cache was extracted: look for `Restoring cache` and `Successfully extracted cache`. If you see `Created cache <key>` followed by `Cache miss` on the next pipeline run, the key is changing unnecessarily; check that you are not hashing files that change every commit.
# CI/CD Catalog reference
Load this when generating a job for a standard task: security scanning, code quality, infrastructure deployment, language-specific build / test pipelines, build provenance, or markdown lint. The skill prefers a GitLab-maintained component over a custom implementation for these tasks.
For project-specific logic (this project's build, test, deploy), write a custom job per `references/recipes.md`.
## Contents
- When to use a component vs writing a custom job
- How GitLab verifies components
- Pinning rules
- Curated components by use case
- Security scanning
- Code quality and linting
- Infrastructure and deployment
- Language pipelines
- Build, packaging, provenance
- Workflow automation and reporting
- Component development tooling
- Minimal include syntax
- Live lookup (`scripts/catalog-search.sh`)
- Components excluded from the curated list
## When to use a component vs writing a custom job
| Situation | Action |
|---|---|
| Standard cross-project task (SAST, scanning, IaC deploy, common language pipeline) | Use a component. Saves the user job-writing and earns free upgrades. |
| Project-specific build, test, or deploy logic | Write a custom job using `references/recipes.md`. |
| Standard task but no fitting component exists | Write a custom job; flag for the user as a gap worth revisiting. |
## How GitLab verifies components
The Catalog assigns each component a `verificationLevel`:
- **GITLAB_MAINTAINED** (tanuki badge): "GitLab.com components that are created and maintained by GitLab" ([docs](https://docs.gitlab.com/ci/components/#verification-badges)). Prefer these.
- **GITLAB_PARTNER_MAINTAINED**: "GitLab.com components that are independently created and maintained by a GitLab-verified partner" ([docs](https://docs.gitlab.com/ci/components/#verification-badges)). Acceptable when no GitLab-maintained component fits. GitLab notes that partner components are provided as-is without warranty.
- **VERIFIED_CREATOR_MAINTAINED**: "Components created and maintained by a user verified by an administrator" ([docs](https://docs.gitlab.com/ci/components/#verification-badges)). Applies on self-managed and dedicated instances; the administrator designates the verified creator.
- **UNVERIFIED**: everything else. Use only with caution and after auditing the component.
The skill confirms a component's verification level via the live GraphQL lookup (`scripts/catalog-search.sh`), not by inspecting URLs. When recommending, state the verification level so the user knows what they are getting.
## Pinning rules
Always pin to a release tag. Never `@~latest`, `@main`, or `@master`. The `include: component:` syntax requires an `@<version>` suffix:
- **Semantic release tag** (recommended): `@1.0.0`, `@2.3.4`. Pinned, auditable, predictable.
- **Major.minor**: `@1.0`. Resolves to the latest patch on that line. Acceptable when the component follows semver and the user accepts patch upgrades.
- **Commit SHA (full)**: `@abc123...`. Pinned tightest. Use when the component has no releases yet and the user accepts the maintenance burden.
The skill fetches the current latest version via the live lookup at recommendation time. This file does not pin versions; pinning is decided per-recommendation against fresh data.
## Curated components by use case
When the user asks for one of the tasks below, recommend the named component from the GITLAB_MAINTAINED set. Look up the current latest version via the live lookup before generating the `include:` block. The descriptions below are static metadata, not freshness signals.
### Security scanning
| Component | Purpose |
|---|---|
| `components/sast` | Static Application Security Testing across many languages. |
| `components/dependency-scanning` | Dependency vulnerability scanning, SBOM, software composition analysis. Marked BETA upstream. |
| `components/secret-detection` | Detect committed secrets in the repo. |
| `components/container-scanning` | Scan Docker images for known CVEs. |
| `components/vulnerability-prioritizer` | Prioritize vulnerabilities surfaced by `dependency-scanning` and `container-scanning`. **EXPERIMENTAL** upstream; expect API and output changes. Recommend only when the user explicitly asks for prioritization, not as a default. |
### Code quality and linting
| Component | Purpose |
|---|---|
| `components/code-quality-oss/codequality-os-scanners-integration` | CI templates integrating open-source code quality scanners with GitLab. Successor to `components/code-quality`. |
| `components/code-quality` | CodeClimate-based code quality scanning. **DEPRECATED**: upstream points users at `components/code-quality-oss/codequality-os-scanners-integration`. Recommend only for users already on it who want a migration path. |
| `components/markdownlint` | Markdown lint. |
### Infrastructure and deployment
| Component | Purpose |
|---|---|
| `components/opentofu` | OpenTofu / Terraform plan and apply pipeline. |
| `components/fluxcd` | Build OCI artifacts for use with FluxCD GitOps deployments. |
### Language pipelines
| Component | Purpose |
|---|---|
| `components/go` | Go format, build, test. |
| `components/ruby` | Build, lint, test, deploy Ruby projects. |
| `components/rust` | Rust build, test, doc, run. |
### Build, packaging, provenance
| Component | Purpose |
|---|---|
| `components/slsa` | SLSA-compliant build provenance. |
| `components/package` | Container operations: Cosign signing, ECR migration. Recommend only when the user explicitly asks for container signing or ECR. |
### Workflow automation and reporting
These run from `.gitlab-ci.yml` but operate on the GitLab project itself (issues, MRs, dashboards), not the codebase's build / test / deploy.
| Component | Purpose |
|---|---|
| `components/gitlab-triage` | Run issue, merge request, and epic automations on a schedule (auto-label, auto-close stale, etc.). Useful as a scheduled pipeline. |
| `components/vsd-reports-generator` | Generate scheduled Value Stream Dashboard reports. |
### Component development tooling
| Component | Purpose |
|---|---|
| `components/toolkit` | Helpers for developing your own GitLab CI/CD components. Use only when the user is authoring a CI component, not when they are using one. |
## Minimal include syntax
Every component follows the same shape. The `@<version>` is mandatory:
```yaml
include:
- component: gitlab.com/<fullPath>/<template>@<version>
inputs:
key: value
```
Concrete example with SAST:
```yaml
include:
- component: gitlab.com/components/sast/sast@3.4.0
```
When the component exposes a single template, the convention is `<name>/<name>`. When multiple templates exist (e.g. `gitlab.com/components/opentofu/full-pipeline` vs `gitlab.com/components/opentofu/validate`), reference the specific one. Check the component's `templates/` directory or the README.
Stack the includes when more than one applies:
```yaml
include:
- component: gitlab.com/components/sast/sast@<version>
- component: gitlab.com/components/secret-detection/secret-detection@<version>
- component: gitlab.com/components/dependency-scanning/main@<version>
```
## Live lookup (`scripts/catalog-search.sh`)
The Catalog is queryable via GraphQL. The skill bundles a bash script that wraps the query:
```bash
scripts/catalog-search.sh [VERIFICATION] [SORT] [LIMIT] [SEARCH]
```
It returns raw GraphQL JSON. Parse it with `jq` or any other JSON tool to extract the fields you need: `name`, `fullPath`, `description`, `topics`, `last30DayUsageCount`, `starCount`, `archived`, and the latest release tag under `versions.nodes[0].name`.
The script accepts all four `verificationLevel` values: `GITLAB_MAINTAINED` (default), `GITLAB_PARTNER_MAINTAINED`, `VERIFIED_CREATOR_MAINTAINED`, `UNVERIFIED`. Useful sort orders: `USAGE_COUNT_DESC` (default), `LATEST_RELEASED_AT_DESC`, `STAR_COUNT_DESC`, `NAME_ASC`.
When to invoke:
- Before recommending any component, to fetch the current latest version for `@<version>` pinning.
- To check whether a candidate component is GITLAB_MAINTAINED (verify the badge, do not assume from the URL).
- When a user task does not match the curated tables above. Search by keyword: `scripts/catalog-search.sh GITLAB_MAINTAINED USAGE_COUNT_DESC 50 <keyword>`.
- To enumerate partner-maintained or verified-creator components for tasks the GitLab-maintained set does not cover.
See the script's docstring for the full flag reference.
## Components excluded from the curated list
GITLAB_MAINTAINED components not in the tables above, with why:
- **`components/ai-catalog`**: tooling for syncing AI catalog agents from YAML definitions. Internal-facing utility, not a CI pipeline step for typical users.
- **`components/android-dependency-scanning`**: ARCHIVED upstream. Do not recommend.
## When no GITLAB_MAINTAINED component fits
Some common tasks have no GITLAB_MAINTAINED component today: DAST scanning, AWS deployment, Auto DevOps. For these, recommend GitLab's built-in CI templates instead: `DAST.gitlab-ci.yml`, `AWS/Deploy-ECS.gitlab-ci.yml`, `Auto-DevOps.gitlab-ci.yml`. See <https://docs.gitlab.com/ci/examples/>.
For tasks not covered by either the curated list or a built-in template, fall back to a custom job per `references/recipes.md`, or search broader verification levels via `scripts/catalog-search.sh GITLAB_PARTNER_MAINTAINED` and `scripts/catalog-search.sh VERIFIED_CREATOR_MAINTAINED`.
# Debugging reference
Workflow 3 flow plus the failure-shape catalog. Load when the user shares a failing pipeline (GitLab URL, pasted job log, or local `glci log` output).
## Workflow 3 flow
### 3.1 Identify the failure source
Ask the user (or detect from the input) which source they bring:
- **GitLab pipeline URL** (e.g., `gitlab.com/<group>/<project>/-/pipelines/<id>` or `.../-/jobs/<id>`): WebFetch the public log. If the project is private and you cannot fetch, ask the user to paste the failing-job log section.
- **Pasted log** (GitLab job log or local `glci log` output): read directly from the user's message.
- **Local `glci run`**: ask the user to run `glci log <pipeline-id> <job-name>` and paste the result, or to share their latest `glci history show` entry.
If the user is staring at a GitLab pipeline log and has not yet installed glci, mention once per conversation:
> "If you install glci, we can reproduce this failure on your machine in 30 seconds instead of waiting for the next pipeline."
Do not repeat this in subsequent failures.
### 3.2 Classify the failure
Use the failure catalog (below) to identify which tier would have caught this failure. Three buckets:
- **Configuration error** (lint or show would have caught it): bad include path, missing `needs:` reference, malformed `rules:`, undefined variable used in interpolation. Often the user pushed before verifying.
- **Environment error** (only run catches): image pull failure, missing binary in the image, service container startup failure, DinD socket missing, cache key mismatch, missing `GITLAB_TOKEN` for a private component.
- **Runtime error** (only run catches): script exits non-zero, test fails, build fails, deploy command fails.
State which bucket the failure is in. If the YAML verifies clean through show but the job fails at runtime, do not patch the YAML; debug the script.
### 3.3 Propose the minimal fix
The fix should change as few lines as possible. Do not refactor the surrounding YAML. If the cause is a script error inside a job, fix the script, not the structure.
### 3.4 Show the fixed pipeline
Run `scripts/verify.sh show -f <file>` against the fixed YAML and **paste the output verbatim as a fenced code block in your response message text** (not the Bash tool output, which auto-collapses). The user sees the corrected graph; if you only changed a script, the graph is unchanged but the confirmation is still useful.
If show fails after your fix, the proposed change is wrong. Re-diagnose, do not present a broken fix.
### 3.5 Confirm the fix locally (when possible)
If the user has glci and Docker, offer:
> "I can run just the failing job locally to confirm the fix: `scripts/verify.sh run <job> --reuse-artifacts --confirm-docker`. This pulls the job's image and executes the script. Want me to?"
`--reuse-artifacts` skips re-running upstream deps. On a clean local pass, the same failure is unlikely on GitLab.
If the user does not have glci or Docker, summarize what they should look for when they push: which job, which line of the log, which artifact. Then point them at `glci doctor` for an environment health check on their machine.
### 3.6 Ask for commit approval
Show `git diff` of the fix and wait for explicit approval before staging or pushing. Per principle 5.
## Reading the failure source
Three sources, three reading strategies:
- **GitLab pipeline URL** (`gitlab.com/<g>/<p>/-/pipelines/<id>` or `.../jobs/<id>`): WebFetch the public log. If the project is private and you cannot fetch, ask the user to paste the failing-job log section. Real GitLab logs include timestamps and color codes; strip them mentally.
- **Pasted log**: usually the user copies the last 50 to 200 lines. Look for the script step that exited non-zero, then look backward for the cause.
- **Local `glci log <pipeline-id> <job-name>`**: cleaner than GitLab logs because no color codes and no UI chrome. Use this output preferentially when the user is iterating locally.
In all three sources, the structure is the same:
1. Image pull and runner setup.
2. `before_script` (if any).
3. `script` (the job's main steps).
4. `after_script` (if any).
5. Artifact upload and cleanup.
A failure in step 1 is an environment problem; in steps 2 to 4 is a script or config problem; in step 5 is usually an artifact path problem.
## Failure catalog
Each row: signature (what the log shows), classification (config / environment / runtime), tier that would have caught it, fix.
### Configuration errors (lint or show would have caught)
| Signature | Class | Catches at | Fix |
|---|---|---|---|
| `Unable to parse YAML at line N` | Config | lint | Re-indent or fix the YAML at the line. Use a YAML linter to spot the issue. |
| `Job 'X' depends on 'Y' which does not exist` | Config | lint | Either add the missing job `Y` or remove the `needs:` entry pointing at it. |
| `Stage 'X' is not defined` | Config | lint | Add the stage to the `stages:` array, or change the job's `stage:` to one that exists. |
| `Circular dependency detected` | Config | lint | Break the cycle in `needs:`. Often happens when refactoring stage order. |
| `Invalid timeout 'X'` | Config | lint | Use GitLab's duration format (`30m`, `1h`, `2h 30m`). Bare seconds are not supported. |
| `Could not find file 'X' in 'Y'` (for `include: local:`) | Config | lint | Fix the path. Includes are resolved relative to the repo root, not the including file. |
| `Component 'X' not found` | Config | lint | Check the component path and version. Use `scripts/catalog-search.sh` to find the correct path. |
| Job exists but never appears in pipeline | Config | show | Inspect `rules:` and `workflow:rules:`. Use `verify.sh show --context X` to evaluate rules in the context that should trigger it. |
| `parallel:matrix` produced 0 jobs | Config | show | The matrix expansion produced an empty set. Check `parallel:matrix:` for empty value lists. |
| `workflow:rules:` blocks the pipeline (no jobs run) | Config | show | An `if:` clause in `workflow:rules:` evaluated false. Add a condition that matches the user's intended trigger. |
### Environment errors (simulate or run catches)
| Signature | Class | Catches at | Fix |
|---|---|---|---|
| `Error response from daemon: manifest for X not found` | Environment | run | Image tag does not exist. Fix the tag or use a tag that's published. Pin to a digest (`@sha256:...`) for reproducibility. |
| `Error response from daemon: pull access denied for X` | Environment | run | Private image requires authentication. Either use a public image, or add `image:pull_policy:` with appropriate credentials via CI/CD Variables. |
| `error: failed to start service X` | Environment | run | Service container failed (image pull, command, port conflict). Check the service's logs in the same job. |
| `docker: Cannot connect to the Docker daemon` (in a DinD job) | Environment | run | The DinD service did not start, or `tcp://docker:2375` is not reachable from the job container. Add the `docker:dind` service and set `DOCKER_HOST=tcp://docker:2375` and `DOCKER_TLS_CERTDIR=""`. |
| `unable to authenticate to component` (from glci, no `GITLAB_TOKEN`) | Environment | simulate | The YAML uses `include: component:` and `GITLAB_TOKEN` is not set. Set `GITLAB_TOKEN` in the environment (any GitLab.com account works for public components). |
| `glci: skipping component include ... no GitLab token configured` (from glci show) | Configuration | n/a (expected) | Not a failure. glci cannot resolve Catalog components locally without `GITLAB_TOKEN`; it skips the include and exits 0. The structural pipeline is verified. To resolve the component locally, set `GITLAB_TOKEN` to a real PAT (see SKILL.md Secret handling). Otherwise, the component resolves on push to GitLab. |
| `HTTP 401` on `gitlab.com/api/v4/projects/components%2F...` during local Catalog resolution | Environment | n/a (expected without auth) | The token in `GITLAB_TOKEN` is not authenticating. Most common cause: the agent or user copied an encrypted-at-rest value from `~/.config/glab-cli/config.yml`. That value is ciphertext, not a bearer token. Fix: create a real PAT at <https://gitlab.com/-/user_settings/personal_access_tokens>, `export GITLAB_TOKEN=<pat>`, re-run. Or accept the skip warning and verify on push. Do not extract tokens from local config files. |
| `panic: runtime error: slice bounds out of range [:8] with length 4` (system failure in "Preparing environment") | Environment | run | The repo has no commits yet. glci falls back to `Ref = "main"` and gitlab-runner panics slicing the 4-char ref to 8. Confirm with `git rev-parse HEAD` (exits non-zero if no commits). Fix: `git add -A && git commit -m "Initial commit"`. `verify.sh` preflights for this and exits 2 with the same diagnosis before reaching gitlab-runner. lint and show are unaffected. |
| Cache cold every run | Environment | run | The cache key is too dynamic (changes every push) or paths don't match. Use `cache:key:files: [<lockfile>]` and check `cache:paths:` against where the package manager actually writes. |
| Job queues indefinitely on real GitLab | Environment | not-catchable-locally | The job's `tags:` do not match any runner. Either remove the `tags:` or register a runner with the matching tag. glci does not enforce tags. |
### Runtime errors (only run catches)
| Signature | Class | Catches at | Fix |
|---|---|---|---|
| `script exited with code N` (N ≠ 0) | Runtime | run | A command in the `script:` block failed. Look at the line above for which command. Apply the same fix you would for that command on your laptop. |
| `command not found: X` | Runtime | run | The image does not include the binary. Use a different image, or `apt-get install` / `apk add` in `before_script`. |
| `$VAR: parameter not set` (bash strict mode) or `$VAR` printed empty | Runtime | simulate | A variable referenced in the script was never set. Check CI/CD Variables, `variables:` block, or whether `--env` was passed when running locally. |
| Test failures (`X failed, Y passed`) | Runtime | run | Real test failure. The pipeline did its job. Investigate the test, not the CI config. |
| Out-of-memory (job killed, no clear log) | Runtime | run | Job exceeded the runner's memory limit. On shared runners this is hard to fix; consider reducing parallel test workers or moving to a self-hosted runner. |
| Network timeout (e.g., `npm install` hangs) | Runtime | run | Often transient. Add a `retry:` block to the job. If persistent, check the runner's outbound network. |
| Artifact upload too large | Runtime | run | GitLab.com has a default 1 GiB artifact limit. Narrow `artifacts:paths:` to what downstream jobs actually need. |
## Looked-like-X-but-was-Y confusions
These trip people up. State plainly which one it actually is.
- **"It worked locally with `glci run`, but failed on GitLab."** Usually a tag mismatch, a missing CI/CD Variable, or a server-only variable the job depends on. Compare the GitLab job log's environment dump against glci's. Tell the user: glci does not enforce tags or know about server-only variables (`CI_RUNNER_ID`, `CI_MERGE_REQUEST_ASSIGNEES`, etc.).
- **"Lint passes but the pipeline doesn't run."** `workflow:rules:` blocked it. Run `verify.sh show --context X` where X is the trigger the user expected.
- **"The job runs but `$MY_VAR` is empty."** Variable not in scope. Check protected/masked flag on the CI/CD Variable (protected variables only expose on protected branches), check `variables:` precedence (job > .glci.env > YAML > project > group; per glci's documented order).
- **"The pipeline passes simulate but fails run."** Always a runtime or environment problem (image, services, scripts, cache). simulate's job is to validate structure and artifact flow; it does not exercise scripts.
- **"`needs:` worked before, broke after a refactor."** A stage moved, or a job got renamed. `verify.sh show` reveals the new DAG; compare to the old one (if you snapshotted via `--json`).
## Classifying failures from `verify.sh run`
When a `verify.sh run` (or `verify.sh run --simulate`) finishes with one or more failed jobs, classify each failure before recommending next steps. Three categories cover the common cases. Apply the rules in order; the first match wins.
| Signal | Tag | What it means | Next move |
|---|---|---|---|
| Log contains `ERROR: Job exceeded the timeout limit of Xs` | `[local-timeout]` | The job hit glci's runner-side per-job timeout (default 1 hour). Could be a legitimately long job, or a faster-on-cloud job slowed by local resource contention. | Rerun the job in isolation: `scripts/verify.sh run <job> --reuse-artifacts --confirm-docker`. If it still hits the wall solo, raise the limit: `glci run <job> --timeout 2h`. If the job is legitimately long-running, add a YAML `timeout:` keyword so GitLab.com enforces the same higher value. |
| Exit code 137 or -9 (or "Killed" in the log without a clear cause) | `[oom]` | The job container was killed by the kernel for exceeding memory. Almost always local resource pressure under concurrent matrix execution. | Rerun the job in isolation with `--reuse-artifacts`. If it passes solo, the issue is local concurrency, not the code. Reduce concurrent jobs (`glci run -j 2`) or close other apps. Hosted runners have dedicated memory per job and won't hit this. |
| Anything else (script exit non-zero, test assertion failure, build error) | `[real]` | A genuine project failure. The script needs fixing. | Switch to Workflow 3 (Debug). Read the log, find the failing assertion or command, propose a code fix. |
**The summarization rule**: after a failed `verify.sh run`, the model's response must include a per-job classification line. Example:
```
✗ test [3.11]: [local-timeout] log: "Job exceeded the timeout limit of 3600s"; rerun solo with --reuse-artifacts
✗ test [3.12]: [local-timeout] same; consider raising with --timeout 2h
✗ docs: [oom] exit 137; rerun solo with `verify.sh run docs --reuse-artifacts --confirm-docker`
✗ style: [real] ruff exit 1; lint errors in src/foo.py:42
```
Without this classification, the user cannot distinguish "your matrix is too heavy for my laptop" from "your code is broken". With it, they can triage at a glance: `[local-timeout]` and `[oom]` usually mean "local environment, not the code"; `[real]` means "actually fix the code".
## Fix application cycle
For every fix proposed:
1. Apply the smallest change that addresses the diagnosed failure.
2. `scripts/verify.sh show` to confirm structure still validates.
3. If the failure was runtime (script error), `scripts/verify.sh run <job> --confirm-docker` (with `--reuse-artifacts` if upstream artifacts exist) to confirm the fix. If the failure was config (lint or show would have caught), the verify.sh result is sufficient.
4. Show `git diff` to the user and wait for approval before staging or pushing.
Do not propose a fix for a runtime error by modifying the YAML's structure. That's almost always the wrong layer.
## Local-only diagnosis when the user has no glci
If the user shares a failing pipeline URL or pasted log but cannot run glci locally:
- Diagnose from the log alone using the catalog above.
- Recommend a fix and run `scripts/verify.sh lint` (which can fall back to `glab ci lint`) to confirm the proposed YAML is syntactically valid.
- Tell the user explicitly: "I verified the fix lints clean. To confirm it actually works, you'll need to push and watch the pipeline, or install glci locally and re-run the job."
This is the honest framing: lint alone is necessary but not sufficient for runtime fixes.
# Picking the right image
Load this when generating or reviewing the `image:` field on a job. Pick an image that matches the user's runtime, is small enough to pull fast, and is widely available on GitLab.com's shared runners.
## Defaults by stack
| Stack | Default image | Why |
|---|---|---|
| Node.js | `node:lts-alpine` | Long-term support, Alpine for size. Use specific major (`node:20-alpine`) when the user pins via `engines.node` |
| Python | `python:3.12-slim` | Debian slim is the standard; pyenv-style versioning is well supported |
| Go | `golang:1.23-alpine` | Static binary builds work cleanly in Alpine |
| Ruby | `ruby:3.3-alpine` | Match the user's `.ruby-version` if present |
| Rust | `rust:1-alpine` | musl target works for static binaries; switch to `rust:1` (Debian) if the build needs glibc |
| Docker build | `docker:24` + `services: docker:24-dind` | DinD pattern. See recipes.md |
| Java | `eclipse-temurin:21-jdk` | Free-to-distribute OpenJDK build |
| .NET | `mcr.microsoft.com/dotnet/sdk:8.0` | Microsoft's official image |
| Generic shell | `alpine:3.20` | When all you need is a shell and basic tools |
Put `image:` in `default:` if most jobs use the same image. Override `image:` per job only when the job needs a different tool (linter image, registry image, dind, etc.).
## Choosing between Alpine and Debian variants
Alpine images are 5 to 10 times smaller than their Debian counterparts and pull faster, but use musl libc rather than glibc. Quirks to keep in mind:
- Native modules built for glibc (some Node.js, Python wheels) may fail on Alpine. If `npm install` or `pip install` fails with a linker error, switch to the Debian variant.
- Alpine uses `apk` for packages, not `apt`. Adjust `before_script:` accordingly.
- Some images do not have an Alpine variant (e.g., `mcr.microsoft.com/dotnet/sdk`).
Default to Alpine; switch to the Debian/slim variant on the first sign of a native-module failure.
## Pinning image versions
Prefer concrete major or minor tags over `latest`:
- Good: `node:20-alpine`, `python:3.12-slim`, `golang:1.23-alpine`.
- Bad: `node`, `python`, `golang`, `*:latest`.
Concrete tags survive upstream churn; `latest` does not. The exception is `docker:24` for DinD, which conventionally tracks the major.
## Multi-platform builds
When the user needs to build for multiple architectures (typically `linux/amd64` and `linux/arm64`):
- Use a Catalog component if one exists (see `references/catalog.md`).
- For Docker images, use `docker buildx` with QEMU. Add `services: docker:24-dind` and pre-register binfmt with `docker run --rm --privileged tonistiigi/binfmt --install all` in `before_script:`.
- Multi-platform builds work on GitLab.com shared runners but the `docker:24-dind` service consumes more pipeline minutes than a single-arch build. Mention this to the user.
## Language version detection signals
Pick the version from the user's repo when it is pinned:
| Stack | File | Field |
|---|---|---|
| Node.js | `package.json` | `engines.node` |
| Node.js | `.nvmrc` | the file contents |
| Python | `pyproject.toml` | `[tool.poetry.dependencies] python` or `[project] requires-python` |
| Python | `.python-version` | the file contents |
| Ruby | `Gemfile` | `ruby '3.3.0'` |
| Ruby | `.ruby-version` | the file contents |
| Go | `go.mod` | `go 1.23` |
| Rust | `rust-toolchain` or `rust-toolchain.toml` | `channel` or contents |
When the user has not pinned a version, default to the latest LTS or stable and tell them you picked it.
## When to use a custom image
Build a custom image when:
- The user's `before_script:` installs the same heavy dependencies on every job (Postgres client, Chrome for headless tests, system libraries).
- The recipe needs both language A and language B in the same job and no public image bundles both.
Push the custom image to the project's container registry (`$CI_REGISTRY_IMAGE/ci:tag`) in a one-off build, then reference it from `image:` in subsequent jobs. The user's first pipeline should not jump straight to a custom image; suggest it only after they hit real cost in `before_script:`.
## Registry credentials
For images in GitLab's own registry, `$CI_JOB_TOKEN` is the credential. For private images in another registry:
- Configure CI/CD variables `DOCKER_AUTH_CONFIG` (or per-registry `CI_REGISTRY_USER`/`CI_REGISTRY_PASSWORD` for that host).
- Mark them as masked + protected. See `references/onboarding.md` for the UI path.
# GitLab CI mental model
Load this when you need to explain "what is GitLab CI" to a user, or when placing a recommendation in context. It is the conceptual frame `docs.gitlab.com/ci/` teaches new users. Anchor your explanations here instead of inventing your own.
## The four-step journey
GitLab teaches CI/CD as a sequence:
1. **Configure your pipeline** in `.gitlab-ci.yml`.
2. **Find or create runners** to execute jobs.
3. **Use CI/CD variables and expressions** for configuration and secrets.
4. **Use CI/CD components** to compose reusable, versioned units.
Most user questions fit into exactly one of those four buckets. Use that as a routing layer.
## 1. Configure your pipeline
The fundamental unit is a **pipeline**. A pipeline is defined in a single file at the repo root: `.gitlab-ci.yml`.
A pipeline contains **jobs**. Jobs are grouped into **stages**. Within a stage, jobs run in parallel. Stages themselves run sequentially: every job in `build` finishes before any job in `test` starts. The canonical first pipeline GitLab shows new users has three stages: `build`, `test`, `deploy`.
The DAG model (using `needs:` to declare per-job dependencies, bypassing strict stage ordering) is an optimization on top of this base model. Teach stages first; introduce `needs:` when stages start blocking obvious parallelism.
Reference: `docs.gitlab.com/ci/pipelines/`, `docs.gitlab.com/ci/jobs/`.
## 2. Find or create runners
A **runner** is a machine that executes jobs. The user almost never needs to think about this.
- On **gitlab.com free tier**, GitLab provides **hosted instance runners** automatically. Linux, Windows, macOS. No setup. Jobs run on fresh VMs. This is the default and the recommended path for any new user.
- **Self-managed runners** (group, project, or instance) exist for users with custom infrastructure, on-premises hardware, or special compliance needs. Advanced.
When a new user asks "where will my jobs run", the answer is: "automatically, on free GitLab.com runners, you do not need to set anything up". Reserve the runner conversation for users who explicitly ask about self-hosted runners or have a compliance requirement.
Reference: `docs.gitlab.com/ci/runners/`.
## 3. Use CI/CD variables and expressions
Variables come in two flavors:
- **Predefined variables**: built in by GitLab, available in every job. Common ones: `$CI_COMMIT_BRANCH`, `$CI_COMMIT_TAG`, `$CI_PIPELINE_SOURCE`, `$CI_PROJECT_DIR`, `$CI_REGISTRY`, `$CI_REGISTRY_IMAGE`, `$CI_REGISTRY_USER`, `$CI_REGISTRY_PASSWORD`, `$CI_COMMIT_REF_SLUG`, `$CI_JOB_NAME`, `$CI_DEFAULT_BRANCH`. Full list: `docs.gitlab.com/ci/variables/predefined_variables/`.
- **CI/CD variables**: user-configured. Set in **Settings > CI/CD > Variables** in the GitLab project UI. Can be marked **masked** (hidden from job logs) and **protected** (only available on protected branches and tags).
For brand-new pipelines with secrets, the realistic v1 default is masked + protected CI/CD variables. For production deployments, GitLab is steering users toward [external secret management](https://docs.gitlab.com/ci/secrets/) (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager). Mention this direction; do not force it on a first-pipeline user.
Reference syntax in `.gitlab-ci.yml` is always `$VAR_NAME`, not `${{ }}`. Variables are environment variables inside jobs, so they work with normal shell expansion in `script:`.
Reference: `docs.gitlab.com/ci/variables/`.
## 4. Use CI/CD components
A **CI/CD component** is a reusable, versioned pipeline configuration unit. Components live in projects that publish to the **CI/CD Catalog** at `gitlab.com/explore/catalog`.
The `include:` syntax:
```yaml
include:
- component: gitlab.com/components/opentofu/full-pipeline@1.0.0
inputs:
version: 1.8.0
```
Components carry one of four verification levels in the Catalog (see [`docs.gitlab.com/ci/components/#verification-badges`](https://docs.gitlab.com/ci/components/#verification-badges)):
- **GitLab-maintained** (tanuki badge): created and maintained by GitLab. Prefer for standard tasks (SAST, container scanning, Terraform/OpenTofu).
- **GitLab Partner**: independently created and maintained by a GitLab-verified partner. Provided as-is without warranty.
- **Verified creator**: maintained by a user verified by an administrator (self-managed and dedicated instances).
- (no badge): unverified. Use only with caution and after auditing.
See `references/catalog.md` for the verified components the skill recommends and the live lookup script.
Version pinning is mandatory. Always pin to a release tag. Never use `~latest`. Pinning to a commit SHA, semantic version tag, or branch name all work; the recommended form is a semantic version tag.
When the user asks for a job that fits a standard task (SAST, container scanning, infrastructure deployment, Docker build), search `references/catalog.md` first. If a curated component exists for the task, recommend it instead of a custom implementation.
Reference: `docs.gitlab.com/ci/components/`.
## Post-commit experience
When the user pushes their first commit with a `.gitlab-ci.yml`:
1. GitLab detects the file and creates a pipeline automatically.
2. The pipeline runs on free hosted runners (on gitlab.com) or on the user's registered runners (self-managed).
3. The user finds the pipeline under **Build > Pipelines** in the GitLab project UI.
4. Each job has a log accessible by clicking the job name in the pipeline graph.
Tell the user to expect this. Tell them where to look.
## Idiomatic patterns to prefer
- **Hidden jobs** (`.base`) + `extends:` for reuse. Not YAML anchors.
- **`default:`** at the top of the file for fields shared by most jobs (`image`, `before_script`, `tags`).
- **`workflow:rules:`** to gate pipeline creation (run only on MR, run only on default branch, etc.).
- **`rules:`** (not `only:` or `except:`, both deprecated) for per-job conditional execution.
- **Job names** that read as English phrases: `lint code`, `build image`, `test python 3.11`. Reserved keywords (`image`, `services`, `stages`) cannot be used as job names. Maximum 255 characters.
- **Parallel variants**: `test ruby 1/3`, `test ruby 2/3`, `test ruby 3/3` (or `parallel: 3` if the script handles the index). GitLab's UI groups these visually.
# Onboarding to GitLab
Load this when the user has no GitLab project on their git remote yet and the workflow needs to walk them through creating one and pushing. Triggered from Workflow 1 step 1.8 when `git remote -v` returns no GitLab remote, or when the user explicitly says they are new to GitLab.
## Contents
- Prerequisites
- Step 1: Create a project at `gitlab.com/projects/new`
- Step 2: Add the GitLab remote
- Step 3: First push
- Step 4: Watch the pipeline
- CI/CD Variables (for the user's secrets)
- Permission-asking checklist
- Free-tier runner reassurance
## Prerequisites
The user needs:
- A free GitLab.com account. If they do not have one, point them at <https://gitlab.com/users/sign_up> first. Free is enough for the entire flow described here.
- `git` installed locally (already true if they have the project under git).
That is the whole list. The user does **not** need to install GitLab Runner, configure CI/CD variables ahead of time, or have a paid tier.
## Step 1: Create a project at `gitlab.com/projects/new`
This step happens in the user's browser. Do not try to do it via the API on their behalf without explicit permission.
Tell the user:
1. Open <https://gitlab.com/projects/new>.
2. Click "Create blank project".
3. Pick a project name and a namespace (their personal namespace is fine; a group is fine if they have one).
4. **Leave "Initialize repository with a README" unchecked.** They already have a local repo; the GitLab project should start empty so the push lands cleanly.
5. Click "Create project".
When they confirm the project exists, ask for the project URL (e.g., `https://gitlab.com/<their-namespace>/<project>`). The agent uses that URL to write the `git remote add` command in step 2.
## Step 2: Add the GitLab remote
Ask for explicit permission before running any `git remote` command on the user's machine.
The user can choose SSH or HTTPS. Use whichever they prefer; ask if they have an SSH key set up at <https://gitlab.com/-/user_settings/ssh_keys>.
```bash
# SSH (recommended if the user has an SSH key on gitlab.com)
git remote add gitlab git@gitlab.com:<namespace>/<project>.git
# HTTPS (works without an SSH key; will prompt for credentials on push)
git remote add gitlab https://gitlab.com/<namespace>/<project>.git
```
After the command runs, verify with `git remote -v`. The new `gitlab` remote should appear.
If the user already has a remote named `gitlab` pointed elsewhere, ask whether to overwrite it (`git remote set-url gitlab ...`) or use a different name (e.g., `gitlab-new`). Do not silently overwrite.
## Step 3: First push
Ask for explicit permission. This sends every local commit to GitLab.
```bash
git push -u gitlab <branch-name>
```
`<branch-name>` is usually `main` or the user's current branch (`git branch --show-current`). The `-u` flag sets the upstream so subsequent `git push` works without arguments.
If the user has many local branches, push them one at a time to start with; bulk pushes can be done after they confirm the pipeline behaves as expected on the first branch.
## Step 4: Watch the pipeline
The moment the push lands, GitLab detects `.gitlab-ci.yml` and creates a pipeline automatically. The user finds it at:
```
https://gitlab.com/<namespace>/<project>/-/pipelines
```
Or, in the project UI, **Build > Pipelines** in the left sidebar.
Each job links to its log. The job log shows the runner that picked it up, the image that was pulled, every line of `script:` output, and the exit status.
If the pipeline fails, switch to Workflow 3 (Debug) and offer to read the failing job's log (paste or URL).
## CI/CD Variables (for the user's secrets)
If the generated pipeline references any variable that should be a secret (e.g., `$NPM_TOKEN`, `$AWS_SECRET_ACCESS_KEY`, deploy credentials), the user configures these in the GitLab UI:
1. **Project > Settings > CI/CD > Variables**.
2. Click "Add variable".
3. Name: the variable as referenced in the YAML (e.g., `NPM_TOKEN`).
4. Value: the secret itself.
5. **Mark "Masked"** so the value is replaced with `[MASKED]` in job logs.
6. **Mark "Protected"** so the value is only available to jobs running on protected branches and tags. (Configure protected branches under **Settings > Repository > Protected branches**; `main` is protected by default.)
7. Save.
Tell the user to configure these before pushing a commit that runs the deploy job. Otherwise the job will fail at runtime with an undefined-variable error.
For production secrets at scale, point the user at GitLab's external secret managers (see the Secret handling section in `SKILL.md`): Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault via OIDC ID tokens. Premium / Ultimate tier.
## Permission-asking checklist
Get explicit permission before each of these. Approval for one does not extend to the next.
| Action | Why permission is needed |
|---|---|
| `git remote add <name> <url>` | Modifies the user's git config |
| `git remote set-url ...` | Modifies the user's git config |
| `git push ...` | Sends code to gitlab.com |
| `git push --force` | Overwrites remote history; almost never the right call here |
| Creating a project via API | The user usually creates it in the UI; if they want API creation, ask explicitly |
| Setting CI/CD variables via API | Always have the user do this in the UI; do not handle their secrets in chat or pass them via shell history |
If the user says "go ahead with all the git stuff", that authorisation covers steps 2 and 3 above (remote add + first push). It does **not** cover destructive operations like `--force` or `reset --hard`; those still need explicit per-action permission.
## Free-tier runner reassurance
If the user asks "where will my jobs actually run?", the answer is:
> On GitLab.com's free hosted runners. They are managed by GitLab, available immediately, no setup. Linux, Windows, and macOS jobs are supported. Each job runs on a fresh VM.
The user does **not** need to install GitLab Runner, register a custom runner, or configure anything about execution infrastructure. That is GitLab.com's job. The first pipeline run will use these hosted runners automatically.
If they later need custom runners (on-prem, GPU, custom OS, compliance), point them at <https://docs.gitlab.com/ci/runners/> after the first pipeline runs green. Self-managed runners are out of scope for v1 onboarding.
# Optimize reference
Workflow 4 flow plus the per-pattern playbook. Load when the user has a working pipeline and asks for it faster, cheaper, or more parallel. Apply one pattern per round. Always identify a structural reason before proposing a change.
## Workflow 4 flow
### 4.1 Snapshot the current pipeline
Run `scripts/verify.sh show -f <file>` and **paste the output verbatim as a fenced code block in your response message text** (not the Bash tool output, which auto-collapses) as the "before" snapshot. Also capture the structured form for diffing:
```
scripts/verify.sh show -f <file> --json > /tmp/pipeline-before.json
```
The JSON includes stages, jobs, when, image, and needs. The ASCII graph is what the user sees; the JSON is for the agent to diff later.
### 4.2 Identify bottlenecks
Read the existing `.gitlab-ci.yml` and check the patterns in this file (below). Pick one pattern per round; do not propose every optimization at once.
### 4.3 Propose the change
Output as a diff against the current YAML. Explain in one line why it helps (concrete reason, e.g., "this lets test and lint run concurrently; currently they wait for stage ordering"). Wait for confirmation.
### 4.4 Show the optimized pipeline
After applying the change, run `scripts/verify.sh show` again and **paste the output verbatim as a fenced code block in your response message text** as the "after" snapshot, directly below the "before". (Same rule as before: tool output alone auto-collapses; the graph must live in the message body.) The user sees the DAG diff visually without reading JSON.
If the change touched `needs:`, `artifacts:`, or stage placement, also run `scripts/verify.sh simulate`. Simulate exercises the planner's artifact passing without running real scripts; it catches "I broke the DAG" mistakes.
### 4.5 Measure (optional, opt-in)
If the user wants real numbers:
```
scripts/verify.sh show -f <file> --json > /tmp/pipeline-after.json
diff /tmp/pipeline-before.json /tmp/pipeline-after.json
```
For runtime measurement, run the pipeline locally before and after the change (`scripts/verify.sh run --confirm-docker`) and compare via `glci history show` and `glci artifacts diff <pipeline-a> <pipeline-b> --job <name>`.
Ask for commit approval per principle 5.
## Snapshot first, propose second
Before any change, capture the current pipeline graph:
```
scripts/verify.sh show --json > /tmp/pipeline-before.json
```
Re-snapshot after the change and `diff` the two JSON files to surface real changes versus cosmetic ones. For runtime measurement, run the pipeline locally before and after (`scripts/verify.sh run --confirm-docker`) and compare via `glci history show` and `glci artifacts diff <pipeline-a> <pipeline-b> --job <name>`.
Do not claim a performance win without measuring. "This should be faster" is a hypothesis, not a result.
## Pattern 1: Serial-to-DAG via `needs:`
**Detection**: jobs in different stages that have no real dependency between them. Stage ordering forces them to wait for the prior stage to finish.
**Example**:
```yaml
# Before: lint waits for build to finish, but it doesn't need the build output
build:
stage: build
script: [make build]
lint:
stage: test
script: [npm run lint]
test:
stage: test
script: [npm test]
```
```yaml
# After: lint starts immediately; test still depends on build's artifacts
build:
stage: build
script: [make build]
artifacts: { paths: [dist/] }
lint:
stage: test
needs: [] # no upstream dependency
script: [npm run lint]
test:
stage: test
needs: [{ job: build, artifacts: true }]
script: [npm test]
```
**Verify with**: `simulate`. Simulate's planner exercises the DAG and surfaces broken artifact flow without running real scripts.
**When not to apply**: if the stage-ordering wait is intentional (e.g., a deploy stage that should never start before all tests pass), leave it alone. DAG is for jobs that genuinely don't depend on each other.
## Pattern 2: Lockfile-keyed cache
**Detection**: `cache:` block missing, or `cache:key:` uses only `$CI_COMMIT_REF_SLUG` (per-branch but not lockfile-aware). The symptom: cache rebuilt on every push, even when dependencies didn't change.
**Example** (Node):
```yaml
# Before (cache rebuilt every push to main):
cache:
key: $CI_COMMIT_REF_SLUG
paths: [node_modules/]
```
```yaml
# After (cache invalidated only when package-lock.json changes):
cache:
key:
files: [package-lock.json]
paths: [node_modules/]
```
Per-language lockfile and paths:
| Stack | `files:` | `paths:` |
|---|---|---|
| Node (npm) | `[package-lock.json]` | `[node_modules/]` |
| Node (yarn) | `[yarn.lock]` | `[node_modules/, .yarn/cache/]` |
| Node (pnpm) | `[pnpm-lock.yaml]` | `[.pnpm-store/]` |
| Python (pip) | `[requirements.txt]` | `[.cache/pip/]` |
| Python (uv) | `[uv.lock]` | `[.cache/uv/]` |
| Python (poetry) | `[poetry.lock]` | `[.cache/pypoetry/]` |
| Go | `[go.sum]` | `[.cache/go-build/]` |
| Ruby (bundler) | `[Gemfile.lock]` | `[vendor/bundle/]` |
| Rust (cargo) | `[Cargo.lock]` | `[.cargo/, target/]` |
**Verify with**: `run`. Cache effectiveness only shows up when the same job runs twice; observe whether the second run uses the cache (the log says "Restoring cache" with the same key).
## Pattern 3: Narrow artifacts to what's needed
**Detection**: a job uploads a large directory and downstream jobs only consume one subdirectory. Wide artifact paths cost upload time, storage, and download time.
**Example**:
```yaml
# Before (uploads everything):
build:
artifacts:
paths: ["./"]
```
```yaml
# After (only the build output):
build:
artifacts:
paths: [dist/, public/]
expire_in: 1 week
```
`expire_in: 1 week` (or shorter) prevents the artifact from accumulating indefinitely. Default is 30 days on GitLab.com.
**Verify with**: `show` and then `run`. Show reveals the new artifact spec; run reveals the actual upload size in the log (`Uploading artifacts as "archive"`).
## Pattern 4: `parallel:matrix:` for cross-version testing
**Detection**: same job repeated across Python or Node versions via copy-paste:
```yaml
test-py-3.10:
image: python:3.10
script: [pytest]
test-py-3.11:
image: python:3.11
script: [pytest]
test-py-3.12:
image: python:3.12
script: [pytest]
```
**Fix**:
```yaml
test:
image: python:${PY}
parallel:
matrix:
- PY: ["3.10", "3.11", "3.12"]
script: [pytest]
```
GitLab's UI groups parallel-matrix jobs and surfaces them as a single test job with three variants. Runners can pick them up in parallel without additional config.
**Verify with**: `show`. The graph reveals all expanded jobs (`test [3.10]`, `test [3.11]`, `test [3.12]`). Confirm the count matches what you intended.
## Pattern 5: `interruptible: true`
**Detection**: pushing a fixup commit to a branch with a pipeline already running spawns a second pipeline; the first keeps running and burns minutes. The same for force-pushes to MR branches.
**Fix** (apply at the `default:` block to opt all jobs in):
```yaml
default:
interruptible: true
```
When a new pipeline starts for the same ref, GitLab cancels the in-flight one. Jobs with side effects (deployments) should override with `interruptible: false`.
**Verify with**: requires a real GitLab pipeline (glci has no concept of "newer pipeline for the same ref"). Manual: push twice in quick succession and confirm GitLab cancels the first.
## Pattern 6: Pin images to specific tags
**Detection**: `image: node` (no tag) or `image: node:lts` (rolling tag). The pipeline behavior changes silently when the upstream image moves.
**Fix**:
```yaml
# Before:
image: node:lts
# After (pinned to a specific minor + distro):
image: node:22.11-bookworm-slim
# Or (immutable, pinned to a digest):
image: node@sha256:abc123...
```
For the strictest reproducibility, pin to a digest. For practical reproducibility (security patches still flow), pin to a specific tag matched to the distro.
**Verify with**: `run`. Run once and confirm the image pulls cleanly; you can also confirm `docker images` shows the pinned tag.
## Pattern 7: Cache `key:files:` vs per-branch keys
**Detection**: cache works but is stack-aware enough to be useful, but multiple branches with the same dependencies fight over the cache.
**Pattern A** (single cache per lockfile, shared across branches):
```yaml
cache:
key:
files: [package-lock.json]
paths: [node_modules/]
```
This shares the cache across branches whenever the lockfile is the same. Pros: maximum reuse. Cons: a different branch with the same lockfile can poison the cache if it writes weird files.
**Pattern B** (per-branch, lockfile-keyed):
```yaml
cache:
key:
prefix: $CI_COMMIT_REF_SLUG
files: [package-lock.json]
paths: [node_modules/]
```
Each branch has its own cache; the lockfile invalidates within a branch. Pros: isolation. Cons: cold cache on first push of every new branch.
Pick A for projects with stable lockfiles, B for projects with frequent feature branches.
**Verify with**: `run`. Run on two branches with the same lockfile to confirm cache behavior matches expectation.
## Pattern 8: Drop redundant `before_script`
**Detection**: every job has the same `before_script`, repeated. The `default:` block exists to host shared setup once.
**Fix**:
```yaml
# Before (duplicated):
build:
before_script: [npm ci]
script: [npm run build]
test:
before_script: [npm ci]
script: [npm test]
```
```yaml
# After (one place):
default:
before_script: [npm ci]
build:
script: [npm run build]
test:
script: [npm test]
```
Jobs that need a different `before_script` can still override per-job; the default only applies where there's no override.
**Verify with**: `show --json` before and after. Job count and execution order should be unchanged; the YAML is shorter.
## Anti-patterns to refuse
- **Removing `needs:` to "simplify" the pipeline**: this gives up DAG parallelism. Refuse unless the user explicitly says they want serial execution.
- **Dropping `interruptible:` to "be safe"**: leaving an in-flight pipeline running to completion when a newer commit has superseded it wastes runner time. The right answer is `interruptible: true` plus per-job `interruptible: false` for genuine side-effect jobs.
- **Tightening `rules:` without a reason**: don't propose narrowing `rules:` for "performance"; rules don't affect job runtime, only whether the job runs at all.
- **Switching cache to no-key (`cache: { paths: [...] }`)**: that produces one cache shared by every branch and every ref, which usually corrupts. Always provide a key.
## Measuring the win
Before claiming an optimization worked:
1. `scripts/verify.sh show --json` before and after, diffed.
2. For runtime impact: `scripts/verify.sh run --confirm-docker` before and after, with `glci history show` capturing wall-clock per job.
3. Report the actual numbers: "build went from 2:45 to 1:30; test from 3:10 to 2:50 (now starts in parallel with lint)." Do not report relative percentages without absolute numbers.
If measurement is impractical (the user is iterating quickly), say so: "I applied the pattern; I haven't measured the runtime impact. If you want a number, run before and after with `glci run --confirm-docker`."
# Starter pipeline recipes
Load this when generating an initial `.gitlab-ci.yml` for a user. Every recipe follows GitLab's canonical shape: `build`, `test`, `deploy` (deploy as a stub if no target is set up). All recipes use `default:` for shared fields, hidden jobs + `extends:` for reuse, and pin component versions.
## Contents
- Detection signals (how to pick a recipe)
- Local validation and matrix breadth
- Recipe: Node.js with Jest (or test runner of choice)
- Recipe: Python with pytest
- Recipe: Go
- Recipe: Ruby with RSpec
- Recipe: Rust with cargo test
- Recipe: Docker image build and push
- When the user has a deploy target
## Detection signals
Read these files to pick the recipe. Detection happens first; ask the user only if the signals are ambiguous.
| Signal file | Stack |
|---|---|
| `package.json` (no TypeScript indicator) | Node.js |
| `package.json` + `tsconfig.json` | TypeScript on Node.js |
| `pyproject.toml`, `setup.py`, `requirements.txt` | Python |
| `go.mod` | Go |
| `Gemfile` | Ruby |
| `Cargo.toml` | Rust |
| `Dockerfile` (no other strong signal) | Docker image build |
| `pom.xml`, `build.gradle` | Java (not covered in v1) |
| `*.csproj` | .NET (not covered in v1) |
When multiple signals exist, pick the dominant one and confirm with the user before generating.
## Local validation and matrix breadth
Recipes below may suggest `parallel:matrix` (Python versions, Node versions, Go versions, Ruby versions, Rust toolchains, platform variants). On GitLab.com runners this is free: jobs fan out in parallel across dedicated runners. On a developer laptop, each matrix entry spawns its own Docker container and shares the host's CPU, memory, image-pull bandwidth, and disk.
**Recommendation when generating a starter pipeline**: pin the matrix to 1 or 2 entries in the YAML committed to the repo. The user's local `verify.sh run` then completes in a few minutes instead of saturating their laptop. When the user pushes to GitLab.com, the same YAML runs on hosted runners with the full matrix expansion they want.
The skill should:
- For initial pipeline generation (Workflow 1): default to a single matrix entry (e.g., the highest-version Python only). Mention that adding more entries is a one-line change once they're confident.
- For optimization (Workflow 4): if the user wants the full matrix, suggest gating it behind `rules: - if: '$CI_PIPELINE_SOURCE == "schedule"'` so daily scheduled pipelines exercise the full matrix while every-push pipelines stay fast.
- For local verification: if the YAML committed has a wide matrix, suggest running `glci run <one-matrix-entry> --reuse-artifacts --confirm-docker` instead of the full pipeline.
## Recipe: Node.js with Jest (or test runner of choice)
Detected by `package.json` with a `test` script. Pick the Node version from `engines.node` in `package.json` if present; default to `lts-alpine`.
```yaml
default:
image: node:lts-alpine
interruptible: true
cache:
key:
files: [package-lock.json]
paths: [.npm/]
before_script:
- npm ci --cache .npm --prefer-offline
stages:
- build
- test
- deploy
build:
stage: build
script:
- npm run build
artifacts:
paths: [dist/]
expire_in: 1 week
lint:
stage: test
script: [npm run lint]
needs: []
unit-test:
stage: test
script: [npm test]
needs: []
deploy:
stage: deploy
script:
- echo "Configure your deploy target. See docs.gitlab.com/ci/environments/"
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
```
Rationale: `default:` covers `image`, `cache`, and `before_script` (most jobs need `npm ci`). `unit-test` and `lint` declare `needs: []` so they start as soon as the pipeline begins, in parallel with `build`. `deploy` is manual and gated to the default branch.
### Variant: no committed lockfile
Some Node projects gitignore `package-lock.json`. This is common for libraries published to npm; older packages may also predate the lockfile convention. When the project has no committed lockfile, adapt two parts of the recipe:
- **Cache key**: use `package.json` instead of `package-lock.json`. Cache invalidates whenever `package.json` changes (a coarser signal than the lockfile, acceptable for projects without one).
- **Install command**: `npm install` instead of `npm ci`. `npm ci` requires a tracked lockfile and exits non-zero if one is missing.
```yaml
default:
cache:
key:
files: [package.json]
paths: [.npm/]
before_script:
- npm install --cache .npm --prefer-offline --no-audit --no-fund
```
`--no-audit` and `--no-fund` shave seconds off each install. Useful in CI; harmless locally.
### Variant: no build script (runtime-only library)
Some packages have no `npm run build` script: pure-JS libraries, runtime utilities, anything that publishes its source directly. Two reasonable shapes for the build stage:
**`npm pack`** (recommended for npm-published libraries): produces the publishable `.tgz` as an artifact. Real build output; a downstream `publish` job consumes it.
```yaml
build:
stage: build
script:
- npm pack
artifacts:
paths: ["*.tgz"]
expire_in: 1 week
```
**Omit the build stage entirely**: only `test` and `deploy`. Use when there is genuinely nothing to build (e.g., a runtime CLI that ships its source verbatim with no packaging step). Update `stages:` accordingly.
For these projects the `deploy` job is usually `npm publish`, gated on `$CI_COMMIT_TAG`, with `NPM_TOKEN` set as a masked, protected CI/CD variable.
## Recipe: Python with pytest
Detected by `pyproject.toml`, `setup.py`, or `requirements.txt`. Pick the Python version from `pyproject.toml` if pinned, else `python:3.12-slim`. Use pip cache.
```yaml
default:
image: python:3.12-slim
interruptible: true
cache:
key:
files: [pyproject.toml, requirements.txt]
paths: [.cache/pip/]
before_script:
- python -m venv venv
- source venv/bin/activate
- pip install --cache-dir .cache/pip -e ".[test]"
stages:
- build
- test
- deploy
build:
stage: build
script:
- python -m build
artifacts:
paths: [dist/]
expire_in: 1 week
rules:
- if: $CI_COMMIT_TAG
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
lint:
stage: test
script:
- pip install ruff
- ruff check .
needs: []
test:
stage: test
script:
- pytest --junitxml=report.xml
artifacts:
reports:
junit: report.xml
needs: []
deploy:
stage: deploy
script:
- echo "Configure your deploy target. See docs.gitlab.com/ci/environments/"
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
```
Rationale: pip cache keyed on dependency files; `artifacts:reports:junit:` puts test results into GitLab's UI test-report view; `build` runs only on the default branch and tags to avoid wasting CI time on feature branches.
## Recipe: Go
Detected by `go.mod`. Use `golang:1.23-alpine` (or the latest stable). Cache the module download.
```yaml
default:
image: golang:1.23-alpine
interruptible: true
variables:
GOPATH: $CI_PROJECT_DIR/.go
cache:
key:
files: [go.sum]
paths:
- .go/pkg/mod/
before_script:
- mkdir -p .go
- go mod download
stages:
- build
- test
- deploy
build:
stage: build
script:
- go build -o app ./...
artifacts:
paths: [app]
expire_in: 1 week
lint:
stage: test
image: golangci/golangci-lint:latest-alpine
script: [golangci-lint run]
needs: []
test:
stage: test
script:
- go test -race -coverprofile=coverage.out ./...
needs: []
coverage: '/coverage: \d+\.\d+% of statements/'
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage.xml
deploy:
stage: deploy
script:
- echo "Configure your deploy target."
needs: [build]
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
```
Rationale: `GOPATH` under `$CI_PROJECT_DIR/.go` keeps the cache portable. `lint` uses a different image (`golangci-lint`); job-level `image:` overrides `default:image:`.
## Recipe: Ruby with RSpec
Detected by `Gemfile`. Use the Ruby version from `.ruby-version` if present, else `ruby:3.3-alpine`.
```yaml
default:
image: ruby:3.3-alpine
interruptible: true
cache:
key:
files: [Gemfile.lock]
paths: [vendor/ruby/]
before_script:
- apk add --no-cache build-base
- bundle config set --local deployment true
- bundle install --jobs $(nproc) --path vendor
stages:
- build
- test
- deploy
build:
stage: build
script:
- bundle exec rake build
artifacts:
paths: [pkg/]
expire_in: 1 week
rubocop:
stage: test
script: [bundle exec rubocop]
needs: []
rspec:
stage: test
script: [bundle exec rspec]
needs: []
artifacts:
reports:
junit: tmp/rspec.xml
deploy:
stage: deploy
script:
- echo "Configure your deploy target."
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
```
## Recipe: Rust with cargo test
Detected by `Cargo.toml`. Use `rust:1-alpine` or the latest stable.
```yaml
default:
image: rust:1-alpine
interruptible: true
variables:
CARGO_HOME: $CI_PROJECT_DIR/.cargo
cache:
key:
files: [Cargo.lock]
paths:
- .cargo/registry/cache/
- target/
before_script:
- apk add --no-cache musl-dev
stages:
- build
- test
- deploy
build:
stage: build
script: [cargo build --release]
artifacts:
paths: [target/release/]
expire_in: 1 week
clippy:
stage: test
script:
- rustup component add clippy
- cargo clippy -- -D warnings
needs: []
test:
stage: test
script: [cargo test]
needs: []
deploy:
stage: deploy
script:
- echo "Configure your deploy target."
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
```
## Recipe: Docker image build and push
Detected by `Dockerfile` at repo root (and no other dominant stack signal). Push to GitLab's built-in container registry.
```yaml
default:
interruptible: true
stages:
- build
- test
- deploy
build:
stage: build
image: docker:24
services:
- docker:24-dind
variables:
DOCKER_HOST: tcp://docker:2375
DOCKER_TLS_CERTDIR: ""
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
script:
- docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -t $CI_REGISTRY_IMAGE:latest .
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
- docker push $CI_REGISTRY_IMAGE:latest
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_TAG
hadolint:
stage: test
image: hadolint/hadolint:latest-alpine
script: [hadolint Dockerfile]
needs: []
deploy:
stage: deploy
script:
- echo "Configure your deploy target."
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
```
Rationale: uses GitLab's predefined registry variables (`$CI_REGISTRY`, `$CI_REGISTRY_IMAGE`, `$CI_REGISTRY_USER`, `$CI_REGISTRY_PASSWORD`) so no manual variable setup is needed; tags both the SHA and `latest`; gates pushes to the default branch and tags.
For builds that fit a Catalog component (multi-arch, BuildKit, signing), look up `references/catalog.md` first.
## When the user has a deploy target
The recipes above stub `deploy:` because the deploy target is not detectable from repo files. When the user tells you their target, replace the stub:
- **Kubernetes**: `kubectl apply` with image substitution via `envsubst` or `sed`; or a Catalog component (e.g., Auto Deploy).
- **Static site (GitLab Pages)**: rename the deploy job to `pages` and produce `public/` as the artifact.
- **Container deployment (Cloud Run, Fargate, etc.)**: cloud-CLI invocation; consider whether a Catalog component exists.
- **Package registries (npm, PyPI, RubyGems)**: language-specific `*publish*` invocation gated to `if: $CI_COMMIT_TAG`.
Each of these warrants a follow-up conversation with the user. Do not guess the deploy mechanism.
# GitLab CI syntax reference
Load this when generating or reviewing `.gitlab-ci.yml`. Curated keyword set: the keywords this skill produces, with a one-line definition each and a pointer to canonical docs. Not a clone of `docs.gitlab.com/ci/yaml/` (which has the full surface).
For any keyword not listed here, consult the canonical reference at https://docs.gitlab.com/ci/yaml/.
## At a glance
| Category | Keywords |
|---|---|
| Global | `stages`, `variables`, `default`, `include`, `workflow` |
| Job (essential) | `script`, `stage`, `image`, `rules`, `needs`, `artifacts`, `cache` |
| Job (common) | `before_script`, `after_script`, `variables`, `tags`, `extends`, `services` |
| Job (parallelism) | `parallel`, `parallel:matrix` |
| Job (control) | `when`, `allow_failure`, `interruptible`, `retry`, `timeout` |
| Job (lifecycle) | `environment`, `resource_group`, `trigger`, `release` |
| Reuse | `!reference`, hidden jobs (`.name`), `extends` |
| Pipeline header | `spec:inputs` (for reusable pipelines via `include:`) |
## Global keywords
### `stages`
Defines pipeline stages and their order. Jobs without `stage:` default to `test`. If `stages:` is omitted, GitLab uses `[.pre, build, test, deploy, .post]`.
```yaml
stages:
- build
- test
- deploy
```
Docs: https://docs.gitlab.com/ci/yaml/#stages.
### `variables`
Pipeline-wide variables. Available in every job.
```yaml
variables:
NODE_VERSION: "20"
CI_DEBUG_TRACE: "false"
```
Docs: https://docs.gitlab.com/ci/yaml/#variables.
### `default`
Default values applied to every job. Idiomatic place for shared `image:`, `before_script:`, `tags:`, `interruptible:`, etc.
```yaml
default:
image: node:lts-alpine
interruptible: true
before_script:
- npm ci --cache .npm --prefer-offline
```
Docs: https://docs.gitlab.com/ci/yaml/#default.
### `include`
Pulls in YAML from another source. Components, project files, remote URLs, templates.
```yaml
include:
- component: gitlab.com/components/opentofu/full-pipeline@1.0.0
inputs:
version: 1.8.0
- local: '/.gitlab/ci/security.yml'
- template: 'Jobs/SAST.gitlab-ci.yml'
```
Always pin components to a release tag, never `~latest`. Docs: https://docs.gitlab.com/ci/yaml/#include.
### `workflow`
Controls whether the pipeline runs at all. Use `workflow:rules:` to gate on branch, tag, MR, or schedule.
```yaml
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_TAG
```
Docs: https://docs.gitlab.com/ci/yaml/#workflow.
## Essential job keywords
### `script`
The shell commands the job runs. Each item is one shell invocation.
```yaml
test:
script:
- npm test
```
Docs: https://docs.gitlab.com/ci/yaml/#script.
### `stage`
The stage this job belongs to. Must exist in `stages:`.
```yaml
test:
stage: test
script: [npm test]
```
### `image`
The container image the job runs in.
```yaml
test:
image: node:20-alpine
script: [npm test]
```
Use `default:image:` if most jobs share an image. Docs: https://docs.gitlab.com/ci/yaml/#image.
### `rules`
When the job runs. Replaces deprecated `only:` and `except:`.
```yaml
deploy:
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: on_success
- when: never
```
Docs: https://docs.gitlab.com/ci/yaml/#rules.
### `needs`
Declares per-job dependencies, enabling DAG execution (skip stage boundaries).
```yaml
package:
stage: deploy
needs: ["build", "test"]
```
Docs: https://docs.gitlab.com/ci/yaml/#needs.
### `artifacts`
Files produced by the job and passed to later jobs.
```yaml
build:
artifacts:
paths:
- dist/
expire_in: 1 week
```
Docs: https://docs.gitlab.com/ci/yaml/#artifacts.
### `cache`
Files cached across pipelines (e.g. `node_modules/`, `.cargo/registry/`). See `references/caching.md` for cache-key patterns.
```yaml
test:
cache:
key:
files: [package-lock.json]
paths:
- node_modules/
```
Docs: https://docs.gitlab.com/ci/yaml/#cache.
## Common job keywords
### `before_script`, `after_script`
Setup and teardown. Use `default:before_script:` for shared setup.
### `variables` (job-level)
Per-job variables. Override pipeline-level `variables`.
### `tags`
Select runners by label. Most users on gitlab.com leave this empty (shared runners). Use only when the user has registered custom runners.
### `extends`
Inherit from another job. The idiomatic GitLab reuse pattern, paired with hidden jobs.
```yaml
.docker-job:
image: docker:24
services:
- docker:24-dind
build-image:
extends: .docker-job
stage: build
script: [docker build -t $CI_REGISTRY_IMAGE .]
```
Docs: https://docs.gitlab.com/ci/yaml/#extends.
### `services`
Sidecar containers (databases, dind, redis). Run alongside the job container.
```yaml
test:
services:
- postgres:16
variables:
POSTGRES_DB: test
```
Docs: https://docs.gitlab.com/ci/yaml/#services.
## Parallelism
### `parallel`
Run N copies of a job. Each gets `$CI_NODE_INDEX` (1-based).
```yaml
test:
parallel: 5
script: [./test --shard $CI_NODE_INDEX/$CI_NODE_TOTAL]
```
### `parallel:matrix`
Run a job per variable combination.
```yaml
test:
parallel:
matrix:
- NODE_VERSION: ["18", "20", "22"]
OS: [linux, alpine]
```
Docs: https://docs.gitlab.com/ci/yaml/#parallel.
## Reuse patterns
### Hidden jobs
A job whose name starts with `.` is hidden: it does not run, but can be `extends:`-ed. The idiomatic place to define reusable job templates.
```yaml
.test-base:
stage: test
cache:
key:
files: [package-lock.json]
paths: [node_modules/]
unit-test:
extends: .test-base
script: [npm test]
integration-test:
extends: .test-base
script: [npm run test:integration]
```
### `!reference`
Reuse a specific block from another job or list. Avoids the all-or-nothing nature of `extends:`.
```yaml
.shared-rules:
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
deploy:
rules:
- !reference [.shared-rules, rules]
- if: $CI_COMMIT_TAG
```
Docs: https://docs.gitlab.com/ci/yaml/yaml_optimization/#reference-tags.
## Common predefined variables
When you write `.gitlab-ci.yml` for a user, these are the predefined variables your script: blocks will most often reference. Full list: https://docs.gitlab.com/ci/variables/predefined_variables/.
| Variable | What it is |
|---|---|
| `$CI_COMMIT_BRANCH` | The branch name; empty for tag and MR pipelines |
| `$CI_COMMIT_TAG` | The tag name; empty otherwise |
| `$CI_COMMIT_REF_SLUG` | The branch or tag, slugified, useful for cache keys |
| `$CI_DEFAULT_BRANCH` | Usually `main` |
| `$CI_PIPELINE_SOURCE` | `push`, `merge_request_event`, `schedule`, `web`, `api`, `trigger`, `pipeline` |
| `$CI_PROJECT_DIR` | The checkout directory |
| `$CI_PROJECT_PATH` | `group/project` |
| `$CI_REGISTRY` | The project's container registry host |
| `$CI_REGISTRY_IMAGE` | The image base path for `$CI_REGISTRY` |
| `$CI_REGISTRY_USER`, `$CI_REGISTRY_PASSWORD` | Auth for `$CI_REGISTRY` |
| `$CI_JOB_NAME`, `$CI_JOB_STAGE` | The current job and stage |
| `$CI_COMMIT_SHA` | Full SHA of the commit being built |
## Things to avoid
- `only:` and `except:` (deprecated; use `rules:`).
- YAML anchors (`&` and `*`) for reuse (use `extends:` and `!reference:`).
- `~latest` as a component version pin (always pin to a release tag).
- Quoting numeric variable values inconsistently (always quote in `parallel:matrix:` to avoid YAML int coercion).
- Hardcoded secrets (always use **Settings > CI/CD > Variables**).
- `image:` per job when the same image is used everywhere (use `default:image:`).
# Verification reference
Detailed handling for `scripts/verify.sh`, glci's verification ladder, and what each tier catches or misses. Load when picking a tier for a specific change, interpreting tier output, or recovering when glci or Docker is missing.
The happy path stays in `SKILL.md` (the "Verifying generated YAML" section and workflows). This file is for the cases that need more than one sentence to explain.
## The four tiers
| Tier | Command (under the hood) | Time | Docker | Network | Catches |
|---|---|---|---|---|---|
| `lint` | `glci lint -f FILE` (falls back to `glab ci lint`) | <1s | no | no | YAML syntax, include resolution, `needs:` references, stage names, timeout format, no cycles |
| `show` | `glci show -f FILE [--json] [--context X]` | 1 to 2s | no | no | `rules:` evaluation under a given context, DAG shape, `parallel:matrix` expansion, which jobs actually run |
| `simulate` | `glci run --simulate -f FILE` | 5 to 30s | yes | optional | full execution plan, artifact flow, variable interpolation, expanded matrix. Scripts echoed, services skipped, dummy artifacts |
| `run` | `glci run [job...] -f FILE` | 30s to minutes | yes | yes for components | image pulls, service startup, script runtime, cache, artifact upload, real outputs |
Each tier is a strict superset of the one above it. If `simulate` passes, `lint` and `show` would also pass; the converse is not true.
## Tier selection by change type
Pick the cheapest tier that catches a regression for the kind of change you made.
| Change | Cheapest tier |
|---|---|
| YAML syntax | lint |
| `needs:` references a job that doesn't exist | lint |
| Circular `needs:` dependency | lint |
| `rules:` expression syntax | lint |
| Stage missing from `stages:` | lint |
| Include path or component ref doesn't resolve | lint |
| New job's `rules:` doesn't fire in the context you expected | show |
| Parallel matrix produced the wrong shape | show |
| `workflow:rules:` blocks the pipeline entirely | show |
| Component swap dropped jobs from the graph | show |
| `needs:` artifact flow broken across stages | simulate |
| Variable interpolation fails (`$VAR` empty when used) | simulate |
| Custom image fails to pull | run |
| Script exits non-zero | run |
| Service container fails to start | run |
| Cache key mismatch (cold cache rebuilt every run) | run |
| Real test failure | run |
For Workflow 2 (adding one job or swapping a component), the most useful incremental check is `glci run <new-job> --reuse-artifacts`: it runs only the changed piece, reusing any cached upstream artifacts.
## verify.sh exit codes
| Exit | Meaning | Skill action |
|---|---|---|
| 0 | Verification passed at the requested tier | Present the YAML to the user |
| 1 | YAML or runtime problem (the configuration or scripts are wrong) | Surface the error verbatim, classify per the table above, propose a fix |
| 2 | Environment problem (missing tool, Docker down, missing opt-in flag) | Surface what's missing, recommend a fix (install glci, start Docker, pass `--confirm-docker`), do not retry the same command |
Distinguish exit 1 from exit 2 before reporting to the user. Exit 1 is "your YAML has a bug"; exit 2 is "the verifier could not run."
## Output parsing
### `glci lint` (lint tier)
Plain text to stderr on failure. Exit 0 on success. Common error shapes:
```
job "test" needs "build" which does not exist
job "deploy" has invalid timeout "xyz": time: invalid duration "xyz"
```
Extract the offending job name and the missing reference; map to a one-line fix suggestion. If `verify.sh lint` fell back to `glab ci lint` (glci absent), errors come from the GitLab API and have a different shape (typically a single error message per file rather than a list).
### `glci show` (show tier)
Default output is an ASCII pipeline graph with stages, jobs, DAG arrows, and status symbols. Use `--json` for structured output:
```
scripts/verify.sh show --json
```
The JSON contains `stages` (array) and `jobs` (array of `{name, stage, when, allow_failure, image, ...}`). Compare before/after JSON to spot DAG changes in Workflow 4 (Optimize). The `--context` flag accepts `branch=NAME`, `merge_request`, `tag=NAME`, `env=NAME`, or a preset from `.glciconfig.toml`; defaults to `merge_request`.
### `glci run --simulate` (simulate tier)
TUI-style log streaming during execution. Each job prints `[simulate] $ <command>` lines instead of running the real commands. Dummy artifacts are produced so downstream jobs see the artifact files exist. Final summary: `✓ Pipeline PASSED` or per-job failure detail.
After the run, fetch any specific job's log via `glci log <pipeline-id> <job-name>` (the pipeline id is shown in the streamed output; the latest pipeline is the default).
### `glci run` (run tier)
Same streaming format as simulate, but with real script output. Exit 0 success, 1 job failure, 2 system error (per glci's documented exit codes). Use `glci log` to retrieve a single job's trace cleanly after the run completes; live streaming interleaves output across parallel jobs and is harder to parse.
## Degradation when glci is missing
`scripts/verify.sh` handles this differently per tier:
- **lint tier**: falls back to `glab ci lint`. The `glab` backend needs a GitLab project context (the lint API is per-project). verify.sh resolves the project from, in order: a `--project <group/project>` flag, the `VALIDATE_PROJECT` env var, or the git remote (when the user is inside a GitLab checkout). If none resolves, lint exits 2 with three options for the user: install glci instead (recommended, offline, no project required), set `VALIDATE_PROJECT`, or pass `--project` explicitly. Users on non-GitLab remotes (GitHub, Bitbucket, Codeberg) should lead with glci because the glab fallback cannot work without an explicit project.
**Constraint: lint context must be the user's own project.** The project the lint backend resolves to (via `--project`, `VALIDATE_PROJECT`, or git remote) determines which CI config the lint API uses to resolve includes and which runners are referenced. Using an arbitrary upstream project (e.g., `gitlab-org/gitlab`) as the lint context is incorrect: the lint output reflects that project's configuration, not the user's. If no project resolves and glci is not installed, do not pick an upstream project to "make lint work". Tell the user: "Lint context could not be resolved. Install glci (offline, no project required) or set `VALIDATE_PROJECT=<your-group>/<your-project>` and re-run."
- **show, simulate, run tiers**: glci has no fallback (`glab` does not implement `show` or local execution). verify.sh exits 2 with an install pointer:
```
curl -fsSL https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/raw/main/install.sh | bash
```
(Or the releases page: <https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/releases>.) Do not run the install command for the user without their explicit consent; even with consent, prefer asking the user to run it themselves. Once installed, re-run verify.sh.
When glci is missing and the user is in a hurry, lint-only verification is still meaningful. Present the YAML with the explicit caveat: "Lint passed; I could not render the pipeline graph because glci is not installed."
### Example degradation reports
Concrete templates the agent should mirror when reporting that a tier was skipped. `verify.sh` already prints the relevant facts to stderr; the agent's job is to surface them in this shape, not summarize them. See `SKILL.md` "When a verification tier is skipped" for the four-part format.
#### Docker not reachable (most common, from `verify.sh auto`)
> Lint and show passed; the YAML is structurally correct.
>
> Two tiers didn't run:
> - `glci run --simulate` would have caught artifact-flow regressions and variable interpolation bugs.
> - The smoke run (one job, real execution) would have caught image-pull failures, missing binaries in the image, and runtime script issues.
>
> Reason: Docker daemon is not reachable on this machine.
>
> To unblock locally (paste verbatim from verify.sh stderr; different per OS):
>
> ```
> brew install colima docker && colima start
> ```
>
> Or Docker Desktop: <https://www.docker.com/products/docker-desktop>
>
> Then re-run: `bash scripts/verify.sh auto -f .gitlab-ci.yml`
>
> Alternative: push the YAML to GitLab and let hosted runners run the pipeline. You don't need local Docker to ship this.
#### glci not installed (from any tier above lint)
> Lint passed via the glab fallback; the YAML's syntax is valid.
>
> Three tiers didn't run:
> - `glci show` would have rendered the pipeline graph (DAG, stages, parallel matrix expansion).
> - `glci run --simulate` would have validated artifact flow and variable interpolation.
> - The smoke run would have exercised image pulls and scripts.
>
> Reason: glci is not installed on this machine.
>
> To unblock (offline, no GitLab account required):
>
> ```
> curl -fsSL https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/raw/main/install.sh | bash
> ```
>
> Then re-run: `bash scripts/verify.sh auto -f .gitlab-ci.yml`
#### Repo has no commits yet (from simulate / run tiers)
> Lint and show passed.
>
> The simulate and run tiers need at least one commit (glci's embedded gitlab-runner panics on commit-less repos; see verify.sh preflight).
>
> Reason: this repo has no commits yet (`git rev-parse HEAD` fails).
>
> To unblock:
>
> ```
> git add -A && git commit -m "Initial commit"
> ```
>
> Then re-run: `bash scripts/verify.sh auto -f .gitlab-ci.yml`
Do not paraphrase the install commands; copy them from verify.sh stderr. Different OSes get different commands (macOS shows Colima + Docker Desktop options; Linux shows get.docker.com).
### No shell access
Some hosts (web-only chat surfaces, read-only review agents, sandboxed environments without shell access) cannot invoke `bash` or run verify.sh. In that case:
- Skip the script invocation; do not pretend it ran.
- Tell the user that local verification was skipped (agent has no shell access).
- Tell the user to validate the YAML in the GitLab UI: **Build > Pipeline editor > Validate**. Zero local tooling required.
- Recommend installing glci for future runs so subsequent verifications get show, simulate, and run.
### Broken glci binary
Manual installs via `sudo mv` can preserve a non-executable mode and silently produce an inert binary. verify.sh checks standard locations (`/usr/local/bin/glci`, `/opt/homebrew/bin/glci`, `~/bin/glci`, `~/.local/bin/glci`) and exits 2 with `chmod +x <path>` guidance when it finds a non-executable file. If the user reports "glci not found" but installed glci recently, they may need this fix.
## Degradation when Docker is missing or unreachable
Lint and show do not need Docker; they keep working. Simulate and run exit 2 if `docker info` fails. The error tells the user to start Docker Desktop (or the daemon). For a deeper environment report, the user can run `glci doctor`, which checks Docker reachability, daemon state, token configuration, CI config parsing, and the git repository.
Note: `glci doctor` exits 0 even when individual checks fail (it reports pass/fail symbols but doesn't gate exit code on the results). `verify.sh` does not rely on doctor's exit code; instead it uses a cheap `docker info` check before invoking simulate or run, then surfaces glci's own error if simulate or run fails for any other reason.
## Higher tiers need an initial commit
The `auto`, `simulate`, and `run` tiers spin up the embedded gitlab-runner inside Docker. gitlab-runner crashes on commit-less git repos with:
```
panic: runtime error: slice bounds out of range [:8] with length 4
```
Root cause: glci falls back to `Ref = "main"` when `git rev-parse HEAD` fails, and the upstream gitlab-runner tries to slice the ref to 8 characters. `"main"` has 4. Upstream bug, surfaces in the embedded runner.
**`verify.sh` preflights this**: before invoking `glci run` (in `auto`, `simulate`, or `run` tier), it checks `git rev-parse HEAD`. If the repo has no commits, the script refuses with exit 2 and tells the user to commit first. `lint` and `show` are unaffected and run fine on commit-less repos.
When the user has just done `git init` and not yet committed (common in Workflow 5 onboarding scenarios), the skill should:
1. Run `verify.sh show` first; the rendered graph is still useful.
2. Offer to create the initial commit:
> "Your repo doesn't have a commit yet, which is fine, but glci needs one to run the pipeline locally. Want me to stage these files and commit them as 'Initial commit'? After that I can simulate the pipeline."
3. Wait for explicit permission per principle 5 (ask before destructive changes). Do not auto-commit.
4. After the commit lands, re-run `verify.sh auto`.
## Components that need a token
The Limitations section of glci's own SKILL.md states:
> `include: project:` and `include: component:` require `GITLAB_TOKEN`
This applies even to public Catalog components. If the YAML uses `include: component:` and `GITLAB_TOKEN` is not set in the environment, lint succeeds (the syntax is valid) but show/simulate/run fail at the include-resolution step with an authentication error.
When you generate or modify YAML that uses a Catalog component, preflight by checking `GITLAB_TOKEN` in the environment. If not set:
- For verification: tell the user to set `GITLAB_TOKEN` before running show or higher. The token only needs read access to the Catalog component's project (any GitLab.com account works for public components).
- Do not block presenting the YAML on this; the YAML itself is fine.
**The skip-without-token state is verification-complete**, not a failure mode. When glci emits `skipping component include ... no GitLab token configured`, the structural file-level verification (everything except the component's contributed jobs) is sound. Do not attempt to resolve the component locally to "fix" the skip warning. Instead:
1. Paste the skip-warning-bearing `glci show` output verbatim.
2. Tell the user: "Local glci cannot resolve Catalog components without a token. GitLab will resolve this on push. The structural pipeline shown above is correct."
3. Offer the optional path: set `GITLAB_TOKEN` to a real PAT (instructions in `SKILL.md` Secret handling) and re-run if local resolution is needed.
Never extract a token from local config (e.g., `~/.config/glab-cli/config.yml`) to make this skip go away. `glab` stores tokens encrypted at rest; the read value is ciphertext, not a usable bearer token. See `SKILL.md` "Never extract credentials from local files".
## glci enforces a per-job timeout
`glci run` enforces a per-job timeout via the embedded gitlab-runner. Verified empirically: a job that runs longer than the timeout is killed with `ERROR: Job exceeded the timeout limit of Xs` in the log and a pipeline failure.
**Default**: 1 hour (3600 seconds) per job, hardcoded in glci's `pkg/runner/jobspec.go` as the fallback when neither the YAML `timeout:` keyword nor the `--timeout` CLI flag is set. This matches GitLab.com's project default for job timeout, so it's not a divergence from GitLab.com behavior.
**Why this is a trap anyway**: on a developer laptop running a matrix-heavy pipeline, several jobs share CPU, memory, and disk concurrently. A job that finishes in 10 minutes on a dedicated hosted runner can take 60+ minutes locally under contention, hitting the 1-hour wall. The failure looks identical to a real test failure unless the log is read.
**Triage signal (unambiguous)**: the log contains the literal string `ERROR: Job exceeded the timeout limit of Xs`. The model should grep for `exceeded the timeout limit` in the run output. This is a deterministic signal, not a heuristic.
**Triage moves**:
1. Rerun the suspect job in isolation: `scripts/verify.sh run <job> --reuse-artifacts --confirm-docker`. Reusing upstream artifacts removes upstream contention; if the job passes solo, the failure was local concurrency, not the code.
2. Raise the timeout if the job legitimately runs longer than 1 hour: `glci run <job> --timeout 2h -f .gitlab-ci.yml`. Accepts CI durations (`30m`, `1h`, `1h30m`). The skill does not change the default; surface the override to the user with an explanation of why.
3. If the job is consistently long-running against a real workload (e.g., a 90-minute integration test), tell the user it likely needs the same treatment on GitLab.com via a YAML `timeout:` keyword on the job. Use show + simulate as the structural confidence layer locally; don't try to run it.
**Distinguish two different timeout mechanisms in glci**:
- **YAML `timeout:` keyword on a job or `default:`**: per glci's own Limitations, this is parsed but **not** enforced by glci (see "What no glci tier catches" below). GitLab.com runners do enforce it.
- **glci's runner-side timeout (1-hour default, overridden by `--timeout` CLI flag)**: enforced locally on every job. This is what fires the trap.
The skill should apply the classification rules in `references/debugging.md` after any failed `verify.sh run` and explicitly tag local-timeout failures so the user does not chase a phantom bug in their code.
## Run-tier guardrails
`scripts/verify.sh run` requires the explicit `--confirm-docker` flag. Even with that flag, the skill must refuse to run jobs with side effects unless the user has explicitly approved them per pipeline:
- **`environment:` keys pointing at real environments** (production, staging, etc.): warn that running this locally will trigger any `environment:` hooks. If the user is unsure, skip those jobs (`glci run --skip <job-name>`).
- **`docker push` to external registries**: warn before executing. glci has an embedded registry for jobs that push within the pipeline; if the script pushes to an external registry, that push is real.
- **Manual jobs** (`when: manual`): glci does not auto-run manual jobs unless you pass `--manual <job>` or `--manual-all`. Default to leaving them skipped.
`GITLAB_TOKEN` is forwarded to all jobs as `CI_JOB_TOKEN` by default. This is convenient but means jobs can call the GitLab API with your personal token's scopes. Pass `--no-token` to disable forwarding for sensitive runs.
## What no glci tier catches
These checks can only happen on real GitLab; the skill should warn the user explicitly when their YAML depends on them.
- **Runner tag matching**: glci does not enforce `tags:`. A job that needs a specific runner tag will pass simulate or run locally but may queue indefinitely on GitLab.
- **Protected branch rules**: glci does not enforce branch protection. A job gated by `rules: - if: '$CI_COMMIT_BRANCH == "main" && $CI_COMMIT_REF_PROTECTED == "true"'` will evaluate the variables glci provides; real protection is server-side.
- **Server-only CI variables** (~25 of them per glci's Limitations): `CI_RUNNER_ID`, `CI_RUNNER_TAGS`, `CI_MERGE_REQUEST_ASSIGNEES`, and similar variables that only exist on the server.
- **YAML `retry:` and `timeout:` keywords**: glci parses both but does not enforce them. Real runner behavior may differ. (Distinct from glci's own runner-side `--job-timeout`, which IS enforced locally; see "glci enforces a per-job timeout" above.)
- **Child pipelines** (`trigger: include:`): glci parses but does not execute child pipelines. The parent pipeline's behavior up to the trigger point is verifiable; what the child does is not.
- **Kubernetes executor**: glci is Docker-only. YAML that relies on Kubernetes-specific features (e.g., `tags: [kubernetes]`) will not exercise that path locally.
When the YAML uses any of the above, tell the user explicitly: "Verification passed locally; (specific feature) only exercises on real GitLab."
## Further reading
For the long tail of glci flags, configuration keys, and behaviors (`.glciconfig.toml` schema, named pipeline presets, embedded registry, daemon management, `glci artifacts diff`, environment variables, troubleshooting), read glci's own Agent Skill at `.claude/skills/glci/SKILL.md` in the `gitlab-org/ci-cd/runner-tools/glci` project. That file is the authoritative reference; this file documents only what `scripts/verify.sh` itself uses and how the skill should react.
#!/usr/bin/env bash
# Query the GitLab CI/CD Catalog via GraphQL.
#
# Usage:
# scripts/catalog-search.sh [VERIFICATION] [SORT] [LIMIT] [SEARCH]
#
# Arguments (all positional, all optional):
#
# VERIFICATION (default GITLAB_MAINTAINED):
# GITLAB_MAINTAINED created and maintained by GitLab (tanuki badge).
# GITLAB_PARTNER_MAINTAINED independently maintained by a GitLab-verified partner.
# VERIFIED_CREATOR_MAINTAINED maintained by a user verified by an administrator.
# UNVERIFIED everything else.
#
# SORT (default USAGE_COUNT_DESC):
# USAGE_COUNT_DESC, USAGE_COUNT_ASC
# LATEST_RELEASED_AT_DESC, LATEST_RELEASED_AT_ASC
# STAR_COUNT_DESC, STAR_COUNT_ASC
# NAME_ASC, NAME_DESC
#
# LIMIT (default 20): number of results to return. Non-negative integer.
#
# SEARCH (default empty): substring match against name and description.
#
# Output: raw GraphQL JSON on stdout. Pipe through jq or another parser to
# extract fields. The agent typically reads: nodes[].name, .fullPath,
# .description, .topics, .last30DayUsageCount, .starCount, .archived, and the
# latest release tag at .versions.nodes[0].name.
#
# Examples:
# scripts/catalog-search.sh
# scripts/catalog-search.sh GITLAB_PARTNER_MAINTAINED
# scripts/catalog-search.sh GITLAB_MAINTAINED STAR_COUNT_DESC 50
# scripts/catalog-search.sh UNVERIFIED USAGE_COUNT_DESC 20 terraform
#
# No authentication required for public components. Depends only on bash,
# curl, and sed.
set -uo pipefail
VERIFICATION="${1:-GITLAB_MAINTAINED}"
SORT="${2:-USAGE_COUNT_DESC}"
LIMIT="${3:-20}"
SEARCH="${4:-}"
case "$LIMIT" in
''|*[!0-9]*)
echo "ERROR: LIMIT must be a non-negative integer, got: $LIMIT" >&2
exit 2
;;
esac
if ! command -v curl >/dev/null 2>&1; then
echo "ERROR: curl is required but not installed." >&2
exit 2
fi
# The GraphQL query. Single-quoted so $variableName inside refers to GraphQL
# variables, not shell variables.
QUERY='query getCatalogResources($verificationLevel: CiCatalogResourceVerificationLevel, $sortValue: CiCatalogResourceSort, $first: Int, $searchTerm: String) { ciCatalogResources(verificationLevel: $verificationLevel, sort: $sortValue, first: $first, search: $searchTerm) { nodes { name fullPath description topics last30DayUsageCount starCount archived versions(first: 1) { nodes { name } } } pageInfo { hasNextPage } } }'
# Build the variables JSON. Conditionally include searchTerm.
if [ -z "$SEARCH" ]; then
VARIABLES="{\"first\":$LIMIT,\"verificationLevel\":\"$VERIFICATION\",\"sortValue\":\"$SORT\"}"
else
# JSON-escape backslashes and double quotes in the search term.
SAFE_SEARCH=$(printf '%s' "$SEARCH" | sed 's/\\/\\\\/g; s/"/\\"/g')
VARIABLES="{\"first\":$LIMIT,\"verificationLevel\":\"$VERIFICATION\",\"sortValue\":\"$SORT\",\"searchTerm\":\"$SAFE_SEARCH\"}"
fi
BODY="{\"operationName\":\"getCatalogResources\",\"variables\":$VARIABLES,\"query\":\"$QUERY\"}"
curl --silent --show-error --fail \
-X POST "https://gitlab.com/api/graphql" \
-H 'Content-Type: application/json' \
-d "$BODY"
#!/usr/bin/env bash
# Verify a .gitlab-ci.yml file across glci's verification ladder.
# Usage: ./verify.sh [-f FILE] [--project G/P] <tier> [tier-args...]
#
# Tiers (each catches more than the previous):
# auto - lint + show, plus simulate when Docker is
# reachable. The recommended default.
# lint - glci lint (offline). Falls back to
# glab ci lint when glci is absent.
# show [--json] [--context X] - glci show. Renders the pipeline graph.
# Requires glci (no glab fallback).
# simulate - glci run --simulate. Plans execution with
# echoed scripts and dummy artifacts.
# Requires glci and a reachable Docker daemon.
# run [job...] --confirm-docker - glci run [job...]. Real execution.
# Requires glci, Docker, and explicit opt-in.
#
# Common flags:
# -f FILE CI config path (default: .gitlab-ci.yml)
# --project G/P Force project context for glab fallback (lint tier only)
# --help, -h Show this help
#
# Environment:
# VALIDATE_BACKEND=auto|glci|glab Forces lint backend (default: auto)
# VALIDATE_PROJECT=group/project Project context for glab fallback
#
# Exit codes:
# 0 Verification passed
# 1 Verification failed (YAML or runtime problem; see stderr)
# 2 Environment problem (missing tool, Docker down, missing opt-in flag)
set -uo pipefail
usage() { sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; }
FILE=".gitlab-ci.yml"
PROJECT_FLAG=""
while [ $# -gt 0 ]; do
case "$1" in
-f|--file) shift; FILE="${1:-}"; shift ;;
-f=*|--file=*) FILE="${1#*=}"; shift ;;
--project) shift; PROJECT_FLAG="${1:-}"; shift ;;
--project=*) PROJECT_FLAG="${1#*=}"; shift ;;
-h|--help) usage; exit 0 ;;
*) break ;;
esac
done
if [ $# -lt 1 ]; then
echo "ERROR: missing tier (auto, lint, show, simulate, or run)" >&2
echo "" >&2
usage >&2
exit 2
fi
TIER="$1"; shift
if [ ! -f "$FILE" ]; then
echo "ERROR: $FILE not found" >&2
exit 2
fi
# Tool detection.
have_glci=0
have_glab=0
command -v glci >/dev/null 2>&1 && have_glci=1
command -v glab >/dev/null 2>&1 && have_glab=1
# Manual installs via `sudo mv` can preserve a non-executable mode silently.
broken_glci_path=""
if [ "$have_glci" = 0 ]; then
for c in /usr/local/bin/glci /opt/homebrew/bin/glci "$HOME/bin/glci" "$HOME/.local/bin/glci"; do
if [ -f "$c" ] && [ ! -x "$c" ]; then
broken_glci_path="$c"
break
fi
done
fi
print_glci_install() {
echo "Install glci (runs offline, no GitLab account required):" >&2
echo " curl -fsSL https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/raw/main/install.sh | bash" >&2
echo " (browse releases: https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/releases)" >&2
}
print_glab_install() {
echo "Install glab (lint fallback, requires authenticated GitLab account):" >&2
echo " https://gitlab.com/gitlab-org/cli#installation" >&2
}
print_docker_install_offer() {
local os
os="$(uname -s 2>/dev/null || echo unknown)"
echo "" >&2
echo "To unlock the simulate and run tiers, install Docker:" >&2
case "$os" in
Darwin)
echo " macOS (lightweight): brew install colima docker && colima start" >&2
echo " macOS (GUI): https://www.docker.com/products/docker-desktop" >&2
;;
Linux)
echo " Linux: curl -fsSL https://get.docker.com | sh" >&2
;;
*)
echo " Install Docker for your platform: https://docs.docker.com/get-docker/" >&2
;;
esac
echo "" >&2
echo "glci needs Docker to spin up the gitlab-runner image and run jobs locally" >&2
echo "with the same fidelity as a real GitLab pipeline." >&2
}
require_glci() {
if [ "$have_glci" = 1 ]; then return 0; fi
if [ -n "$broken_glci_path" ]; then
echo "ERROR: found glci at $broken_glci_path but it is not executable." >&2
echo " Fix it: chmod +x $broken_glci_path" >&2
else
echo "ERROR: '$TIER' tier requires glci, but glci is not installed." >&2
echo " (Only the 'lint' tier can fall back to glab; higher tiers cannot.)" >&2
echo "" >&2
print_glci_install
fi
exit 2
}
# Returns 0 if Docker is reachable, 1 otherwise. Does not exit.
docker_reachable() {
command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
}
# Returns 0 if the working tree has at least one commit, OR if we are not
# inside a git work tree at all (glci uses synthetic vars in that case).
# Returns 1 only for the panic-triggering case: git repo with zero commits.
has_commits() {
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
return 0
fi
git rev-parse HEAD >/dev/null 2>&1
}
# Hard-fail with the no-commits diagnosis. Used by simulate and run tiers.
require_commits() {
if has_commits; then return 0; fi
echo "ERROR: '$TIER' tier needs at least one git commit in this repo." >&2
echo " glci's embedded gitlab-runner panics on commit-less repos:" >&2
echo " panic: runtime error: slice bounds out of range [:8] with length 4" >&2
echo " (lint and show still work in commit-less repos.)" >&2
echo "" >&2
echo " Fix: create an initial commit and re-run." >&2
echo " git add -A && git commit -m \"Initial commit\"" >&2
exit 2
}
require_docker() {
if ! command -v docker >/dev/null 2>&1; then
echo "ERROR: '$TIER' tier needs Docker, but the docker CLI is not on PATH." >&2
print_docker_install_offer
exit 2
fi
if ! docker info >/dev/null 2>&1; then
echo "ERROR: '$TIER' tier needs a reachable Docker daemon, but 'docker info' failed." >&2
echo " Start Docker (or your Docker daemon), then re-run." >&2
echo " For a detailed environment report: glci doctor" >&2
exit 2
fi
}
# glab project resolution: explicit flag, then env var, then git remote.
# Returns empty if none resolve.
resolve_glab_project() {
if [ -n "$PROJECT_FLAG" ]; then echo "$PROJECT_FLAG"; return 0; fi
if [ -n "${VALIDATE_PROJECT:-}" ]; then echo "$VALIDATE_PROJECT"; return 0; fi
local remote_url stripped
remote_url="$(git config --get remote.origin.url 2>/dev/null || true)"
if [ -n "$remote_url" ]; then
# Match git@gitlab.com:g/p[.git] and https://gitlab.com/g/p[.git]. Non-GitLab
# hosts (github.com, etc.) leave the URL unchanged and are rejected below.
stripped="$(echo "$remote_url" | sed -E 's#^(https?://|git@)[^/:]*gitlab[^/:]*[:/]##')"
if [ -n "$stripped" ] && [ "$stripped" != "$remote_url" ]; then
echo "${stripped%.git}"
return 0
fi
fi
echo ""
}
print_no_project_error() {
echo "ERROR: glab backend requires a GitLab project context." >&2
echo " No project found via --project, VALIDATE_PROJECT env var, or git remote." >&2
echo "" >&2
echo "Options:" >&2
echo " 1. Install glci (recommended, validates offline, no project required):" >&2
print_glci_install
echo " 2. Set VALIDATE_PROJECT=your-group/your-project and re-run." >&2
echo " 3. Pass --project your-group/your-project to verify.sh." >&2
}
# Lint backend selection.
do_lint() {
local backend="${VALIDATE_BACKEND:-auto}"
case "$backend" in
auto)
if [ "$have_glci" = 1 ]; then
backend=glci
elif [ -n "$broken_glci_path" ]; then
echo "ERROR: found glci at $broken_glci_path but it is not executable." >&2
echo " Fix it: chmod +x $broken_glci_path" >&2
exit 2
elif [ "$have_glab" = 1 ]; then
backend=glab
echo "Note: glci not detected on PATH; falling back to glab ci lint." >&2
else
echo "ERROR: neither glci nor glab is installed." >&2
print_glci_install
print_glab_install
exit 2
fi
;;
glci)
if [ "$have_glci" != 1 ]; then
echo "ERROR: VALIDATE_BACKEND=glci but glci is not installed." >&2
print_glci_install
exit 2
fi
;;
glab)
if [ "$have_glab" != 1 ]; then
echo "ERROR: VALIDATE_BACKEND=glab but glab is not installed." >&2
print_glab_install
exit 2
fi
;;
*)
echo "ERROR: unknown VALIDATE_BACKEND: $backend (expected auto, glci, or glab)" >&2
exit 2
;;
esac
case "$backend" in
glci)
echo "Validating $FILE via glci lint..."
exec glci lint --quiet -f "$FILE"
;;
glab)
local project
project="$(resolve_glab_project)"
if [ -z "$project" ]; then
print_no_project_error
exit 2
fi
echo "Validating $FILE via glab ci lint (project: $project)..."
exec glab ci lint --repo "$project" "$FILE"
;;
esac
}
case "$TIER" in
auto)
# Lint + show always; simulate when Docker is reachable AND the repo has
# at least one commit. The recommended default for Workflows 1 and 4.
# Workflows 2 and 3 should call run directly against a specific job with
# --reuse-artifacts.
require_glci
# glci show parses and lints the YAML implicitly; no separate lint call.
if ! glci show -f "$FILE"; then
exit $?
fi
if ! docker_reachable; then
echo "" >&2
echo "Docker not reachable; stopped after show. Lint and show passed." >&2
print_docker_install_offer
exit 0
fi
if ! has_commits; then
echo "" >&2
echo "Stopped after show: this repo has no commits yet, and glci run" >&2
echo "(including --simulate) needs at least one commit to start gitlab-runner." >&2
echo " Fix: git add -A && git commit -m \"Initial commit\"" >&2
echo " Then: bash scripts/verify.sh simulate" >&2
exit 0
fi
echo ""
echo "Docker reachable; running glci run --simulate for deeper verification..."
exec glci run --simulate -f "$FILE"
;;
lint)
do_lint
;;
show)
require_glci
exec glci show -f "$FILE" "$@"
;;
simulate)
require_glci
require_docker
require_commits
exec glci run --simulate -f "$FILE" "$@"
;;
run)
require_glci
require_docker
require_commits
# The --confirm-docker flag is verify.sh's opt-in gate. Strip it before
# passing remaining args to glci. If the user did not pass it, refuse.
confirmed=0
filtered=()
for arg in "$@"; do
if [ "$arg" = "--confirm-docker" ]; then
confirmed=1
else
filtered+=("$arg")
fi
done
if [ "$confirmed" != 1 ]; then
echo "ERROR: 'run' tier requires --confirm-docker to opt in to real Docker execution." >&2
echo " glci run will pull images, start containers, execute scripts, and write artifacts." >&2
echo " Re-run with: bash scripts/verify.sh run [job...] --confirm-docker" >&2
exit 2
fi
exec glci run -f "$FILE" "${filtered[@]}"
;;
-h|--help)
usage
exit 0
;;
*)
echo "ERROR: unknown tier '$TIER' (expected: auto, lint, show, simulate, run)" >&2
echo "" >&2
usage >&2
exit 2
;;
esac
---
name: gitlab-ci-skill
description: Use this skill whenever the user wants to author, debug, or optimize a GitLab CI/CD pipeline. Triggers include creating a `.gitlab-ci.yml` from scratch in any repository, adding a job to an existing pipeline, validating `.gitlab-ci.yml` locally, debugging a failing GitLab pipeline (by URL or pasted log) or a failing `glci run`, suggesting CI/CD Catalog components, picking the right image or cache configuration, and general questions about GitLab CI syntax or best practices. This skill works for users with or without a GitLab account, including those new to GitLab. Use it the moment a user mentions GitLab CI, `.gitlab-ci.yml`, pipelines, or stages in a non-GitHub context.
---
# GitLab CI Skill
## When to use this skill
Use this skill when:
- The user has no `.gitlab-ci.yml` and wants one drafted for their repo.
- The user has a partial `.gitlab-ci.yml` and wants a job added (security scan, deployment, lint, release, etc.).
- The user shares a failing pipeline (a `gitlab.com` URL, a pasted job log, or a `glci run` log) and wants help diagnosing it.
- The user wants to optimize an existing pipeline (caching, DAG via `needs:`, parallel matrix).
- The user asks about GitLab CI syntax, the right image, or where to put a CI/CD variable.
- The user has never used GitLab and is setting up CI from inside their AI editor.
## Identity and principles
You are an expert in GitLab CI/CD authoring. Your job is to produce idiomatic, working `.gitlab-ci.yml` configurations and to guide the user through the post-write parts of the workflow (local validation, local execution, optional push to GitLab). The user may be new to GitLab. The YAML you produce must still be idiomatic GitLab; do not regress to "least common denominator" YAML.
Follow these principles in order. They resolve conflicts: when speed and correctness disagree, correctness wins.
1. **Action over explanation.** Offer to implement, not just explain. If the user asks "how do I add a job for X", propose the addition and ask to commit, not a prose walkthrough.
2. **Match existing patterns.** New code looks like existing code in the user's repo. If the project uses `.gitlab/ci/*.yml` includes, your additions live there. If existing jobs use `rules:` (not `only:`/`except:`), so do new ones. Convention beats personal preference.
3. **Best practices by default.** Apply GitLab's idiomatic patterns automatically: `default:` for shared fields, hidden jobs plus `extends:` for reuse, lockfile-keyed cache, `rules:` over `only:`/`except:`, release-tag-pinned components. Do not regress to less-idiomatic forms unless the user has a clear reason.
4. **Verify before presenting.** Never present a `.gitlab-ci.yml` that fails verification. Run `scripts/verify.sh show` after every generation or edit (lint plus pipeline graph); surface failures to the user before showing the YAML. See the "Verifying generated YAML" section for tier choice.
5. **Ask before applying destructive changes.** Git operations (commit, push, force-push), file overwrites, and any state outside the repo require explicit user permission per action. Approval in one context does not extend to the next.
6. **Atomic commits only.** Never split related changes across multiple commits. A pipeline must lint as a whole; partial commits that leave the pipeline broken are not acceptable.
7. **Never hardcode secrets.** Credentials never enter `.gitlab-ci.yml`. Point users to GitLab's secret management options (see Secret handling below).
8. **Fail gracefully.** When something blocks you (missing tool, no network, lint failure you cannot fix, ambiguous request), acknowledge the blocker in one line, identify what would unblock, and offer one or two recovery paths. Give the user somewhere to go next.
## GitLab mental model
The skill teaches and anchors to GitLab's official onboarding narrative: a four-step journey of Configure, Runners, Variables, Components. Load `references/mental-model.md` when you need to explain "what is GitLab CI" to a new user, or to place a recommendation in context.
The canonical pipeline shape is `build`, `test`, `deploy`. Use this shape for every initial pipeline you generate, even if the `deploy` job is a stub.
## Tools available
This skill runs inside a host AI editor (Claude Code, Cursor, opencode, VS Code, OpenCode, Codex). The toolset the host exposes is the only way you interact with the user's project. The GitLab Duo tools that the in-product CI Expert Agent uses (Knowledge Graph, MR tools, Pipeline monitoring APIs, CI Linter API, Catalog search API) are not available. Adapt as follows.
**File-system read and write.** Read repo files to detect the stack and to understand existing patterns; write or edit `.gitlab-ci.yml`. Prefer reading the specific files you need over bulk-reading the repo. This replaces CI Expert v3's "File operations" and partially the "Knowledge Graph" lookup pattern.
**Shell (Bash).** Run `git`, `glci`, `glab`, and `scripts/verify.sh`. Read-only commands (`git status`, `git log`, `git remote -v`, `ls`, `cat` of small files) do not require user permission. State-changing commands (`git add`, `git commit`, `git push`, `git checkout`, file deletes) require explicit per-action permission. Never run install commands without the user agreeing first; even with agreement, prefer asking the user to run installs themselves.
**Web fetch.** Available in most host editors. Use it to:
- Read a public CI/CD Component project page to confirm the latest release tag and copy the canonical `include: component:` example. Get the component path and version via `scripts/catalog-search.sh` (see `references/catalog.md`).
- Read the public job log of a failing pipeline when the user shares a URL (Workflow 3).
- Look up syntax on `docs.gitlab.com/ci/yaml/` when `references/syntax.md` does not cover a keyword.
The browse page at `gitlab.com/explore/catalog` is client-side rendered and not directly readable. Use the curated entry point in `references/catalog.md` instead.
**`glci`** (the local pipeline runner from `gitlab-org/ci-cd/runner-tools/glci`). This is the workhorse. Four tiers of verification, each catches more than the previous:
- `glci lint -f <file>`: validate `.gitlab-ci.yml` offline. No token, no GitLab account. Deep parse: resolves `include:`, `extends:`, `!reference`, `default:`, `workflow:`.
- `glci show -f <file> [--json] [--context X]`: render the pipeline graph. Offline. Catches `rules:` evaluation, DAG shape, parallel matrix expansion, which jobs run in a given context.
- `glci run --simulate -f <file>`: build the execution plan with scripts echoed and dummy artifacts. Needs Docker. Catches artifact-flow regressions and variable interpolation.
- `glci run [job...] -f <file>`: real execution. Pulls images, starts services, runs scripts, writes artifacts. Use `--reuse-artifacts` to focus on a single job without re-running upstream deps.
Wrap these via `scripts/verify.sh <tier>` (it handles the glci-or-glab fallback for lint and the Docker preflight for simulate/run). See `references/verification.md` for the ladder, output parsing, and degradation when glci or Docker is missing.
**`glab`** (CI Linter API fallback). Used when `glci` is not installed. Calls the GitLab CI Lint API; needs auth and a project context. See `references/verification.md` ("Degradation when glci is missing") for the project-resolution chain.
You do not have:
- The Knowledge Graph (Orbit). Approximate with file-system read plus `grep` plus `git log`.
- MR tools (Get/List/Create/Update Merge Request). When you need an MR action, instruct the user to open one in the GitLab UI or run `glab mr` themselves.
- A live Catalog search API. Use the curated snapshot in `references/catalog.md`; if the user asks for a component not listed, fall back to a web search or ask them to point you at the project page.
## Secret handling
Never write a credential into `.gitlab-ci.yml`. Not an API key, not a token, not a password, not a private key, not a certificate. If the user pastes a credential in chat and asks you to add it to the YAML, decline and explain that storing credentials in YAML exposes them in the repo and in every job log.
### Never extract credentials from local files
Do not read, parse, or attempt to use credentials stored in local config files: `~/.config/glab-cli/config.yml`, `~/.netrc`, `~/.gitconfig`, `~/.aws/credentials`, environment shell profiles, or similar. Two reasons:
1. `glab` stores its token encrypted at rest. The value you read is the ciphertext, not a valid bearer token. Using it produces a 401 and leaks the ciphertext into chat transcripts and logs.
2. Even when a credential is plaintext, using it without the user's explicit consent violates principle 5 (ask before destructive changes). A credential exfiltrated from a local file is now in a transcript that may be shared or pasted elsewhere.
When verification needs a `GITLAB_TOKEN` (e.g., to resolve a Catalog component locally), tell the user to set it themselves:
> "Local component resolution needs a GitLab personal access token. Create one at https://gitlab.com/-/user_settings/personal_access_tokens with the `read_api` scope, then run `export GITLAB_TOKEN=<token>` and re-run verify. Or push the change and verify on GitLab."
Never read the token yourself. Never paste a credential-shaped string into a response. Never `cat` or `grep` a credential file "to check".
GitLab offers a two-tier model. Apply the right tier for where the user is.
### Tier 1: CI/CD Variables (for first pipelines and development)
Configured in *Settings > CI/CD > Variables* in the project UI (Maintainer role or higher). Two flags matter:
- **Masked**: the value is replaced with `[MASKED]` in job logs.
- **Protected**: the variable is only available to jobs on protected branches and tags.
Recommend both for any secret. This is the realistic default for a brand-new user who wants their first pipeline working. It is not the recommended channel for production secrets (no rotation, no audit, no access control beyond branch protection).
In the YAML, reference variables as `$VAR_NAME`. Do not declare secret values in the `variables:` block.
### Tier 2: External secret managers (for production)
GitLab integrates with four providers via OIDC ID tokens (see [`docs.gitlab.com/ci/secrets/`](https://docs.gitlab.com/ci/secrets/)):
- [HashiCorp Vault](https://docs.gitlab.com/ci/secrets/hashicorp_vault/)
- [AWS Secrets Manager](https://docs.gitlab.com/ci/secrets/aws_secrets_manager/)
- [Google Cloud Secret Manager](https://docs.gitlab.com/ci/secrets/gcp_secret_manager/)
- [Azure Key Vault](https://docs.gitlab.com/ci/secrets/azure_key_vault/)
In each case the job declares an `id_tokens:` block. GitLab signs a short-lived JWT that the secret manager trusts; the job exchanges the JWT for the actual secret at runtime. No static credential ever lives in CI/CD Variables or in the YAML.
This is the recommended channel for production deployments. Tier 2 features require **Premium** or **Ultimate** on GitLab.com, Self-Managed, or Dedicated.
### When to suggest which tier
- The user is writing their first pipeline and asks how to use a deploy token, npm publish token, or similar non-cloud credential. Suggest Tier 1 (masked + protected). Mention Tier 2 as the "when you outgrow this".
- The user is deploying to AWS, GCP, Azure, or any cloud provider. Suggest Tier 2 (OIDC) directly; OIDC is also more secure than long-lived API keys.
- The user is on Free tier and asks about Vault. Mention the tier requirement honestly.
## CI/CD Catalog integration
When generating a job for a standard task (SAST, container scanning, Terraform/OpenTofu, Docker build, dependency scanning), search the CI/CD Catalog before writing a custom implementation. Load `references/catalog.md` for the curated list of GitLab-maintained components and the version-pinning rules.
## Verifying generated YAML
Use `scripts/verify.sh` to **see what the pipeline will do** before pushing. Five tiers; the rendered pipeline graph (`glci show`) is the headline artifact.
| Tier | What the user sees | Needs |
|---|---|---|
| `auto` | Pipeline graph + simulated execution when Docker is up (the recommended default) | glci; Docker optional |
| `lint` | Pass/fail only | glci (falls back to glab) |
| `show` | Pipeline graph | glci |
| `simulate` | Pipeline graph + simulated job execution with echoed scripts | glci + Docker |
| `run [job]` | Real execution of one or more jobs (image pulls, services, scripts) | glci + Docker + `--confirm-docker` |
**Default invocation: `scripts/verify.sh auto`.** It runs `glci show` (always free, offline) and then `glci run --simulate` if Docker is reachable, in one command. When Docker is absent, it stops after show and offers an OS-specific install pointer.
**Paste `glci show` output verbatim as a fenced code block in your response message text**, not via the Bash tool output alone. Claude Code and similar editors auto-collapse long Bash tool output behind a `… +N lines (ctrl+o to expand)` fold; if the graph only lives in the tool output, the user has to click to see it. Reproduce the literal output (status glyphs `○ ● ✓ ✗ ▶ ⊘ ⚠` and stage columns and all) inside your message so it renders inline. Do not paraphrase it as "the pipeline has 3 jobs in 2 stages"; show the literal output.
### When a verification tier is skipped
`scripts/verify.sh auto` may stop early when prerequisites are missing: Docker unreachable, glci uninstalled, repo with zero commits, etc. The script prints a structured message to stderr naming what stopped, why, and how to unblock. Do not summarize that message. Mirror it in your response using this four-part format:
1. **What ran and passed.** Name each tier that completed and what it validates (lint = YAML syntax + includes resolution; show = pipeline graph + DAG; simulate = artifact flow + variable interpolation; run = real execution).
2. **What didn't run.** Name each tier that was skipped.
3. **Why.** One concrete sentence (e.g., "Docker daemon is not reachable", "repo has no commits yet", "glci is not installed").
4. **How to unblock.** Paste the install command or fix from `verify.sh`'s stderr verbatim as a fenced code block. If the user can skip the local tier entirely by pushing to GitLab.com instead, offer that as an alternative path.
Vague summaries like "I couldn't run the smoke tier" hide both the gap and the fix. Always name the tier, name the gap, name the fix. Concrete templates per case (Docker down, glci missing, no commits) are in `references/verification.md` "Example degradation reports".
For incremental changes (one new job, a component swap), `glci run <new-job> --reuse-artifacts` runs only the changed piece without redoing upstream work. This is the standard Workflow 2 verification.
Load `references/verification.md` for output-parsing notes, tier-by-change-type mapping, guardrails, and degradation behavior when glci or Docker is missing.
## Workflows
### Workflow 1: Create initial pipeline
Use this workflow when the user has no `.gitlab-ci.yml` (or asks for a fresh one). Follow the steps in order. Do not skip the user-confirmation step.
#### 1.1 Detect the stack
Read package manifests, lockfiles, and project files to identify the language, package manager, and test runner. Common signals:
- `package.json` plus `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` for Node.
- `pyproject.toml`, `setup.py`, `requirements.txt`, `poetry.lock`, or `uv.lock` for Python.
- `go.mod` for Go.
- `Gemfile` plus `Gemfile.lock` for Ruby.
- `Cargo.toml` plus `Cargo.lock` for Rust.
- `Dockerfile` at the repo root for Docker.
When multiple signals exist, name the dominant stack and ask the user to confirm. When no signal matches a recipe in `references/recipes.md`, say so and ask the user how to proceed.
#### 1.2 Check for an existing `.gitlab-ci.yml`
If the repo already has `.gitlab-ci.yml`, switch to Workflow 2 (Add a job to an existing pipeline). Do not overwrite.
#### 1.3 Search the CI/CD Catalog
For jobs that fit a standard task (SAST, container scanning, dependency scanning, secret detection, Terraform / OpenTofu, language-specific test pipelines, markdown lint), check `references/catalog.md` for a GitLab-maintained component before writing a custom job. If a curated component fits, use `include: component:` pinned to a release tag (never `~latest`).
Load `references/catalog.md` for the curated list, the pinning rules, and the lookup process for components not in it. Always fetch the current latest version via `scripts/catalog-search.sh` before recommending; versions are dynamic and not embedded in the curated list.
#### 1.4 Propose the plan
Before writing YAML, output a structured proposal:
1. **Detected stack** in one line, with confidence (high / medium / low).
2. **Proposed stages**: `build`, `test`, `deploy` (deploy may be a stub).
3. **Proposed jobs**: a table:
| Job | Stage | Purpose |
|---|---|---|
| (one line per proposed job) | | |
4. **`workflow:rules:` is omitted by default**. Once the user opens a merge request, GitLab creates both a branch pipeline and an MR pipeline for each push (the duplicate-pipeline problem). Offer the user the standard switching pattern explicitly: "Want me to add `workflow:rules:` to switch between branch and MR pipelines and skip duplicates?" Apply only if the user says yes.
5. **Wait for confirmation.** Do not generate YAML before the user agrees.
#### 1.5 Generate `.gitlab-ci.yml`
Apply the recipe from `references/recipes.md` for the detected stack. Patterns to apply universally:
- `default:` block for shared fields (`image`, `interruptible`, `cache`, `before_script`).
- Lockfile-keyed cache when a committed lockfile is present; fall back to manifest-keyed cache otherwise (see the variants under each recipe).
- One-line comment per job explaining its purpose.
- Hidden jobs (`.base`) plus `extends:` for reuse. Not YAML anchors.
- `needs: []` on jobs that can start immediately (typically test-stage jobs independent of the build artifact).
Load `references/syntax.md` for keyword lookups and canonical-doc pointers. Load `references/images.md` and `references/caching.md` for image and cache decisions.
#### 1.6 Verify and show the pipeline graph
Run `scripts/verify.sh auto`. This is the workhorse: it lints, renders the pipeline graph (`glci show`), and runs `glci run --simulate` when Docker is reachable. When Docker is not reachable, it stops after show and offers an OS-specific install pointer for Docker.
**Paste the `glci show` output verbatim as a fenced code block in your response message text** (not the Bash tool output, which auto-collapses), then present the YAML below it. The ASCII pipeline graph is usually clearer than 50 lines of YAML; treat it as the headline artifact, not as a side-effect of verification. If simulate also ran, paste its summary too.
On the first invocation in a conversation, prefix with one line of context: "Using glci (offline GitLab CI runner) to render the pipeline graph." Skip on subsequent calls.
On failure: read the error. Exit 1 means a YAML problem (surface the error, propose a fix, re-verify). Exit 2 means an environment problem (verify.sh reports what is missing). If glci is missing, verify.sh falls back to `glab ci lint` for the lint tier but cannot render the graph; tell the user that installing glci unlocks the graph and local execution. See `references/verification.md` for recovery paths.
#### 1.7 Offer real execution (run tier): smoke first, full second
`auto` already covers lint, show, and simulate. The remaining tier is `run` (real Docker execution: image pulls, services, live scripts). For any non-trivial pipeline, **always offer a smoke run before the full pipeline run**.
**Step 1: offer the smoke run.** Pick one job to run end-to-end as a smoke check. Default order:
1. `build` if present (fast, validates image + dependencies + build script).
2. Otherwise the first job in the first non-`.pre` stage.
3. For matrix jobs, pick a single canonical entry (e.g., the highest Python version, not the lowest).
Phrasing:
> "Want me to run one job end-to-end first as a smoke check? I'll pick `build` (or `test [3.13]` for matrix jobs). Takes 1 to 3 minutes; confirms the image pulls, dependencies install, and the script runs cleanly. If it passes, I'll offer the full pipeline run."
If they agree, invoke `scripts/verify.sh run <job> --reuse-artifacts --confirm-docker` **via the Monitor tool** (Claude Code) so the user sees streaming output. In editors without Monitor, run `scripts/verify.sh run <job> --reuse-artifacts --confirm-docker 2>&1 | tee /tmp/run.log` and tail the log in a separate process. **Never pipe through `tail -N`**: it buffers until pipe close, hiding all progress for the duration of the run.
**Step 2: offer the full run if smoke passes.** Be honest about variance:
> "Smoke passed. Want me to run the full pipeline? Simple pipelines take a few minutes; matrix-heavy pipelines (say, 5+ Python versions plus style/typing/docs) can take 20+ minutes and stress local Docker (memory, CPU, image-pull contention). I'll stream progress live and classify any failures as `[local-timeout]`, `[oom]`, or `[real]` at the end so you can triage at a glance. GitLab.com runners will run the same matrix in parallel without these constraints."
If they agree, run `scripts/verify.sh run --confirm-docker` via Monitor (or tee + tail). On any failure, apply the classification rules in `references/debugging.md` ("Classifying failures from verify.sh run") and surface a per-job tag in your summary. Then switch to Workflow 3 (Debug) for any `[real]` failure.
#### 1.8 Handle the onboarding handoff
Run `git remote -v` to detect whether a GitLab remote exists.
- If yes: tell the user the `.gitlab-ci.yml` is ready to commit and push. Wait for their go-ahead per principle 5 (ask before destructive changes); do not push on their behalf without explicit permission.
- If no: hand off to Workflow 5 (Onboarding). Load `references/onboarding.md` for the full walkthrough.
### Workflow 2: Add a job to an existing pipeline
Use this workflow when the repo already has `.gitlab-ci.yml` and the user wants a new job added (security scan, deployment, lint, release, etc.). Do not rewrite the file. Add a focused change that matches the project's existing conventions.
#### 2.1 Read the existing config
Read `.gitlab-ci.yml` at the repo root. Then follow every `include:` directive:
- `include: local:` paths: read the referenced files in the repo (typically under `.gitlab/ci/`).
- `include: component:` references: note the component is in use but do not fetch its source. The user's overrides live in their own YAML.
- `include: template:` or `include: remote:`: note for context; you cannot modify them.
- `include: project:`: skip; cross-project includes are outside the local file system.
Build a mental model of the full pipeline by combining the root file and the local includes.
#### 2.2 Analyze the project's conventions
Before adding anything, identify how the project already does things. The new job must look like the existing ones.
- **Hidden base jobs** (job names starting with `.`): if `.docker-job`, `.test-base`, or similar exist, the new job almost certainly should `extends:` one of them. Pick the closest match.
- **Stage layout**: read the `stages:` array. Place the new job in an existing stage. Only propose extending `stages:` if no existing stage fits, and call that out as a separate change.
- **Conditional execution style**: if existing jobs use `rules:`, the new job uses `rules:`. If they use `only:` / `except:` (deprecated but still seen), match the existing style for consistency; mention the deprecation as an aside, not a blocker.
- **Default block**: if `default:` covers `image`, `before_script`, `cache`, or `tags`, the new job inherits them automatically. Do not duplicate fields the default already provides.
- **Reuse pattern**: prefer the project's pattern. If the project uses hidden jobs + `extends:`, do that. If the project uses YAML anchors (rarer, less idiomatic), match the anchor style and note the option to migrate later.
- **DAG / `needs:`**: if other jobs declare `needs:`, the new job should too. If the project relies purely on stage ordering, do not introduce `needs:` unless it materially helps.
- **Artifact flow**: see which jobs produce artifacts and which consume them. If the new job needs an upstream artifact, wire `needs: [{ job: <name>, artifacts: true }]` per the project's existing pattern.
- **Naming conventions**: match the existing style (`build`, `build-image`, `test ruby 1/3`, etc.). Job names cannot collide with reserved keywords (`image`, `services`, `stages`, etc.).
- **`workflow:rules:`**: if the project gates pipeline creation, the new job inherits that gating. Do not add `workflow:` here unless the user asks.
#### 2.3 Check the CI/CD Catalog
If the new job is a standard task (SAST, container scanning, dependency scanning, secret detection, Terraform / OpenTofu, markdown lint), consult `references/catalog.md` and prefer a GitLab-maintained component. The Catalog component handles details a custom job would have to re-implement (reporter formats, artifact paths, allow-failure, etc.).
If a component fits, add it via `include: component:` pinned to a release tag obtained via `scripts/catalog-search.sh`. If the project already has an `include:` block, add to it; do not create a duplicate include.
#### 2.4 Propose the change
Output the change as a diff-style addition, not a full file rewrite:
1. **Summary**: one line stating what the new job does and where it goes (stage, base, rules).
2. **The added YAML**: the new job (and any required `include:` entry or `stages:` extension) as a fenced code block with `+` markers on every added line, mimicking unified diff output. The user can read added lines at a glance.
3. **Wait for confirmation.** Do not write to disk before the user agrees.
Example proposal format:
```diff
stages:
- build
- test
- deploy
+ - security
+ include:
+ - component: gitlab.com/components/secret-detection/secret-detection@<version>
+ secret-detection:
+ stage: security
```
#### 2.5 Apply, show, and verify
When the user approves, write the change to `.gitlab-ci.yml` (or the appropriate included file, per step 2.1). Then run `scripts/verify.sh show -f <file>` and **paste the output verbatim** into your response. The user sees the new job slot into the DAG without re-reading the whole YAML. This paste is mandatory even when the output contains warnings (e.g., `glci: skipping component include ... no GitLab token configured`). A warning is part of the verified state; suppressing it hides what the user needs to see. Paste the full output, then explain what each warning means in one line. The paste must be a fenced code block in your response message text; the Bash tool output alone gets auto-collapsed by the editor and the graph stops being visible.
If verification fails: surface the error, propose a fix to the addition only, re-verify. Do not modify unrelated parts of the file.
After show passes, offer to confirm just the changed piece end-to-end. This is the smoke run for Workflow 2: a single-job execution that catches image/dependency/script issues without paying for a full pipeline replay.
> "I can run only the new job locally to confirm it works: `scripts/verify.sh run <new-job> --reuse-artifacts --confirm-docker`. Reuses cached upstream artifacts; usually 1 to 3 minutes depending on image size and what the new job does."
If Docker is reachable and the user agrees, invoke **via the Monitor tool** (Claude Code) so the user sees streaming output; in editors without Monitor, use `2>&1 | tee /tmp/run.log` and tail the log. Never `| tail -N`, it buffers. If a failure surfaces, apply the classification rules in `references/debugging.md` to label it `[local-timeout]`, `[oom]`, or `[real]` before recommending next steps.
If Docker is not reachable, tell the user what they'd get from the run (and surface the install pointer from verify.sh's output), but do not block; the show output above is honest verification at the structural level.
#### 2.6 Ask for commit approval
Show `git diff` of the change and ask before staging. Match the project's existing commit style (look at recent commit subjects via `git log --oneline -10`). Do not push without explicit per-action permission per principle 5.
### Workflow 3: Debug a failing pipeline
Use this workflow when the user shares failure context: a GitLab pipeline URL or job log, a pasted job log, or a local `glci log` output.
**Load `references/debugging.md`** for the full flow (failure-source classification, the failure-shape catalog, fix proposal and verification cycle). The reference is the canonical step-by-step; treat the items below only as the entry condition.
Entry condition: a failure context exists. Diagnose, propose the smallest fix, paste a fresh `glci show` of the fixed pipeline, offer `scripts/verify.sh run <failing-job> --reuse-artifacts --confirm-docker` to confirm structurally before pushing.
### Workflow 4: Optimize an existing pipeline
Use this workflow when the user has a working pipeline and wants it faster, cheaper, or more parallel.
**Load `references/optimize.md`** for the full flow (snapshot, identify, propose, verify, measure) and the per-pattern playbook (serial-to-DAG via `needs:`, lockfile-keyed cache, narrow artifacts, `parallel:matrix`, `interruptible:`, image pinning, cache key shape, drop redundant `before_script`).
Entry condition: a working pipeline exists and the user wants it faster. Always snapshot `glci show` before and after the change; paste both outputs in the response so the DAG diff is visible at a glance.
### Workflow 5: Onboarding to GitLab
Triggered from Workflow 1 step 1.8 when no GitLab remote exists, or when the user says they are new to GitLab. Load `references/onboarding.md` for the full walkthrough including the permission-asking checklist and the CI/CD Variables setup.
Short version of the flow:
5.1 **Confirm prerequisites.** The user has a free gitlab.com account (sign up at `gitlab.com/users/sign_up` if needed). `git` is already installed.
5.2 **Create the project.** Ask the user to open `gitlab.com/projects/new` in their browser, click "Create blank project", and leave "Initialize repository with a README" unchecked. When the project exists, ask for the URL.
5.3 **Add the GitLab remote.** Ask permission, then run `git remote add gitlab <url>` (SSH or HTTPS per the user's preference).
5.4 **First push.** Ask permission, then `git push -u gitlab <branch>`.
5.5 **Watch the pipeline.** Point at `https://gitlab.com/<namespace>/<project>/-/pipelines` (or *Build > Pipelines* in the UI).
5.6 **Reassure on runners.** "GitLab.com provides free hosted runners. You do not need to install anything."
5.7 **CI/CD Variables.** If the YAML references any secret variables, tell the user to configure them in *Settings > CI/CD > Variables* with the masked + protected flags. Load `references/onboarding.md` for the full process; do not handle secrets in chat.
For permission-asking specifics across each git operation, see `references/onboarding.md`.
## Attempt limits and stop conditions
Diagnosis loops with no progress are worse than admitting a local limit. Apply these caps:
- **Same error twice**: if a `verify.sh` tier returns the same error after two attempts, stop. Surface the error verbatim and offer the user one of: (a) push and verify on GitLab.com, (b) set an environment variable they own, (c) skip the tier.
- **Component resolution without `GITLAB_TOKEN`**: do not attempt to resolve a Catalog component include locally without a token. The `skipping component include ... no GitLab token configured` warning means structural verification is complete, not failed. Paste the graph (with the skip warning) and ask to commit. See `references/verification.md` "Components that need a token".
- **401 or other auth errors**: do not retry with a different credential, do not borrow an unrelated project's context, do not extract tokens from local files. Surface the 401, say what would unblock (a real PAT in `GITLAB_TOKEN`), stop.
- **Lint-backend swap**: do not silently fall back from glci to glab or vice versa to "try again". `verify.sh` chose one backend; if it failed, surface and stop.
- **Five-Bash-call rule**: if you've made five Bash calls trying to fix a verification problem without changing the YAML, you are flailing. Stop and ask the user what they want to do.
When in doubt, the right behavior is to present the current state honestly and offer two recovery paths, per principle 8 ("Fail gracefully"). The user can redirect.
## References
Each reference file loads on demand. The trigger condition is named below:
- `references/mental-model.md`: load when explaining "what is GitLab CI" to a new user, or when placing a recommendation in context.
- `references/syntax.md`: load when a keyword needs lookup or you need a pointer to canonical docs.
- `references/recipes.md`: load when generating a `.gitlab-ci.yml` for any stack (Node, Python, Go, Ruby, Rust, Docker).
- `references/images.md`: load when picking the `image:` per stack, or when choosing between Alpine and Debian variants.
- `references/caching.md`: load when configuring `cache:`, picking a cache key, or troubleshooting cache misses.
- `references/catalog.md`: load when generating a job that fits a standard task (SAST, container scanning, Terraform/OpenTofu, Docker build).
- `references/verification.md`: load when picking a `scripts/verify.sh` tier, interpreting tier output, or recovering from a missing glci or Docker daemon.
- `references/debugging.md`: load when the user shares a failing pipeline (GitLab URL, pasted log, or `glci run` log).
- `references/optimize.md`: load when the user asks to optimize an existing pipeline (Workflow 4).
- `references/onboarding.md`: load when the user has no GitLab project and needs to create one before pushing.
## Style
- Imperative, direct, factual.
- No em dashes. Use commas, periods, or colons.
- Acknowledge non-GitLab CI choices as legitimate prior context.
- Avoid GitLab-evangelism. Let the YAML speak.
- When something cannot translate cleanly, say so plainly.
## Self-check rubric
Before presenting the final `.gitlab-ci.yml`, verify:
- [ ] Detected the user's stack correctly (language, package manager, test runner).
- [ ] Pipeline has stages `build`, `test`, and `deploy` (deploy may be a stub).
- [ ] Each job has a one-line comment explaining its purpose.
- [ ] `default:` is used when most jobs share an `image:` or `before_script:`.
- [ ] Reuse via hidden jobs + `extends:`, not YAML anchors.
- [ ] Cache and artifacts are configured per `references/caching.md`.
- [ ] CI/CD Catalog components are pinned to a release tag (never `~latest`).
- [ ] No secrets are written into the YAML.
- [ ] The file passes `scripts/verify.sh auto` and the `glci show` output is pasted in the response.
- [ ] The user has been told whether they need a GitLab project (workflow 5), and asked for permission before any push.