@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/claude/packs/integrations/skills/gitlab-ci-skill/references/catalog.md

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

package/assets/claude/packs/integrations/skills/gitlab-ci-skill/references/debugging.md

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

package/assets/claude/packs/integrations/skills/gitlab-ci-skill/references/images.md

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

package/assets/claude/packs/integrations/skills/gitlab-ci-skill/references/mental-model.md

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

package/assets/claude/packs/integrations/skills/gitlab-ci-skill/references/onboarding.md

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