@mthanh/vespercli 1.7.1 → 2.0.0

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/SKILL.md

@@ -0,0 +1,422 @@
+---
+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.

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/UPSTREAM.json

@@ -0,0 +1,7 @@
+{
+  "upstream": "https://gitlab.com/gitlab-org/ci-cd/gitlab-ci-skill",
+  "sha": "6ddc101995c2504c5743612920e0f0748d854dc3",
+  "retrieved": "2026-09-27",
+  "license": "MIT",
+  "path": "/"
+}

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/README.md

@@ -0,0 +1,70 @@
+# `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.

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/node-mocha/.gitlab-ci.yml

@@ -0,0 +1,55 @@
+# 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

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/node-mocha/README.md

@@ -0,0 +1,28 @@
+# 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).