feat(cli): .glint.yml config and inline suppression comments

Adds project-level configuration and per-job suppression directives:

.glint.yml (searched from pipeline dir up to the git root):
- ignore: [GL007, GL032] — suppress rules globally for the project
- severity: {GL004: warning} — override rule severity (error/warning/ignore)
- stages: [quality] — extra stages beyond the pipeline's stages: block
- token: / url: / cache_dir: — defaults for flags; lower priority than
  CLI flags and environment variables

Inline suppression (# glint: ignore):
- Place "# glint: ignore GL007" immediately before a job definition to
  suppress that rule for the specific job only
- Multiple rules: "# glint: ignore GL007, GL032" (comma or space separated)
- Wildcard: "# glint: ignore all" suppresses every finding for the job
- Suppressions are scoped to the annotated job; pipeline-level findings
  are unaffected
- Parsed from yaml.Node head/line comments in the first parse pass;
  stored in Pipeline.Suppressions (root file only, not includes)

New packages: internal/config (Load, walk-up search, .git boundary stop)
New files: cmd/glint/filter.go (applyConfig, isSuppressed helpers)
Tests: config_test.go, parser_suppress_test.go, filter_test.go
Validate fixtures: testdata/config_ignored/, config_severity/, config_suppress/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+
+jobs:
+  ci:
+    name: vet, staticcheck, test, build
+    runs-on: ubuntu-latest
+    container:
+      image: golang:1.26-alpine
+
+    steps:
+      - name: Install tools
+        run: apk add --no-cache git
+
+      - name: Checkout
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SERVER_URL: ${{ github.server_url }}
+          REPO: ${{ github.repository }}
+          REF: ${{ github.ref_name }}
+        run: |
+          git clone --depth 1 --branch "$REF" \
+            "$(echo "$SERVER_URL" | sed "s|https://|https://oauth2:${TOKEN}@|")/${REPO}.git" .
+
+      - name: vet
+        run: go vet ./...
+
+      - name: staticcheck
+        run: go tool staticcheck ./...
+
+      - name: test
+        run: go test ./...
+
+      - name: build
+        run: go build ./cmd/glint/...

.gitea/workflows/release.yml

@@ -0,0 +1,70 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    name: Build and publish release
+    runs-on: ubuntu-latest
+    container:
+      image: golang:1.26-alpine
+
+    steps:
+      - name: Install tools
+        run: apk add --no-cache curl git jq
+
+      - name: Checkout
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SERVER_URL: ${{ github.server_url }}
+          REPO: ${{ github.repository }}
+          REF: ${{ github.ref_name }}
+        run: |
+          git clone --depth 1 --branch "$REF" \
+            "$(echo "$SERVER_URL" | sed "s|https://|https://oauth2:${TOKEN}@|")/${REPO}.git" .
+
+      - name: Build Linux (amd64)
+        env:
+          GOOS: linux
+          GOARCH: amd64
+          CGO_ENABLED: "0"
+        run: |
+          go build -trimpath -ldflags="-s -w" \
+            -o glint-${{ github.ref_name }}-linux-amd64 \
+            ./cmd/glint/...
+
+      - name: Build Windows (amd64)
+        env:
+          GOOS: windows
+          GOARCH: amd64
+          CGO_ENABLED: "0"
+        run: |
+          go build -trimpath -ldflags="-s -w" \
+            -o glint-${{ github.ref_name }}.exe \
+            ./cmd/glint/...
+
+      - name: Create release and upload assets
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+          API_URL: ${{ github.api_url }}
+          REPO: ${{ github.repository }}
+        run: |
+          release_id=$(curl -sf -X POST \
+            -H "Authorization: token $TOKEN" \
+            -H "Content-Type: application/json" \
+            "$API_URL/repos/$REPO/releases" \
+            -d "{\"tag_name\":\"$TAG\",\"name\":\"$TAG\",\"draft\":false,\"prerelease\":false}" \
+            | jq -r .id)
+
+          for file in glint-${{ github.ref_name }}-linux-amd64 glint-${{ github.ref_name }}.exe; do
+            curl -sf -X POST \
+              -H "Authorization: token $TOKEN" \
+              -H "Content-Type: application/octet-stream" \
+              "$API_URL/repos/$REPO/releases/$release_id/assets?name=$file" \
+              --data-binary "@$file"
+            echo "uploaded: $file"
+          done

.gitignore

@@ -1,6 +1,6 @@
 # Compiled binaries
-glint
-glint.exe
+/glint
+/glint.exe
 dist/
 bin/
 

CHANGELOG.md

@@ -5,14 +5,178 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project uses [Semantic Versioning](https://semver.org).
 
-## [Unreleased]
+## [0.2.19] - 2026-06-14
 
 ### Added
 
-- **Cross-platform release builds** — two new Taskfile tasks for producing tagged release binaries:
+- **`.glint.yml` project config file** — glint now searches for a `.glint.yml` file starting from the pipeline file's directory and walking up to the first `.git` boundary. Supported keys:
+  - `ignore: [GL007, GL032]` — suppress rules globally for the project.
+  - `severity: {GL004: warning}` — override rule severity (`error`, `warning`, or `ignore`). `ignore` is equivalent to listing the rule in `ignore:`.
+  - `stages: [quality]` — declare extra stage names that are valid beyond those in the pipeline's own `stages:` block; jobs in these stages are not flagged by GL004.
+  - `token: glpat-xxx` — default GitLab personal access token (lower priority than the `--token` flag and `GITLAB_TOKEN` env var).
+  - `url: https://gitlab.example.com` — default GitLab instance URL.
+  - `cache_dir: ~/.cache/glint` — default cache directory for fetched remote includes.
+
+- **Inline suppression comments** — a `# glint: ignore RULE` comment placed immediately before a job definition suppresses that rule for the specific job. Multiple rules can be comma- or space-separated (`# glint: ignore GL007, GL032`). Use `# glint: ignore all` to suppress every finding for the job. Suppressions are scoped to the annotated job; pipeline-level findings are unaffected.
+
+## [0.2.18] - 2026-06-14
+
+### Added
+
+- **`--format json`** — `glint check` can now emit a structured JSON report instead of plain text. The schema (version `1`) includes `glint_version`, `pipeline`, a `findings` array (each finding has `rule`, `severity`, `file`, `line`, `job`, `message`), and a `summary` block (`total`, `errors`, `warnings`). An empty findings array is `[]`, not `null`. In this mode the human-readable summary line is written to stderr so stdout contains only the JSON payload.
+
+- **`--format sarif`** — emits a SARIF 2.1.0 JSON document (schema `https://json.schemastore.org/sarif-2.1.0.json`). The `runs[0].tool.driver` lists every unique rule ID found in findings; each `result` carries `ruleId`, `level` (`error`/`warning`), `message.text` (including the job name prefix), and `locations[0].physicalLocation` with `artifactLocation.uri` and `region.startLine` (when available). Pipeline-level findings without a file have no `locations` entry. This format is consumed natively by GitHub Code Scanning and GitLab SAST.
+
+- **`--format junit`** — emits a JUnit XML document compatible with CI test-report artifact parsers (GitLab: `artifacts:reports:junit`; GitHub: upload-artifact + test-reporter). Each finding becomes a `<testcase>` with a `<failure>` child whose `message` and `type` attributes carry the finding details. A clean pipeline produces a single passing `<testcase>` with no `<failure>` element.
+
+- **`--format github`** — emits GitHub Actions workflow-command annotation lines (`::error file=…,line=…,title=RULE::message` / `::warning …`). GitHub CI renders these as inline comments on the relevant file in pull requests. Pipeline-level findings without a file omit the `file=` parameter.
+
+- **Format validation** — an unknown `--format` value exits with code 2 and a helpful error message listing the valid formats.
+
+## [0.2.17] - 2026-06-14
+
+### Added
+
+- **Recursive include depth limit** — `resolveIncludes` now accepts a `depth` counter and returns a warning when the nesting depth exceeds 100 (matching GitLab's documented limit). This guards against pathologically deep include chains.
+
+- **Cycle detection for project and component includes** — `project:` and `component:` includes were not previously tracked in the `visited` map (only `local:` and `remote:` were). They are now registered before recursing into their sub-includes, preventing cross-file include cycles from causing infinite loops.
+
+- **`include: inputs:` substitution** — when a `component:` include entry has a `with:` block, all `$[[ inputs.KEY ]]` and `$[[ inputs.KEY | default('…') ]]` placeholders in the fetched template YAML are substituted with the corresponding values before parsing. Supported default value forms: `'single quoted'`, `"double quoted"`, bare booleans (`true`/`false`), and bare integers. Missing keys without a default become empty strings. This replaces the previous behaviour of leaving `$[[…]]` tokens in the YAML, which caused false-positive lint findings.
+
+- **Include cache (`--cache-dir`)** — pass `--cache-dir DIR` to `glint check` or `glint graph` to persist fetched remote templates (both `project:` and `component:` includes and `remote:` URLs) to a local directory. Cache entries are keyed by the SHA-256 of the full request coordinates (base URL + project + path + ref). The directory is created automatically on first use.
+
+- **Offline mode (`--offline`)** — pass `--offline` to skip all network calls. Remote includes not present in the cache are surfaced as warnings (same UX as "no token"). When `--offline` is set without an explicit `--cache-dir`, the default platform cache directory (`$XDG_CACHE_HOME/glint` or `~/.cache/glint`) is used automatically.
+
+## [0.2.16] - 2026-06-14
+
+### Added
+
+- **`services:` validation (GL034)** — the map form of a service entry requires a `name` key; emits an `ERROR` when absent. The optional `alias` field must be a valid DNS label (letters, digits, hyphens, and dots; must start and end with an alphanumeric character); invalid aliases emit an `ERROR`.
+
+- **`rules:changes` / `rules:exists` absolute path detection (GL035)** — emits a `WARNING` when a path in `rules:changes:` or `rules:exists:` starts with `/`. GitLab CI evaluates these paths relative to the repository root, so absolute paths can never match. Applies to both the list form and the `{paths: …}` map form.
+
+- **`timeout:` format validation (GL036)** — emits an `ERROR` when a job's `timeout:` (or the pipeline-level `default.timeout:`) is not a valid GitLab CI duration string. Valid formats: `30m`, `1h 30m`, `90 minutes`, `2 hours 30 minutes`, `1 day`, etc.
+
+- **`id_tokens:` `aud` validation (GL037)** — emits an `ERROR` for each OIDC token entry in `id_tokens:` that is missing the required `aud` key. GitLab returns an API error at pipeline start when `aud` is absent.
+
+- **`secrets:` provider validation (GL038)** — emits an `ERROR` for each secret entry in `secrets:` that does not declare a provider key (`vault`, `gcp_secret_manager`, or `azure_key_vault`).
+
+- **`pages:` keyword + `artifacts.paths` consistency (GL039)** — emits a `WARNING` when a job uses the `pages:` keyword but `artifacts.paths` does not include the publish directory (default `public`, or the value of `pages.publish`). GitLab Pages will not deploy unless the publish directory is listed as an artifact.
+
+- **Duplicate stage names (GL040)** — emits a `WARNING` when a stage name appears more than once in the top-level `stages:` list. GitLab silently merges duplicate stage entries, which can produce confusing pipeline ordering.
+
+- **`cache.key.files` glob detection (GL041)** — emits a `WARNING` when an entry in `cache.key.files` contains glob metacharacters (`*`, `?`, `[`). The `files` field requires exact file paths; GitLab does not expand globs there.
+
+## [0.2.15] - 2026-06-13
+
+### Added
+
+- **Static reachability check (GL033)** — warns when every rule in a job's `rules:` block has an explicit `when: never`, making the job permanently excluded from any pipeline run. This is a purely static claim: no matter which `if:` condition evaluates to true, the outcome is always "skip"; and if no rule matches, the implicit fallback is also skip. No expression evaluation or context is required. The finding is a `WARNING` (may be intentional as a "disabled job" pattern). Only jobs where every rule has the literal `when: never` value are flagged; rules with no `when:` (default `on_success`), `when: manual`, `when: always`, or `when: on_failure` are not.
+
+## [0.2.14] - 2026-06-13
+
+### Added
+
+- **`--version` / `-v` flag** — `glint --version`, `glint -v`, and `glint version` all print the compiled version string (e.g. `glint v0.2.14`). The version is also shown at the top of every `--help` output (global, `check --help`, `graph --help`). The version is injected at build time via `-ldflags "-X main.version=..."` using `git describe --tags --always --dirty`.
+
+- **Sorted findings output** — `Lint` now returns findings sorted by `(File, Line, Rule)`. All issues from the same source file appear together in ascending line order; pipeline-level findings with no file location sort first. Previously findings were emitted in map-iteration order (non-deterministic).
+
+### Fixed
+
+- **Warning format consistency** — include-resolution warnings, extends-chain warnings, and the workflow non-start warning now use the same ruff-style `path: [warning] message` format as lint findings instead of the old `[WARNING] …` prefix with no file context.
+
+- **Workflow rule permissive evaluation** — workflow `rules:if:` expressions are now evaluated in strict mode: an expression that cannot be fully parsed returns `false` (skip this rule, try the next) instead of `true` (match everything). Previously, a complex or partially-unsupported condition on the first workflow rule would match every context, blocking all subsequent rules and injecting the wrong variables. Job rules retain permissive evaluation (`true` on parse failure) to avoid silently dropping jobs.
+
+- **Single `=` operator in `rules:if:`** — a bare `=` not followed by `=` or `~` is now accepted as an alias for `==`. This is a common mistake in GitLab CI YAML; previously it caused a parse failure and triggered the permissive fallback.
+
+- **Source location lost through `extends:` resolution** — when a job was resolved via `extends:`, the merged definition was re-encoded and re-decoded as a fresh `model.Job` struct, which does not carry `File` or `Line` (they are not YAML keys). Those fields are now explicitly copied back from the original job before replacing it in `p.Jobs`, so extended jobs report the correct source file and line number in findings.
+
+## [0.2.13] - 2026-06-12
+
+### Added
+
+- **Variable expansion (`$VAR` / `${VAR}`)** — variable values that reference other variables are now expanded in the effective context after all sources are merged. Transitive chains (`A=$B`, `B=$C`) are resolved over up to ten passes; circular references are left as-is. The expanded values are visible in `--list-vars` output under "Effective context variables" and are used when evaluating `rules:if:` expressions.
+
+- **Non-string scalar variables (`bool`, `int`, `float64`)** — variables declared with bare `true`/`false` or integer values (e.g. `BUILD: true`, `RETRIES: 3`) are now handled correctly in all variable processing paths. Previously they were rendered as `(complex)` in `--list-vars` output and silently dropped from the effective context; they now render and inject as their string equivalents (`"true"`, `"3"`), matching GitLab CI's own behaviour where all variable values are strings.
+
+### Fixed
+
+- **YAML `\/` escape in double-quoted strings** — regex patterns containing `\/` (escaped forward-slash) in double-quoted `if:` expressions (e.g. `$CI_COMMIT_BRANCH =~ /^us\//`) caused a YAML parse error (`found unknown escape character`) with `gopkg.in/yaml.v3`, which does not implement this YAML 1.2 escape. The parser now preprocesses the raw bytes before unmarshalling: inside double-quoted strings, `\/` is rewritten to `\\/`, which `yaml.v3` parses as a literal backslash followed by a slash — preserving the regex intent.
+
+## [0.2.11] - 2026-06-12
+
+### Added
+
+- **Ruff-style finding output** — findings now follow the `file:line: RULEID [severity] message` format (e.g. `.gitlab-ci.yml:14: GL004 [error] job "deploy": stage "production" is not defined in 'stages'`), matching the output convention used by [ruff](https://docs.astral.sh/ruff/) and other modern linters. Job-scoped findings prefix the message with `job "name": `; pipeline-level findings omit the job prefix. Severity is lowercase inside brackets (`[error]`, `[warning]`).
+
+- **Implicit default context (`--branch main --source push`)** — when `glint check` or `glint graph` is invoked without any of `--branch`, `--tag`, `--source`, or `--var`, the context now defaults to `--branch main --source push` so that `rules:if:` expressions are always evaluated. Previously the context was empty and no rule evaluation occurred. Any explicit context flag bypasses the defaults entirely.
+
+- **`--list-vars` debug flag** — available on both `glint check` and `glint graph`; prints all pipeline-level variables collected from the root file and every included file (sorted `KEY=VALUE`) to stderr, then continues normally. When a context is active, also prints the effective merged variable set (pipeline defaults + workflow-rule variables + CLI flags). Useful for diagnosing GL032 false positives.
+
+- **Included-file variables now visible to all lint rules** — `variables:` blocks declared in included files (local, remote, project, and component includes) are now merged into the pipeline's variable namespace before linting. This eliminates false-positive GL032 warnings for variables declared in shared CI templates. Root-pipeline variables take precedence over included-file variables when the same key appears in both (matching GitLab's own override behaviour).
+
+- **Variable reference validation (GL032)** — glint now warns when a `rules:if:` expression references a variable (`$VAR` or `${VAR}`) that is not declared anywhere in the pipeline YAML: pipeline-level `variables:`, the job's own `variables:`, or any `workflow:rules:variables:` block. Predefined GitLab CI variable namespaces (`CI_*`, `GITLAB_*`, `FF_*`, `RUNNER_*`, `TRIGGER_*`, `CHAT_*`) are exempt. Because variables can also be set in GitLab CI/CD project settings (invisible to glint), the finding is a `[WARNING]` rather than an error. Each undeclared variable is reported at most once per job to keep the output concise.
+
+- **Structured rule IDs** — every finding now carries a stable `GL###` identifier (e.g. `GL003`) that appears in the output alongside the location and message: `.gitlab-ci.yml:14: GL003 [error] job "deploy": missing required field 'script'`. IDs are assigned per check function across 31 rules (GL001–GL031) and are stable across versions. The `linter.Finding` struct exposes the ID as a `Rule string` field for programmatic consumers. The README lint rules table is updated with ID columns.
+
+- **`workflow:rules:variables:` now propagate to job rule evaluation** — when a `workflow:rules:` entry matches, any `variables:` it defines are injected into the evaluation context so job `rules:if:` expressions can reference them. Pipeline-level `variables:` are also available as defaults (lower priority). Variable priority order, highest first: `--var` CLI overrides → `--branch`/`--tag`/`--source` shortcuts → workflow-rule variables → pipeline-level variable defaults. This means `$DEPLOY_TARGET == "production"` in a job rule correctly evaluates when a workflow rule sets `DEPLOY_TARGET: production` for the matching branch. The `glint graph tree` command benefits from the same enrichment.
+
+- **`rules:if:` expression evaluator improvements** — six correctness fixes to the GitLab CI expression parser:
+  - **Multi-line expressions** — newlines (`\n`, `\r`) are now treated as whitespace between tokens, so block-scalar `if:` values (e.g. `if: | ...`) and folded YAML scalars with `||`/`&&` on a continuation line are parsed correctly instead of falling back to permissive `true`.
+  - **`${VAR}` curly-brace variable syntax** — `${CI_COMMIT_BRANCH}` is now equivalent to `$CI_COMMIT_BRANCH` everywhere a value is expected.
+  - **Regex flags** — `/pattern/i`, `/pattern/m`, `/pattern/s` are now honoured; the `i` flag (case-insensitive) is translated to Go's `(?i)` prefix before compiling. Unknown flags are silently ignored.
+  - **Variable as regex RHS** — `$BRANCH =~ $PATTERN` where `$PATTERN` holds a `/regex/[flags]` string is now evaluated by extracting and compiling the pattern from the variable's value; if the value is empty or does not look like a regex literal the expression falls back to permissive `true`.
+  - **`true` / `false` keywords** — bare `true` and `false` (without quotes) are now recognised as the string values `"true"` and `"false"`, matching GitLab CI's own behaviour. `$GATEWAY_ENABLED == true` and `$FEATURE_FLAG == false` now evaluate correctly.
+  - **Integer literals** — bare integers (e.g. `$PARALLEL == 4`, `$ENABLED == 1`, `$DISABLED == 0`) are now parsed as their decimal string representations and compared accordingly.
+
+- **File and line numbers on findings** — every finding now includes the source file and line where the job is defined, e.g. `[ERROR] job "deploy" (src/deploy.yml:14): …`. For jobs that come from local or fetched includes the file reflects the include source. Pipeline-level findings (workflow rules, missing stages) reference the root pipeline file.
+
+- **`glint graph includes` shows jobs per file** — each node in the Mermaid include dependency graph now shows the jobs defined directly in that file. Jobs are rendered as rounded nodes (`(name)`) in a distinct light-purple style, connected with dashed arrows (`-.->`) to distinguish ownership from the include hierarchy (solid `-->` arrows). The root pipeline file always shows its direct jobs; local and fetched project/component nodes show theirs when the file can be read.
+
+### Fixed
+
+- **`include: remote:` URL includes are now fetched and merged** — glint fetches plain HTTPS URLs in `include: remote:` entries (no authentication), parses the resulting YAML, merges its jobs into the pipeline, and recursively resolves any sub-includes the remote file itself declares. Unreachable or unparseable URLs emit a `[WARNING]` and lint continues on the rest of the pipeline. The `glint graph includes` command now expands remote nodes with their jobs and sub-include tree, matching the behaviour of local and project includes.
+
+- **`needs: optional: true` downgraded to warning** — a `needs:` entry that carries `optional: true` and references a job not present in the pipeline now emits `[WARNING]` instead of `[ERROR]`. GitLab CI silently skips such dependencies at runtime (the job is absent when its include was not triggered), so the finding was a false positive. Non-optional missing needs remain errors. Optional missing deps are also excluded from the cycle-detection graph.
+
+- **`extends:` jobs with missing script downgraded to warning** — a job that declares `extends:` but has no `script` after resolution now emits `[WARNING]` instead of `[ERROR]`. The script may legitimately come from a base job in a remote include that could not be fetched at lint time (e.g. no token configured).
+
+- **Variable map form now parses correctly** — `variables:` entries that use the extended `{value, description, options}` form (GitLab CI 13.7+) no longer cause `yaml: cannot unmarshal !!map into string`. Both `Pipeline.Variables` and per-job `Variables` now accept either plain strings or map-form declarations.
+- **`default.image` map form now parses correctly** — `default: image: {name: ..., pull_policy: ...}` used to cause `yaml: cannot unmarshal !!map into string`; `DefaultConfig.Image` is now typed as `any` to match `Job.Image`.
+- **`default.before_script` / `default.after_script` now accept both list and scalar forms** — previously `DefaultConfig.BeforeScript` and `DefaultConfig.AfterScript` were `[]string`, causing a parse error when the field was written as a block scalar string. They are now typed as `any` to match the corresponding `Job` fields.
+- **`rules.changes` / `rules.exists` map form now parses correctly** — extended `changes: {paths: [...], compare_to: "..."}` syntax (GitLab CI 15.3+) used to cause `yaml: cannot unmarshal !!map into []string`.
+
+## [0.2.0] - 2026-06-11
+
+### Added
+
+- **Subcommand CLI** — reworked interface inspired by [ruff](https://docs.astral.sh/ruff/):
+  - `glint check <file>` — lint a pipeline (replaces bare `glint <file>`)
+  - `glint graph [mode] <file>` — visualise the pipeline (replaces `--graph` flag)
+  - Graph modes: no-arg (tree + includes), `tree`, `includes`, `pipeline`, `all`
+  - Per-command `--help` with ruff-style layout: `Arguments:`, `Options:` (flag declaration on its own line, description below), `[env: ...]` / `[default: ...]` / `[possible values: ...]` metadata, `Examples:` section
+
+- **`glint graph tree`** — jobs displayed as a terminal directory tree grouped by stage (like the `tree` command); job-type annotations (`[manual]`, `[delayed]`, `[trigger]`) when no context is set; evaluated-state annotations (`[skipped]`, `[manual]`) when a context is provided via `--branch` / `--tag` / `--source`
+
+- **Context flags on `glint graph`** — `--branch`, `--tag`, `--source`, `--var` are now available on `glint graph` as well as `glint check`
+
+- **Local include resolution** — `include: local:` entries are now read from disk, recursively resolved, and merged into the pipeline before linting; enables cross-file `extends:` and `needs:` validation for multi-file pipelines
+
+- **Cross-platform release builds** — two Taskfile tasks for tagged release binaries:
   - `task build-windows` — cross-compiles for Windows x64; output: `glint-<tag>.exe`
   - `task build-linux` — cross-compiles for Linux x64; output: `glint-<tag>-linux-amd64`
-  - Both tasks enforce that the current commit carries an exact git tag (`git describe --tags --exact-match`); they abort with a clear error otherwise
+  - Both tasks require an exact git tag on the current commit
+
+### Fixed
+
+- **`extends:` unknown base no longer fatal** — when a base job referenced by `extends:` does not exist, glint now emits a resolver warning and skips extends resolution for that job rather than aborting with exit code 2; linting continues on the job's own fields
+- **`script: |` (block scalar) support** — jobs using a multiline block scalar for `script:`, `before_script:`, or `after_script:` are now parsed correctly; previously caused false-positive "missing script" errors
+
+### Changed
+
+- **`glint <file>` removed** — use `glint check <file>`
+- **`--graph <mode>` removed** — replaced by `glint graph [mode]`
+- **`--graph-out` renamed to `--out`** — now a flag on `glint graph` (`glint graph pipeline --out <dir>`)
 
 ## [0.1.0] - 2026-06-07
 

README.md

@@ -1,7 +1,13 @@
-# glint
+<p align="center">
+  <img src="assets/glint-logo.png" alt="glint logo" width="220" />
+</p>
 
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![Release](https://img.shields.io/badge/release-v0.1.0-blue.svg)](CHANGELOG.md)
+<h1 align="center">glint</h1>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/release-v0.2.19-blue.svg" alt="Release"></a>
+</p>
 
 > **Disclaimer:** This tool was built through iterative AI-assisted development with [Claude](https://claude.ai). It is experimental, incomplete, and not intended for production use. Coverage of GitLab CI keywords is best-effort and may lag behind GitLab's evolving spec. Use it at your own discretion — no correctness guarantees are made. Contributions and bug reports are welcome.
 
@@ -18,8 +24,32 @@ A local tool to validate and lint `.gitlab-ci.yml` pipelines without needing a G
 - **Remote project includes** — fetches `include: project:` templates from the GitLab API so extends/needs can be validated against the full merged pipeline
 - **CI/CD catalog components** — resolves `include: component:` references from the GitLab CI/CD Catalog; public components work without a token
 - **Deprecation warnings** — flags `only`/`except` usage in favour of `rules`
-- **Graph output** — emits Mermaid diagrams for the include dependency tree and the pipeline jobs layout (DAG or classic stage ordering)
-- **Context simulation** — pass `--branch`, `--tag`, or `--source` to see which jobs would be active, manual, or skipped for a specific branch push, tag, or pipeline event; evaluates `rules:if:` expressions and `only`/`except` filters
+- **Local include resolution** — `include: local:` entries are read from disk and recursively merged before linting, so multi-file pipelines are fully validated
+- **Extended variable declarations** — `variables:` entries may use the `{value, description, options}` map form (GitLab CI 13.7+); `default.image` accepts both string and map form; `rules.changes`/`rules.exists` accept both list and `{paths, compare_to}` map form
+- **Graph output** — `glint graph` prints a job tree (stages → jobs) to the terminal; `glint graph includes` emits a Mermaid include dependency diagram; `glint graph pipeline` renders a GitLab CI-style PNG/SVG
+- **Context simulation** — pass `--branch`, `--tag`, or `--source` to `glint check` or `glint graph` to see which jobs would be active, manual, or skipped for a specific pipeline event; evaluates `rules:if:` expressions and `only`/`except` filters
+- **Variable expansion** — `$VAR` and `${VAR}` references inside variable values are expanded after all sources are merged (pipeline defaults → workflow-rule overrides → CLI flags); transitive chains resolve automatically; visible via `--list-vars`
+- **Non-string variable scalars** — `BUILD: true`, `RETRIES: 3` and other bare boolean/integer variable values are handled correctly throughout: they render in `--list-vars` output and are injected into the evaluation context as their string equivalents, matching GitLab CI's behaviour
+- **Static reachability (GL033)** — warns when a job's `rules:` block can never activate: if every rule has `when: never` the job is permanently excluded from any pipeline run, provable without evaluating any `if:` expressions
+- **`services:` validation (GL034)** — map form requires a `name` key; `alias` must be a valid DNS label (letters, digits, hyphens, dots; no leading/trailing hyphens)
+- **`rules:changes` / `rules:exists` glob safety (GL035)** — warns when paths are absolute (start with `/`), which can never match since GitLab CI paths are always relative to the repository root
+- **`timeout:` format (GL036)** — validates that job and `default:` timeout values are valid GitLab CI duration strings (`1h 30m`, `90 minutes`, `2 hours`, etc.)
+- **`id_tokens:` validation (GL037)** — each OIDC token entry must have an `aud` key (missing `aud` is a GitLab API error at runtime)
+- **`secrets:` validation (GL038)** — each secret entry must declare exactly one provider (`vault`, `gcp_secret_manager`, or `azure_key_vault`)
+- **`pages:` keyword + `artifacts.paths` (GL039)** — warns when a job uses the `pages:` keyword but `artifacts.paths` does not include the publish directory (default: `public`)
+- **Duplicate stage names (GL040)** — warns when a stage name appears more than once in `stages:`; GitLab silently merges duplicates, which can cause confusing ordering
+- **`cache.key.files` glob detection (GL041)** — warns when `cache.key.files` entries contain glob metacharacters; this field requires exact file paths, not patterns
+- **Recursive include depth limit** — include chains are capped at 100 nesting levels (matching GitLab's own limit); project and component includes are now tracked in the visited-file set to prevent cross-include cycles
+- **`include: inputs:` substitution** — when a `component:` entry has a `with:` block, all `$[[ inputs.KEY ]]` and `$[[ inputs.KEY | default(…) ]]` placeholders in the fetched template are substituted before parsing, so component-scoped jobs get their correct `stage:` and keyword values instead of `$[[…]]` placeholders
+- **Offline mode + include cache** — pass `--cache-dir DIR` to cache fetched remote templates (project: and component: includes) to disk; `--offline` serves entirely from the cache without making network calls
+- **Structured output formats** — `--format json` emits a stable JSON report; `--format sarif` emits SARIF 2.1.0 (consumed by GitHub Code Scanning and GitLab SAST); `--format junit` emits JUnit XML (consumable as a CI test-report artifact); `--format github` emits GitHub Actions annotation lines (`::error file=…::`) so findings appear as inline PR comments
+- **`.glint.yml` project config** — rule suppression (`ignore: [GL007]`), severity overrides (`severity: {GL004: warning}`), extra stages allowlist (`stages: [quality]`), and default token/URL/cache-dir so flags are not needed on every invocation
+- **Inline suppression comments** — `# glint: ignore GL007` (or `# glint: ignore all`) immediately before a job definition suppresses the specified rule(s) for that job without touching other jobs
+- **Sorted findings output** — findings are sorted by source file then line number, so all issues from the same file appear together in order; pipeline-level findings (no file) sort first
+- **Consistent ruff-style warnings** — all warnings (unresolvable includes, skipped extends chains, workflow non-start) use the same `path: [warning] message` format as lint findings
+- **`--version` / `-v` flag** — prints the compiled version string (e.g. `glint v0.2.14`); the version is also shown at the top of every `--help` output
+
+See [ROADMAP.md](ROADMAP.md) for planned improvements.
 
 ## Requirements
 
@@ -42,12 +72,130 @@ task build
 
 ## Usage
 
+```
+glint [OPTIONS] <COMMAND>
+
+Commands:
+  check    Lint a pipeline file — exits 0 (clean) or 1 (errors found)
+  graph    Visualise the pipeline as a job tree or Mermaid graph
+```
+
+Run `glint <command> --help` for command-specific options and examples.
+
+### `glint check`
+
 ```bash
-glint [options] <pipeline.yml>
+glint check .gitlab-ci.yml
 ```
 
 Exits `0` when no errors are found, `1` when at least one error is reported.
 
+### Output formats
+
+Pass `--format` to control the output. Plain text is the default.
+
+```bash
+# Default: ruff-style text (human-readable)
+glint check .gitlab-ci.yml
+
+# JSON — stable schema, machine-readable
+glint check --format json .gitlab-ci.yml
+
+# SARIF 2.1.0 — GitHub Code Scanning / GitLab SAST
+glint check --format sarif .gitlab-ci.yml > glint.sarif
+
+# JUnit XML — CI test-report artifact (GitLab: artifacts:reports:junit)
+glint check --format junit .gitlab-ci.yml > glint-junit.xml
+
+# GitHub Actions annotations — inline PR diff comments
+glint check --format github .gitlab-ci.yml
+```
+
+In structured formats (`json`, `sarif`, `junit`, `github`) the summary line
+(`OK: … no issues found` or `N finding(s): M error(s)`) is written to stderr
+so stdout contains only the machine-readable payload.
+
+**JSON schema (`schema_version: 1`):**
+```json
+{
+  "schema_version": 1,
+  "glint_version": "v0.2.18",
+  "pipeline": ".gitlab-ci.yml",
+  "findings": [
+    {"rule":"GL004","severity":"error","file":".gitlab-ci.yml","line":14,
+     "job":"deploy","message":"stage \"production\" is not defined in 'stages'"}
+  ],
+  "summary": {"total": 1, "errors": 1, "warnings": 0}
+}
+```
+
+**GitHub annotation lines:**
+```
+::error file=.gitlab-ci.yml,line=14,title=GL004::job "deploy": stage "production" is not defined in 'stages'
+```
+
+### Project configuration (`.glint.yml`)
+
+Place a `.glint.yml` file next to your pipeline (or anywhere in the directory tree up to the repository root) to configure glint for that project. glint searches upward from the pipeline file's directory, stopping at the first `.git` boundary.
+
+```yaml
+# .glint.yml
+
+# Suppress specific rules entirely.
+ignore:
+  - GL007   # we still use only:/except:, migration in progress
+  - GL032   # lots of dynamic variables injected by CI
+
+# Override the severity of specific rules.
+severity:
+  GL004: warning  # demote stage errors to warnings during a migration
+  GL035: error    # promote absolute-path warning to error for this project
+
+# Extra stages that are valid but not declared in the pipeline YAML itself
+# (e.g. injected by an include template we can't edit).
+stages:
+  - quality
+  - security
+
+# Default token — overridden by --token flag and GITLAB_TOKEN env.
+token: glpat-xxxx
+
+# Default GitLab instance URL.
+url: https://gitlab.example.com
+
+# Default cache directory for fetched remote includes.
+cache_dir: ~/.cache/glint
+```
+
+**Priority chain for token and URL:** `--token`/`--gitlab-url` flags > `.glint.yml` values > `GITLAB_TOKEN`/`CI_SERVER_URL` environment variables.
+
+### Inline suppression (`# glint: ignore`)
+
+Suppress a finding for a specific job by placing a `# glint: ignore RULE` comment immediately before the job definition:
+
+```yaml
+# glint: ignore GL007
+legacy-job:
+  stage: build
+  only:
+    - main
+  script: echo ok
+
+# Multiple rules — comma- or space-separated:
+# glint: ignore GL007, GL032
+another-job:
+  stage: build
+  script: echo ok
+
+# Suppress all rules for this job:
+# glint: ignore all
+noisy-job:
+  stage: build
+  script: echo ok
+```
+
+Inline suppressions are scoped to the single job they precede. They do not affect other jobs or pipeline-level findings. For project-wide suppression use `.glint.yml` `ignore:`.
+
 ### Remote project includes
 
 Pipelines that include templates from other GitLab projects are supported.
@@ -55,21 +203,39 @@ Provide a token so `glint` can fetch them:
 
 ```bash
 # personal access token (read_api scope)
-GITLAB_TOKEN=glpat-xxxx glint .gitlab-ci.yml
+GITLAB_TOKEN=glpat-xxxx glint check .gitlab-ci.yml
 
 # CI/CD job token (when running inside a pipeline)
-CI_JOB_TOKEN=$CI_JOB_TOKEN glint .gitlab-ci.yml
+CI_JOB_TOKEN=$CI_JOB_TOKEN glint check .gitlab-ci.yml
 
 # self-hosted GitLab
-GITLAB_TOKEN=glpat-xxxx GITLAB_URL=https://gitlab.example.com glint .gitlab-ci.yml
+GITLAB_TOKEN=glpat-xxxx GITLAB_URL=https://gitlab.example.com glint check .gitlab-ci.yml
 
 # or via flags
-glint --token glpat-xxxx --gitlab-url https://gitlab.example.com .gitlab-ci.yml
+glint check --token glpat-xxxx --gitlab-url https://gitlab.example.com .gitlab-ci.yml
 ```
 
 **Project includes** require a token; without one they are skipped with a
 warning and the rest of the pipeline is linted as-is.
 
+### Include cache and offline mode
+
+Pass `--cache-dir` to cache fetched remote templates so repeated runs skip the network:
+
+```bash
+# First run: fetches and caches
+glint check --cache-dir ~/.cache/glint .gitlab-ci.yml
+
+# Subsequent runs: served from cache
+glint check --cache-dir ~/.cache/glint .gitlab-ci.yml
+
+# Fully offline (uses ~/.cache/glint automatically when --cache-dir is absent)
+glint check --offline .gitlab-ci.yml
+glint check --offline --cache-dir ~/.cache/glint .gitlab-ci.yml
+```
+
+Cache entries are keyed by SHA-256 of the full request URL/coordinates and stored as plain YAML files in the cache directory. There is currently no automatic expiry — delete the directory or individual entries to force a fresh fetch.
+
 **Component includes** (`include: component: ...`) attempt the fetch
 unauthenticated, so public [CI/CD Catalog](https://gitlab.com/explore/catalog)
 components work without a token. A warning is emitted if the fetch fails.
@@ -104,26 +270,36 @@ GitLab at runtime. Jobs in fetched components may use `$[[ inputs.xxx ]]`
 placeholders in fields like `stage`; `glint` skips those fields rather
 than producing false positive errors.
 
-### Graph output
+### `glint graph`
 
-Pass `--graph` to visualise the pipeline instead of running lint rules.
+Visualise the pipeline. Without a mode word, prints a job tree and the include
+dependency graph separated by `---`.
 
 ```bash
-# Include dependency graph (which files include which) → Mermaid to stdout
-glint --graph includes .gitlab-ci.yml > includes.mmd
+# Default: job tree + include dependency graph
+glint graph .gitlab-ci.yml
 
-# GitLab-like pipeline layout → PNG (or SVG fallback) written to --graph-out dir
-glint --graph pipeline .gitlab-ci.yml
+# Job tree only (stages → jobs, like the tree command)
+glint graph tree .gitlab-ci.yml
+
+# Include dependency graph → Mermaid flowchart to stdout
+glint graph includes .gitlab-ci.yml > includes.mmd
+
+# GitLab-like pipeline layout → PNG (or SVG fallback) written to --out dir
+glint graph pipeline .gitlab-ci.yml
 # prints the output file path, e.g.: glint-out/pipeline-20260607-143022.png
 
-# Both at once: Mermaid to stdout + pipeline file path to stderr
-glint --graph all .gitlab-ci.yml > includes.mmd
+# Mermaid to stdout + pipeline file path to stderr
+glint graph all .gitlab-ci.yml > includes.mmd
 
-# Custom output directory
-glint --graph pipeline --graph-out /tmp/graphs .gitlab-ci.yml
+# Custom output directory (pipeline mode)
+glint graph pipeline --out /tmp/graphs .gitlab-ci.yml
 ```
 
-**Include graph** (`--graph includes`) — [Mermaid](https://mermaid.js.org) flowchart written to stdout.
+**Job tree** (`graph tree`) — stages as branches, jobs as leaves. Jobs with
+`when: manual`, `when: delayed`, or `trigger:` are annotated in brackets.
+
+**Include graph** (`graph includes`) — [Mermaid](https://mermaid.js.org) flowchart written to stdout.
 Pipe to a `.mmd` file or paste into [mermaid.live](https://mermaid.live).
 One node per include entry, colour-coded by type:
 - Orange (bold): the main pipeline file
@@ -133,8 +309,8 @@ One node per include entry, colour-coded by type:
 - Grey: `remote:` URL includes
 - Light orange: GitLab-provided `template:` includes
 
-**Pipeline graph** (`--graph pipeline`) — GitLab CI-style SVG rendered to a timestamped file
-in the `--graph-out` directory (default: `glint-out/`). Converted to PNG automatically
+**Pipeline graph** (`graph pipeline`) — GitLab CI-style SVG rendered to a timestamped file
+in the `--out` directory (default: `glint-out/`). Converted to PNG automatically
 when `rsvg-convert`, `inkscape`, or `magick` is available; falls back to SVG otherwise.
 Jobs are colour-coded by type:
 - Blue (`#1f75cb`): regular jobs
@@ -147,26 +323,28 @@ Classic mode draws L-shaped or straight connectors between stage columns otherwi
 
 ### Context simulation
 
-Pass `--branch`, `--tag`, or `--source` to see which jobs would run for a given
-pipeline event. The pipeline is still fully linted; context output is printed first.
+Pass `--branch`, `--tag`, or `--source` to `glint check` to see which jobs
+would run for a given pipeline event. The pipeline is still fully linted;
+context output is printed first.
 
 ```bash
 # What runs on a push to develop?
-glint --branch develop .gitlab-ci.yml
+glint check --branch develop .gitlab-ci.yml
 
 # What runs when a v1.2.0 tag is pushed?
-glint --tag v1.2.0 .gitlab-ci.yml
+glint check --tag v1.2.0 .gitlab-ci.yml
 
 # Merge request pipeline
-glint --source merge_request_event .gitlab-ci.yml
+glint check --source merge_request_event .gitlab-ci.yml
 
 # Arbitrary variable overrides (repeatable)
-glint --branch main --var DEPLOY_ENV=production .gitlab-ci.yml
+glint check --branch main --var DEPLOY_ENV=production .gitlab-ci.yml
 ```
 
 **Evaluated:**
 - `rules:if:` — full expression language: `==`, `!=`, `=~`, `!~`, `&&`, `||`, `!`, `()`, `$VAR`, string literals, `null`
 - `only:` / `except:` — ref keywords (`branches`, `tags`, `merge_requests`, `schedules`, …), branch name globs (`feat/*`), and `/regex/` patterns
+- Variable expansion — `$VAR` / `${VAR}` references within variable values are expanded after all sources are merged; use `--list-vars` to inspect the resolved values
 
 **Not evaluated** (no git tree at lint time): `rules:changes:`, `rules:exists:`.
 Rules without an `if:` clause always match.
@@ -183,8 +361,12 @@ Rules without an `if:` clause always match.
 ### Example output
 
 ```
-# Clean pipeline, no context
-OK: .gitlab-ci.yml — no issues found (5 jobs, 3 stages)
+# Clean pipeline (implicit default: --branch main --source push)
+Context: branch=main, source=push
+
+Active  (5): build, deploy-staging, test, ...
+
+OK: .gitlab-ci.yml — no issues found (5 job(s), 3 stage(s))
 
 # With --branch develop context
 Context: branch=develop, source=push
@@ -192,7 +374,7 @@ Context: branch=develop, source=push
 Active  (3): build, deploy-staging, test
 Skipped (2): deploy-prod, release-notes
 
-OK: .gitlab-ci.yml — no issues found (5 jobs, 3 stages)
+OK: .gitlab-ci.yml — no issues found (5 job(s), 3 stage(s))
 
 # With --tag v1.0.0 context
 Context: tag=v1.0.0, source=push
@@ -200,75 +382,86 @@ Context: tag=v1.0.0, source=push
 Active  (4): build, deploy-prod, release-notes, test
 Skipped (1): deploy-staging
 
-OK: .gitlab-ci.yml — no issues found (5 jobs, 3 stages)
+OK: .gitlab-ci.yml — no issues found (5 job(s), 3 stage(s))
 
 # Pipeline with issues
-[ERROR] job "deploy": stage "production" is not defined in 'stages'
-[ERROR] job "test": needs unknown job "build-app"
-[WARNING] job "old-job": 'only'/'except' are deprecated; prefer 'rules'
+.gitlab-ci.yml:14: GL004 [error] job "deploy": stage "production" is not defined in 'stages'
+.gitlab-ci.yml:22: GL027 [error] job "test": needs unknown job "build-app"
+.gitlab-ci.yml:31: GL007 [warning] job "old-job": 'only'/'except' are deprecated; prefer 'rules'
 
 3 finding(s): 2 error(s)
 ```
 
 ## Lint rules
 
+Every finding includes a stable rule ID (e.g. `GL003`) that can be used to filter output or reference a specific check in documentation.
+
 ### Pipeline-level
 
-| Severity | Rule |
-|----------|------|
-| ERROR | `workflow.rules[*].when` is not `always` or `never` |
-| WARNING | No `stages` defined (GitLab falls back to default stages) |
+| ID | Severity | Rule |
+|----|----------|------|
+| GL002 | ERROR | `workflow.rules[*].when` is not `always` or `never` |
+| GL001 | WARNING | No `stages` defined (GitLab falls back to default stages) |
+| GL036 | ERROR | `default.timeout` is not a valid GitLab CI duration string |
+| GL040 | WARNING | A stage name appears more than once in `stages:` |
 
 ### Job-level — structure
 
-| Severity | Rule |
-|----------|------|
-| ERROR | Job is missing required `script` (or `run`) — non-trigger, non-template jobs |
-| ERROR | Job references a `stage` not declared in `stages` |
-| ERROR | `only` and `rules` used together on the same job |
-| ERROR | `except` and `rules` used together on the same job |
-| WARNING | `only`/`except` used (deprecated, prefer `rules`) |
+| ID | Severity | Rule |
+|----|----------|------|
+| GL003 | ERROR | Job is missing required `script` (or `run`) — non-trigger, non-template jobs |
+| GL004 | ERROR | Job references a `stage` not declared in `stages` |
+| GL005 | ERROR | `only` and `rules` used together on the same job |
+| GL006 | ERROR | `except` and `rules` used together on the same job |
+| GL007 | WARNING | `only`/`except` used (deprecated, prefer `rules`) |
 
 ### Job-level — keyword constraints
 
-| Severity | Rule |
-|----------|------|
-| ERROR | `when` is not one of `on_success`, `on_failure`, `always`, `manual`, `delayed`, `never` |
-| ERROR | `when: delayed` without `start_in` |
-| ERROR | `start_in` set but `when` is not `delayed` |
-| ERROR | `parallel` integer not in range 2–200 |
-| ERROR | `parallel` map form missing `matrix` key |
-| ERROR | `retry` integer not in range 0–2 |
-| ERROR | `retry.max` not in range 0–2 |
-| ERROR | `retry.when` contains an invalid failure type |
-| ERROR | `allow_failure` is not a boolean or a map with `exit_codes` |
-| ERROR | `interruptible` is not a boolean |
-| ERROR | `trigger` job also has `script` |
-| ERROR | `trigger` map missing `project` or `include` |
-| ERROR | `coverage` is not a regex pattern wrapped in `/` |
-| ERROR | `release` missing required `tag_name` |
-| ERROR | `environment.url` set without `environment.name` |
-| ERROR | `environment.action` is not one of `start`, `stop`, `prepare`, `verify`, `access` |
-| ERROR | `artifacts.when` is not `on_success`, `on_failure`, or `always` |
-| ERROR | `artifacts.expose_as` set without `artifacts.paths` |
-| ERROR | `cache.when` is not `on_success`, `on_failure`, or `always` |
-| ERROR | `cache.policy` is not `pull`, `push`, or `pull-push` |
-| ERROR | `rules[*].when` is not one of the valid `when` values |
-| ERROR | `image` map form missing `name` key |
-| ERROR | `inherit.default` / `inherit.variables` is not a boolean or list |
-| WARNING | `pages` job `artifacts.paths` does not include `public` |
+| ID | Severity | Rule |
+|----|----------|------|
+| GL008 | ERROR | `when` is not one of `on_success`, `on_failure`, `always`, `manual`, `delayed`, `never` |
+| GL009 | ERROR | `when: delayed` without `start_in` |
+| GL010 | ERROR | `start_in` set but `when` is not `delayed` |
+| GL011 | ERROR | `parallel` integer not in range 2–200, or map form missing `matrix` key |
+| GL012 | ERROR | `retry` integer not in range 0–2, or `retry.max` out of range |
+| GL013 | ERROR | `retry.when` contains an unrecognised failure type |
+| GL014 | ERROR | `allow_failure` is not a boolean or a map with `exit_codes` |
+| GL015 | ERROR | `interruptible` is not a boolean |
+| GL016 | ERROR | `trigger` job also has `script` |
+| GL017 | ERROR | `trigger` map missing `project` or `include` |
+| GL018 | ERROR | `coverage` is not a regex pattern wrapped in `/` |
+| GL019 | ERROR | `release` missing required `tag_name`, or is not a map |
+| GL020 | ERROR | `environment.url` set without `environment.name`, or invalid `environment.action` |
+| GL021 | ERROR | `artifacts.when` invalid, or `artifacts.expose_as` set without `artifacts.paths` |
+| GL022 | WARNING | `pages` job `artifacts.paths` does not include `public` |
+| GL023 | ERROR | `cache.when` or `cache.policy` has an invalid value |
+| GL024 | ERROR | `rules[*].when` is not one of the valid `when` values |
+| GL025 | ERROR | `image` map form missing `name` key |
+| GL026 | ERROR | `inherit.default` / `inherit.variables` is not a boolean or list |
+| GL034 | ERROR | `services:` map form missing `name`, or `alias` is not a valid DNS label |
+| GL036 | ERROR | `timeout:` is not a valid GitLab CI duration string (e.g. `1h 30m`, `90 minutes`) |
+| GL037 | ERROR | `id_tokens:` entry is missing the required `aud` key |
+| GL038 | ERROR | `secrets:` entry is missing a provider key (`vault`, `gcp_secret_manager`, or `azure_key_vault`) |
+| GL039 | WARNING | Job has `pages:` keyword but `artifacts.paths` does not include the publish directory |
+| GL041 | WARNING | `cache.key.files` entry looks like a glob pattern; must be an exact file path |
 
 ### Cross-job graph
 
-| Severity | Rule |
-|----------|------|
-| ERROR | `needs:` references a job that does not exist |
-| ERROR | `needs:` references a job in a later stage |
-| ERROR | Circular dependency detected in `needs:` graph |
-| ERROR | `dependencies:` references a job that does not exist |
-| ERROR | `dependencies:` references a job in the same or a later stage |
-| ERROR | `extends:` references an unknown job |
-| ERROR | Cycle detected in `extends:` graph |
+| ID | Severity | Rule |
+|----|----------|------|
+| GL027 | ERROR/WARNING | `needs:` references a job that does not exist (WARNING when `optional: true`) |
+| GL028 | ERROR | `needs:` references a job in a later stage |
+| GL029 | ERROR | Circular dependency detected in `needs:` graph |
+| GL030 | ERROR | `dependencies:` references a job that does not exist |
+| GL031 | ERROR | `dependencies:` references a job in the same or a later stage |
+
+### Expression validation
+
+| ID | Severity | Rule |
+|----|----------|------|
+| GL032 | WARNING | `rules:if:` references `$VAR` not declared in `variables:` (pipeline, job, or `workflow:rules:variables:`) — may be a false positive for variables set in GitLab CI/CD project settings |
+| GL033 | WARNING | Every rule in `rules:` has `when: never` — job is permanently excluded from the pipeline (statically provable without context) |
+| GL035 | WARNING | `rules:changes` / `rules:exists` path is absolute; GitLab CI paths are relative to the repo root — absolute paths will never match |
 
 ### Hidden jobs (templates)
 

ROADMAP.md

@@ -4,58 +4,55 @@ This document tracks planned improvements to `glint`. Items are grouped by theme
 
 ---
 
-## Context-aware validation
+## Context-aware validation — ✓ single-context shipped in v0.2.0; expression evaluator hardened post-v0.2.0; implicit defaults and --list-vars shipped v0.2.11; variable expansion and scalar handling shipped v0.2.13; workflow evaluation and output fixes shipped v0.2.14
 
-Pipelines in Git Flow, Trunk-Based Development, or any branching strategy are rarely uniform: jobs activate or skip based on `$CI_COMMIT_BRANCH`, `$CI_COMMIT_TAG`, `$CI_PIPELINE_SOURCE`, and similar runtime variables. Today `glint` validates structure but cannot tell which jobs are actually reachable for a given context.
-
-The plan is to make the execution context injectable so the linter can evaluate `rules:if:` / `only` / `except` conditions and report per-context reachability.
-
-**CLI surface**
+Single-context simulation is fully implemented. Pass `--branch`, `--tag`, `--source`, or `--var` to either `glint check` or `glint graph`; jobs are evaluated and shown as active / manual / skipped.
 
 ```bash
-# Push to develop
-glint --branch develop .gitlab-ci.yml
-
-# Tag push (v1.2.0) — sets CI_COMMIT_TAG and clears CI_COMMIT_BRANCH
-glint --tag v1.2.0 .gitlab-ci.yml
-
-# Merge request pipeline
-glint --source merge_request_event \
-           --var CI_MERGE_REQUEST_TARGET_BRANCH_NAME=main \
-           .gitlab-ci.yml
-
-# Explicit variable overrides for anything not covered by the shortcuts
-glint --var CI_COMMIT_BRANCH=feat/my-feature \
-           --var CI_ENVIRONMENT_NAME=staging \
-           .gitlab-ci.yml
-
-# Simulate multiple contexts in one run (print per-context job tables)
-glint --context branch=main \
-           --context branch=develop \
-           --context tag=v1.0.0 \
-           .gitlab-ci.yml
+# shipped: single-context simulation
+glint check --branch develop .gitlab-ci.yml
+glint check --tag v1.2.0 .gitlab-ci.yml
+glint check --source merge_request_event --var CI_MERGE_REQUEST_TARGET_BRANCH_NAME=main .gitlab-ci.yml
+glint graph tree --branch main .gitlab-ci.yml   # tree annotated with [skipped] / [manual]
 ```
 
-**What context injection enables**
+**Shipped post-v0.2.0 (unreleased)**
 
-- Each job is resolved to **active** / **manual** / **skipped** for the given context
-- Warn when the entire pipeline would produce zero runnable jobs (common mistake when a `workflow:rules:` block is too restrictive)
-- Lint only the active job subset — skip `needs:` / `dependencies:` cross-checks for jobs that never co-execute in that context
-- `--context` multi-simulation: print a table showing which jobs activate per context, making it easy to audit Git Flow rules across branches and tags at once
+- ✓ **`workflow:rules:variables:` propagation** — variables defined on the matching `workflow:rules:` entry are injected into the evaluation context before job `rules:if:` expressions are evaluated. Pipeline-level `variables:` defaults are also available. Priority chain (highest wins): `--var` > shortcuts > workflow-rule vars > pipeline defaults.
+- ✓ **Expression evaluator: multi-line expressions** — newlines in block-scalar and folded YAML `if:` values are now treated as whitespace; `||` / `&&` on a continuation line evaluate correctly.
+- ✓ **Expression evaluator: `${VAR}` curly-brace syntax** — `${CI_COMMIT_BRANCH}` is equivalent to `$CI_COMMIT_BRANCH` everywhere.
+- ✓ **Expression evaluator: regex flags** — `/pattern/i`, `/pattern/m`, `/pattern/s` are now supported; `i` maps to `(?i)` in Go's regexp.
+- ✓ **Expression evaluator: variable as regex RHS** — `$BRANCH =~ $PATTERN` where `$PATTERN` holds a `/regex/` string is evaluated correctly.
+- ✓ **Expression evaluator: bare `true` / `false` keywords** — treated as the strings `"true"` / `"false"` matching GitLab CI's own behaviour; `$GATEWAY_ENABLED == true` now evaluates correctly.
+- ✓ **Expression evaluator: integer literals** — `$COUNT == 4`, `$ENABLED == 1`, `$DISABLED == 0` compare as decimal strings.
 
-**Expression evaluator scope**
+~~**Implicit default context**~~ — ✓ shipped v0.2.11; `glint check` and `glint graph` default to `--branch main --source push` when no context flag is given, so `rules:if:` expressions are always evaluated out of the box.
 
-GitLab's `rules:if:` expression language will be implemented incrementally:
+~~**`--list-vars` debug flag**~~ — ✓ shipped v0.2.11; prints sorted `KEY=VALUE` of all collected variables (pipeline YAML + included files + workflow-rule union + effective context) to stderr.
 
-| Priority | Operators / features |
-|----------|----------------------|
-| 1 (MVP)  | `==`, `!=`, `null` check, `&&`, `\|\|`, `!`, parentheses |
-| 2        | Regex match `=~` / `!~` with `/pattern/` literals |
-| 3        | `$CI_COMMIT_BRANCH =~ /^feat\//`, anchored patterns |
-| 4        | `only: branches / tags / merge_requests` shorthand mapping |
-| 5        | `changes:` path glob evaluation against a real or mock file tree |
+**Shipped in v0.2.13**
 
-Predefined variables populated automatically from `--branch` / `--tag` / `--source` shortcuts: `CI_COMMIT_BRANCH`, `CI_COMMIT_TAG`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`, `CI_PIPELINE_SOURCE`, `CI_DEFAULT_BRANCH` (defaulting to `main`).
+- ✓ **Variable expansion** — `$VAR` / `${VAR}` references within variable values are expanded after all sources are merged; transitive chains resolve over multiple passes; visible in `--list-vars` effective-context output.
+- ✓ **Non-string scalar variables** — `BUILD: true`, `RETRIES: 3` and similar bare boolean/integer values now render correctly in `--list-vars` and are injected into the evaluation context as string equivalents; previously shown as `(complex)` and silently dropped.
+- ✓ **YAML `\/` escape in double-quoted strings** — regex patterns like `/^us\//` in double-quoted `if:` blocks no longer cause a parse error; the raw bytes are preprocessed before YAML unmarshalling.
+
+**Shipped in v0.2.14**
+
+- ✓ **Workflow rule strict evaluation** — workflow `rules:if:` now uses strict mode (parse failure → skip rule, not match); fixes premature matching that blocked later rules and injected wrong variables.
+- ✓ **Single `=` operator** — `=` is now accepted as an alias for `==` in `rules:if:` expressions, matching common user intent.
+- ✓ **Source location through `extends:` resolution** — `File` and `Line` are now preserved when a job is rebuilt via extends, so findings reference the correct source location.
+- ✓ **Sorted findings output** — findings are sorted by `(File, Line, Rule)`; same-file issues group together in line order.
+- ✓ **Consistent warning format** — all warnings use ruff-style `path: [warning] message` format.
+- ✓ **`--version` / `-v` flag** — prints compiled version; version also shown at the top of every `--help` output.
+
+**Remaining work**
+
+- **Multi-context simulation** — run multiple contexts in one invocation and print a comparison table:
+  ```bash
+  glint check --context branch=main --context branch=develop --context tag=v1.0.0 .gitlab-ci.yml
+  ```
+- **Context-scoped linting** — skip `needs:`/`dependencies:` cross-checks for jobs that are statically unreachable in the given context
+- **`rules:changes:` evaluation** — path glob evaluation against the local git tree
 
 ---
 
@@ -63,44 +60,45 @@ Predefined variables populated automatically from `--branch` / `--tag` / `--sour
 
 The current rule set covers the most common sources of broken pipelines. These are the gaps most likely to matter in practice.
 
-- **Variable reference validation** — warn when a job references `$VAR` (or `${VAR}`) that is not declared anywhere in `variables:`, `default.variables`, or the job itself
-- **`services:` validation** — map form requires `name`; `alias` must be a valid DNS label
-- **`rules:changes` / `rules:exists`** — warn on glob patterns that can never match (e.g. absolute paths, double `**` on unsupported versions)
-- **`timeout` format** — must be a duration string GitLab understands (`1h 30m`, `90 minutes`, etc.)
-- **`id_tokens:` / `secrets:`** — presence and required-key checks
-- **`pages:publish`** — validate that the path is consistent with `artifacts.paths`
+- ~~**Variable reference validation (GL032)**~~ — ✓ shipped v0.2.11; warns when a `rules:if:` expression references `$VAR` / `${VAR}` not declared anywhere in pipeline YAML; predefined GitLab namespaces (`CI_*`, `GITLAB_*`, …) exempt; variables from included files are also considered
+- ~~**`rules:if:` static reachability (GL033)**~~ — ✓ shipped v0.2.15; warns when every rule in a job's `rules:` block has `when: never`, making the job permanently excluded from any pipeline run; no `if:` evaluation required
+- ~~**`services:` validation (GL034)**~~ — ✓ shipped v0.2.16; map form requires `name`; `alias` must be a valid DNS label
+- ~~**`rules:changes` / `rules:exists` absolute path detection (GL035)**~~ — ✓ shipped v0.2.16; warns when a path starts with `/`; GitLab CI paths are always relative to the repo root
+- ~~**`timeout` format validation (GL036)**~~ — ✓ shipped v0.2.16; validates job-level and `default.timeout` against recognised GitLab CI duration strings
+- ~~**`id_tokens:` / `secrets:` required-key checks (GL037, GL038)**~~ — ✓ shipped v0.2.16; `id_tokens` entries must have `aud`; `secrets` entries must declare a provider
+- ~~**`pages:publish` + `artifacts.paths` consistency (GL039)**~~ — ✓ shipped v0.2.16; warns when the publish directory is missing from `artifacts.paths`
+- ~~**Duplicate stage names (GL040)**~~ — ✓ shipped v0.2.16; warns when a stage appears more than once in `stages:`
+- ~~**`cache:key:files` must be exact paths (GL041)**~~ — ✓ shipped v0.2.16; warns when entries look like glob patterns
+- ~~**Unreachable jobs**~~ — covered by GL033 (shipped v0.2.15); every-`when:never` rules block is statically dead
 - **`inherit:` completeness** — flag when a job overrides a default field that would require `inherit: default: false` to suppress
-- **Unreachable jobs** — detect jobs that can never run because every `rules:` branch evaluates to `never` (static analysis only, no variable expansion)
-- **Duplicate stage names** — GitLab silently merges them; warn to avoid confusion
-- **`cache:key:files`** — must be a list of paths, not a glob
 
 ---
 
 ## Include resolution
 
-- **`include: local:`** full resolution — parse and merge locally-referenced YAML files the same way remote project includes are handled; enables cross-file `extends:` and `needs:` validation for monorepo setups
-- **`include: remote:`** (URL) — fetch and merge plain HTTP/HTTPS URLs (no auth required)
-- **Recursive include depth limit** — guard against include cycles across files
-- **Offline mode / cache** — persist fetched remote templates to a local cache directory; `--offline` flag to skip network calls and use only cached copies
-- **`include: inputs:`** — substitute CI component input values into fetched templates before merging, so component-scoped jobs get their correct `stage:` and keyword values
+- ~~**`include: local:`** full resolution~~ — ✓ shipped in v0.2.0; local files are read from disk, recursively resolved, and merged before linting
+- ~~**`include: remote:`** (URL)~~ — ✓ shipped post-v0.2.0; plain HTTPS URLs are fetched (unauthenticated), parsed, and merged; sub-includes are resolved recursively; unreachable URLs emit `[WARNING]` and linting continues
+- ~~**Recursive include depth limit**~~ — ✓ shipped v0.2.17; depth capped at 100 (matching GitLab); project/component includes now tracked in visited set to prevent cross-file cycles
+- ~~**Offline mode / cache**~~ — ✓ shipped v0.2.17; `--cache-dir DIR` persists fetched templates; `--offline` serves from cache only; default cache dir (`~/.cache/glint`) used automatically with `--offline`
+- ~~**`include: inputs:`**~~ — ✓ shipped v0.2.17; `$[[ inputs.KEY ]]` and `$[[ inputs.KEY | default(…) ]]` placeholders in fetched component YAML are substituted from the include's `with:` block before parsing
 
 ---
 
-## Output formats
+## Output formats — ✓ shipped v0.2.18
 
-Right now the only output is plain-text findings. Structured output enables integration with other tools.
-
-- **JSON** (`--format json`) — machine-readable findings with file, job, severity, rule ID, and message; stable schema
-- **SARIF** (`--format sarif`) — [Static Analysis Results Interchange Format](https://sarifweb.azurewebsites.net); consumed natively by GitHub Code Scanning and GitLab SAST
-- **JUnit XML** (`--format junit`) — lets CI pipelines publish lint results as a test report artifact
-- **GitHub / GitLab annotation format** — emit `::error file=…,line=…::message` lines so findings appear as inline comments in PR diffs
+- ~~**JSON** (`--format json`)~~ — ✓ shipped v0.2.18; machine-readable findings with stable schema (version 1)
+- ~~**SARIF** (`--format sarif`)~~ — ✓ shipped v0.2.18; SARIF 2.1.0; consumed natively by GitHub Code Scanning and GitLab SAST
+- ~~**JUnit XML** (`--format junit`)~~ — ✓ shipped v0.2.18; lets CI pipelines publish lint results as a test report artifact
+- ~~**GitHub annotation format** (`--format github`)~~ — ✓ shipped v0.2.18; emits `::error file=…,line=…,title=RULE::message` lines so findings appear as inline comments in PR diffs
 
 ---
 
 ## Pipeline graph improvements
 
-The SVG renderer covers the basic layout. These would bring it closer to GitLab's full interactive view.
+The SVG renderer and terminal tree cover the basic layout. These would bring it closer to GitLab's full interactive view.
 
+- ~~**Terminal job tree**~~ — ✓ shipped in v0.2.0 as `glint graph tree`; stages as branches, jobs as leaves, context-aware annotations
+- ~~**`glint graph includes` shows jobs per file**~~ — ✓ shipped post-v0.2.0; each include node shows the jobs it defines as dashed-arrow rounded nodes in a distinct style
 - **Multi-job connector accuracy** — draw one connector per job pair rather than one per stage pair in classic mode, so pipelines with uneven columns look correct
 - **Job tooltip / detail panel** — embed a hidden `<title>` and `<desc>` per chip so SVG viewers show `stage`, `when`, `image`, and `needs` on hover
 - **`when: on_failure` visual distinction** — dashed border or distinct icon for failure-path jobs
@@ -110,6 +108,20 @@ The SVG renderer covers the basic layout. These would bring it closer to GitLab'
 
 ---
 
+## Findings quality — ✓ file and line numbers shipped post-v0.2.0; ruff-style format shipped v0.2.11
+
+~~**File and line numbers on findings**~~ — ✓ shipped post-v0.2.0; every finding includes the source file and exact line of the job key. Works across local includes, remote project templates, and fetched component templates.
+
+~~**Ruff-style output format**~~ — ✓ shipped v0.2.11; findings follow `file:line: RULEID [severity] message` matching the convention used by ruff and other modern linters.
+
+**Remaining improvements**
+
+- ~~**`needs: optional: true` false-positive errors**~~ — ✓ shipped post-v0.2.0; optional missing needs are downgraded to `[WARNING]`
+- ~~**`extends:` jobs with missing script false errors**~~ — ✓ shipped post-v0.2.0; jobs using `extends:` that have no `script` after resolution emit `[WARNING]` (the script may come from an unfetchable remote base)
+- **`rules:if:` static reachability** — report when a job's entire `rules:` block can never evaluate to `when: on_success` given the declared pipeline variables (pure static, no context required)
+
+---
+
 ## CI / editor integration
 
 - **GitLab CI template** — a `.gitlab-ci.yml` snippet that runs `glint` as a pipeline-validation job before the real pipeline executes; publishable to the GitLab CI/CD Catalog
@@ -120,21 +132,18 @@ The SVG renderer covers the basic layout. These would bring it closer to GitLab'
 
 ---
 
-## Configuration
+## Configuration — ✓ shipped v0.2.19
 
-- **`.glint.yml` config file** — project-level configuration for:
-  - Rule suppression by rule ID (e.g. `ignore: [no-only, missing-stages]`)
-  - Severity overrides (demote specific errors to warnings)
-  - Custom `stages` allowlist for projects that use a non-standard default set
-  - Token and URL defaults so flags are not needed in every invocation
-- **Inline suppression comments** — `# glint: ignore next-line <rule-id>` in the pipeline YAML
+- ~~**`.glint.yml` config file**~~ — ✓ shipped v0.2.19; `ignore:`, `severity:`, `stages:`, `token:`, `url:`, `cache_dir:`; searched from the pipeline directory up to the git root
+- ~~**Inline suppression comments**~~ — ✓ shipped v0.2.19; `# glint: ignore GL007` before a job definition; comma/space-separated rules; `# glint: ignore all` wildcard
 
 ---
 
 ## Reliability and developer experience
 
-- **Structured rule IDs** — assign a stable short ID to every rule (e.g. `GS001`) so suppression, documentation, and SARIF output are stable across versions
+- ~~**Structured rule IDs**~~ — ✓ shipped post-v0.2.0; GL001–GL031 assigned; GL032 added v0.2.11; GL033 added v0.2.15; GL034–GL041 added v0.2.16; output formats (--format json/sarif/junit/github) added v0.2.18
 - **`--explain <rule-id>`** — print the rule description, rationale, and an example fix
 - ~~**Semantic versioning and first release**~~ — shipped as `v0.1.0` (2026-06-07)
+- ~~**Subcommand CLI**~~ — shipped as `v0.2.0` (2026-06-11); `glint check` / `glint graph [mode]` with ruff-style `--help`
 - **Changelog automation** — generate release notes from Conventional Commits via `git-cliff` or similar
 - **Fuzz testing** — add a `go test -fuzz` target for the YAML parser to harden it against malformed input

Taskfile.yml

@@ -3,6 +3,8 @@ version: "3"
 vars:
   BINARY: glint
   GO: /usr/local/go/bin/go
+  VERSION:
+    sh: git describe --tags --always --dirty 2>/dev/null || echo "dev"
 
 tasks:
   default:
@@ -12,7 +14,7 @@ tasks:
   build:
     desc: Build the glint binary
     cmds:
-      - "{{.GO}} build -o {{.BINARY}} ./cmd/glint/..."
+      - "{{.GO}} build -ldflags \"-X main.version={{.VERSION}}\" -o {{.BINARY}} ./cmd/glint/..."
     sources:
       - "**/*.go"
       - go.mod
@@ -27,43 +29,98 @@ tasks:
     desc: Run glint against all testdata fixtures
     deps: [build]
     cmds:
-      - cmd: ./{{.BINARY}} testdata/valid.yml
+      - cmd: ./{{.BINARY}} check testdata/valid.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} testdata/extends.yml
+      - cmd: ./{{.BINARY}} check testdata/extends.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} testdata/keywords_valid.yml
+      - cmd: ./{{.BINARY}} check testdata/keywords_valid.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} testdata/invalid.yml
+      - cmd: ./{{.BINARY}} check testdata/invalid.yml
         ignore_error: true
-      - cmd: ./{{.BINARY}} testdata/needs.yml
+      - cmd: ./{{.BINARY}} check testdata/needs.yml
         ignore_error: true
-      - cmd: ./{{.BINARY}} testdata/needs_cycle.yml
+      - cmd: ./{{.BINARY}} check testdata/needs_cycle.yml
         ignore_error: true
-      - cmd: ./{{.BINARY}} testdata/keywords_invalid.yml
+      - cmd: ./{{.BINARY}} check testdata/keywords_invalid.yml
         ignore_error: true
-      - cmd: ./{{.BINARY}} testdata/includes_project.yml
+      - cmd: ./{{.BINARY}} check testdata/includes_remote.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} testdata/includes_component.yml
+      - cmd: ./{{.BINARY}} check testdata/includes_project.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} testdata/context_rules.yml
+      - cmd: ./{{.BINARY}} check testdata/includes_component.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} --branch main testdata/context_rules.yml
+      - cmd: ./{{.BINARY}} check testdata/script_multiline.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} --branch develop testdata/context_rules.yml
+      - cmd: ./{{.BINARY}} check testdata/context_rules.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} --branch feat/my-feature testdata/context_rules.yml
+      - cmd: ./{{.BINARY}} check --branch main testdata/context_rules.yml
         ignore_error: false
-      - cmd: ./{{.BINARY}} --tag v1.0.0 testdata/context_rules.yml
+      - cmd: ./{{.BINARY}} check --branch develop testdata/context_rules.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --branch feat/my-feature testdata/context_rules.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --tag v1.0.0 testdata/context_rules.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/rules_if_expr.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --branch main testdata/rules_if_expr.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --branch feat/x testdata/rules_if_expr.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/workflow_vars.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --branch main testdata/workflow_vars.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --branch develop testdata/workflow_vars.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --branch feat/x testdata/workflow_vars.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/workflow_escape.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/variable_refs.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/variable_refs_included.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/dead_rules.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/new_rules_valid.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/new_rules_invalid.yml
+        ignore_error: true
+      - cmd: ./{{.BINARY}} check testdata/samba/.gitlab-ci.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/samba/.gitlab-ci-coverage.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/samba/.gitlab-ci-private.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --format json testdata/valid.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --format sarif testdata/valid.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --format junit testdata/valid.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check --format github testdata/invalid.yml
+        ignore_error: true
+      - cmd: ./{{.BINARY}} check testdata/config_ignored/.gitlab-ci.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/config_severity/.gitlab-ci.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/config_suppress/.gitlab-ci.yml
         ignore_error: false
 
   lint-go:
     desc: Run go vet on all packages
     cmd: "{{.GO}} vet ./..."
 
+  lint-static:
+    desc: Run staticcheck on all packages
+    cmd: "{{.GO}} tool staticcheck ./..."
+
   ci:
-    desc: Full CI check — vet, test, build, validate
+    desc: Full CI check — vet, staticcheck, test, build, validate
     cmds:
       - task: lint-go
+      - task: lint-static
       - task: test
       - task: build
       - task: validate
@@ -77,7 +134,7 @@ tasks:
       - sh: git describe --tags --exact-match
         msg: "Current commit is not tagged — Windows build requires a git tag"
     cmds:
-      - "GOOS=windows GOARCH=amd64 {{.GO}} build -o {{.BINARY}}-{{.TAG}}.exe ./cmd/glint/..."
+      - "GOOS=windows GOARCH=amd64 {{.GO}} build -ldflags \"-X main.version={{.TAG}}\" -o {{.BINARY}}-{{.TAG}}.exe ./cmd/glint/..."
     sources:
       - "**/*.go"
       - go.mod
@@ -93,7 +150,7 @@ tasks:
       - sh: git describe --tags --exact-match
         msg: "Current commit is not tagged — Linux build requires a git tag"
     cmds:
-      - "GOOS=linux GOARCH=amd64 {{.GO}} build -o {{.BINARY}}-{{.TAG}}-linux-amd64 ./cmd/glint/..."
+      - "GOOS=linux GOARCH=amd64 {{.GO}} build -ldflags \"-X main.version={{.TAG}}\" -o {{.BINARY}}-{{.TAG}}-linux-amd64 ./cmd/glint/..."
     sources:
       - "**/*.go"
       - go.mod

cmd/glint/filter.go

@@ -0,0 +1,87 @@
+package main
+
+import (
+	"strings"
+
+	"git.k3nny.fr/glint/internal/config"
+	"git.k3nny.fr/glint/internal/linter"
+)
+
+// applyConfig filters and adjusts findings according to the project config
+// and inline suppression comments parsed from the pipeline YAML.
+//
+// Processing order:
+//  1. Build a combined ignore set from config.Ignore and any severity entry
+//     whose value is "ignore".
+//  2. Drop findings whose rule is in the ignore set.
+//  3. Drop findings suppressed by an inline "# glint: ignore" comment on the
+//     job definition (from p.Suppressions).
+//  4. Apply severity overrides ("error" / "warning") from config.Severity.
+func applyConfig(findings []linter.Finding, cfg config.Config, suppressions map[string][]string) []linter.Finding {
+	// Build the global ignore set (uppercased rule IDs).
+	ignoreSet := make(map[string]bool, len(cfg.Ignore))
+	for _, r := range cfg.Ignore {
+		ignoreSet[strings.ToUpper(r)] = true
+	}
+	// Severity entries with value "ignore" are equivalent to Ignore entries.
+	sevMap := make(map[string]string, len(cfg.Severity)) // upperRule → lowerLevel
+	for rule, sev := range cfg.Severity {
+		upper := strings.ToUpper(rule)
+		lower := strings.ToLower(sev)
+		sevMap[upper] = lower
+		if lower == "ignore" {
+			ignoreSet[upper] = true
+		}
+	}
+
+	if len(ignoreSet) == 0 && len(sevMap) == 0 && len(suppressions) == 0 {
+		return findings
+	}
+
+	kept := findings[:0:0] // reuse underlying array but return fresh slice
+	for _, f := range findings {
+		ruleUpper := strings.ToUpper(f.Rule)
+
+		// Global ignore.
+		if ignoreSet[ruleUpper] {
+			continue
+		}
+
+		// Inline suppression.
+		if isSuppressed(f.Job, ruleUpper, suppressions) {
+			continue
+		}
+
+		// Severity override.
+		if level, ok := sevMap[ruleUpper]; ok {
+			switch level {
+			case "error":
+				f.Severity = linter.Error
+			case "warning":
+				f.Severity = linter.Warning
+			}
+		}
+
+		kept = append(kept, f)
+	}
+	return kept
+}
+
+// isSuppressed reports whether jobName has a "# glint: ignore" directive that
+// covers ruleUpper. The wildcard entry "*" (from "# glint: ignore all")
+// suppresses every rule.
+func isSuppressed(jobName, ruleUpper string, suppressions map[string][]string) bool {
+	if jobName == "" || len(suppressions) == 0 {
+		return false
+	}
+	rules, ok := suppressions[jobName]
+	if !ok {
+		return false
+	}
+	for _, r := range rules {
+		if r == "*" || r == ruleUpper {
+			return true
+		}
+	}
+	return false
+}

cmd/glint/filter_test.go

@@ -0,0 +1,116 @@
+package main
+
+import (
+	"testing"
+
+	"git.k3nny.fr/glint/internal/config"
+	"git.k3nny.fr/glint/internal/linter"
+)
+
+func TestApplyConfig(t *testing.T) {
+	findings := []linter.Finding{
+		{Severity: linter.Error, Rule: "GL004", Job: "deploy", File: "ci.yml", Line: 10, Message: "bad stage"},
+		{Severity: linter.Warning, Rule: "GL007", Job: "old-job", File: "ci.yml", Line: 20, Message: "deprecated"},
+		{Severity: linter.Warning, Rule: "GL032", Job: "check", File: "ci.yml", Line: 30, Message: "var ref"},
+	}
+
+	t.Run("no config — pass through", func(t *testing.T) {
+		got := applyConfig(findings, config.Config{}, nil)
+		if len(got) != 3 {
+			t.Errorf("got %d findings, want 3", len(got))
+		}
+	})
+
+	t.Run("ignore GL007", func(t *testing.T) {
+		cfg := config.Config{Ignore: []string{"GL007"}}
+		got := applyConfig(findings, cfg, nil)
+		if len(got) != 2 {
+			t.Fatalf("got %d findings, want 2", len(got))
+		}
+		for _, f := range got {
+			if f.Rule == "GL007" {
+				t.Error("GL007 should be suppressed")
+			}
+		}
+	})
+
+	t.Run("ignore case-insensitive", func(t *testing.T) {
+		cfg := config.Config{Ignore: []string{"gl007"}}
+		got := applyConfig(findings, cfg, nil)
+		if len(got) != 2 {
+			t.Fatalf("got %d, want 2", len(got))
+		}
+	})
+
+	t.Run("severity demote error to warning", func(t *testing.T) {
+		cfg := config.Config{Severity: map[string]string{"GL004": "warning"}}
+		got := applyConfig(findings, cfg, nil)
+		if len(got) != 3 {
+			t.Fatalf("got %d findings, want 3", len(got))
+		}
+		if got[0].Severity != linter.Warning {
+			t.Errorf("GL004 severity = %s, want WARNING", got[0].Severity)
+		}
+	})
+
+	t.Run("severity promote warning to error", func(t *testing.T) {
+		cfg := config.Config{Severity: map[string]string{"GL007": "error"}}
+		got := applyConfig(findings, cfg, nil)
+		if got[1].Severity != linter.Error {
+			t.Errorf("GL007 severity = %s, want ERROR", got[1].Severity)
+		}
+	})
+
+	t.Run("severity ignore is equivalent to ignore list", func(t *testing.T) {
+		cfg := config.Config{Severity: map[string]string{"GL032": "ignore"}}
+		got := applyConfig(findings, cfg, nil)
+		if len(got) != 2 {
+			t.Fatalf("got %d, want 2", len(got))
+		}
+		for _, f := range got {
+			if f.Rule == "GL032" {
+				t.Error("GL032 should be suppressed via severity=ignore")
+			}
+		}
+	})
+
+	t.Run("inline suppression by job", func(t *testing.T) {
+		suppressions := map[string][]string{
+			"old-job": {"GL007"},
+		}
+		got := applyConfig(findings, config.Config{}, suppressions)
+		if len(got) != 2 {
+			t.Fatalf("got %d, want 2", len(got))
+		}
+		for _, f := range got {
+			if f.Job == "old-job" && f.Rule == "GL007" {
+				t.Error("old-job GL007 should be suppressed")
+			}
+		}
+	})
+
+	t.Run("inline suppression wildcard", func(t *testing.T) {
+		suppressions := map[string][]string{
+			"old-job": {"*"},
+		}
+		got := applyConfig(findings, config.Config{}, suppressions)
+		// old-job had GL007; should be gone
+		if len(got) != 2 {
+			t.Fatalf("got %d, want 2", len(got))
+		}
+	})
+
+	t.Run("pipeline-level findings not suppressed by job comment", func(t *testing.T) {
+		pipelineFindings := []linter.Finding{
+			{Severity: linter.Error, Rule: "GL001", Job: "", File: "ci.yml", Line: 0, Message: "no stages"},
+		}
+		suppressions := map[string][]string{
+			"": {"GL001"}, // empty job key should not match pipeline-level
+		}
+		got := applyConfig(pipelineFindings, config.Config{}, suppressions)
+		// Pipeline-level findings (f.Job == "") are never suppressed by job comments.
+		if len(got) != 1 {
+			t.Errorf("got %d, want 1 (pipeline-level finding must not be suppressed)", len(got))
+		}
+	})
+}

cmd/glint/format.go

@@ -0,0 +1,332 @@
+package main
+
+import (
+	"encoding/json"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"strings"
+
+	"git.k3nny.fr/glint/internal/linter"
+)
+
+// --- JSON ---
+
+type jsonReport struct {
+	SchemaVersion int           `json:"schema_version"`
+	GlintVersion  string        `json:"glint_version"`
+	Pipeline      string        `json:"pipeline"`
+	Findings      []jsonFinding `json:"findings"`
+	Summary       jsonSummary   `json:"summary"`
+}
+
+type jsonFinding struct {
+	Rule     string `json:"rule,omitempty"`
+	Severity string `json:"severity"`
+	File     string `json:"file,omitempty"`
+	Line     int    `json:"line,omitempty"`
+	Job      string `json:"job,omitempty"`
+	Message  string `json:"message"`
+}
+
+type jsonSummary struct {
+	Total    int `json:"total"`
+	Errors   int `json:"errors"`
+	Warnings int `json:"warnings"`
+}
+
+func writeJSON(w io.Writer, findings []linter.Finding, pipeline string) {
+	errs, warns := countSeverities(findings)
+	jf := make([]jsonFinding, 0, len(findings))
+	for _, f := range findings {
+		jf = append(jf, jsonFinding{
+			Rule:     f.Rule,
+			Severity: strings.ToLower(string(f.Severity)),
+			File:     f.File,
+			Line:     f.Line,
+			Job:      f.Job,
+			Message:  f.Message,
+		})
+	}
+	report := jsonReport{
+		SchemaVersion: 1,
+		GlintVersion:  version,
+		Pipeline:      pipeline,
+		Findings:      jf,
+		Summary:       jsonSummary{Total: len(findings), Errors: errs, Warnings: warns},
+	}
+	enc := json.NewEncoder(w)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(report)
+}
+
+// --- SARIF 2.1.0 ---
+
+type sarifLog struct {
+	Schema  string     `json:"$schema"`
+	Version string     `json:"version"`
+	Runs    []sarifRun `json:"runs"`
+}
+
+type sarifRun struct {
+	Tool    sarifTool     `json:"tool"`
+	Results []sarifResult `json:"results"`
+}
+
+type sarifTool struct {
+	Driver sarifDriver `json:"driver"`
+}
+
+type sarifDriver struct {
+	Name           string      `json:"name"`
+	Version        string      `json:"version"`
+	InformationURI string      `json:"informationUri"`
+	Rules          []sarifRule `json:"rules"`
+}
+
+type sarifRule struct {
+	ID               string       `json:"id"`
+	ShortDescription sarifMessage `json:"shortDescription"`
+	HelpURI          string       `json:"helpUri,omitempty"`
+}
+
+type sarifMessage struct {
+	Text string `json:"text"`
+}
+
+type sarifResult struct {
+	RuleID    string          `json:"ruleId,omitempty"`
+	Level     string          `json:"level"`
+	Message   sarifMessage    `json:"message"`
+	Locations []sarifLocation `json:"locations,omitempty"`
+}
+
+type sarifLocation struct {
+	PhysicalLocation sarifPhysLoc `json:"physicalLocation"`
+}
+
+type sarifPhysLoc struct {
+	ArtifactLocation sarifArtifact `json:"artifactLocation"`
+	Region           *sarifRegion  `json:"region,omitempty"`
+}
+
+type sarifArtifact struct {
+	URI       string `json:"uri"`
+	URIBaseID string `json:"uriBaseId,omitempty"`
+}
+
+type sarifRegion struct {
+	StartLine int `json:"startLine"`
+}
+
+func writeSARIF(w io.Writer, findings []linter.Finding, _ string) {
+	// Collect unique rule IDs (preserving first-seen order).
+	seenRules := map[string]bool{}
+	var rules []sarifRule
+	for _, f := range findings {
+		if f.Rule != "" && !seenRules[f.Rule] {
+			seenRules[f.Rule] = true
+			rules = append(rules, sarifRule{
+				ID:               f.Rule,
+				ShortDescription: sarifMessage{Text: "glint rule " + f.Rule},
+				HelpURI:          "https://git.k3nny.fr/glint",
+			})
+		}
+	}
+	if rules == nil {
+		rules = []sarifRule{}
+	}
+
+	var results []sarifResult
+	for _, f := range findings {
+		level := "warning"
+		if f.Severity == linter.Error {
+			level = "error"
+		}
+		msg := f.Message
+		if f.Job != "" {
+			msg = fmt.Sprintf("job %q: %s", f.Job, msg)
+		}
+		result := sarifResult{
+			RuleID:  f.Rule,
+			Level:   level,
+			Message: sarifMessage{Text: msg},
+		}
+		if f.File != "" {
+			loc := sarifLocation{
+				PhysicalLocation: sarifPhysLoc{
+					ArtifactLocation: sarifArtifact{URI: f.File, URIBaseID: "%SRCROOT%"},
+				},
+			}
+			if f.Line > 0 {
+				loc.PhysicalLocation.Region = &sarifRegion{StartLine: f.Line}
+			}
+			result.Locations = []sarifLocation{loc}
+		}
+		results = append(results, result)
+	}
+	if results == nil {
+		results = []sarifResult{}
+	}
+
+	log := sarifLog{
+		Schema:  "https://json.schemastore.org/sarif-2.1.0.json",
+		Version: "2.1.0",
+		Runs: []sarifRun{{
+			Tool: sarifTool{Driver: sarifDriver{
+				Name:           "glint",
+				Version:        strings.TrimPrefix(version, "v"),
+				InformationURI: "https://git.k3nny.fr/glint",
+				Rules:          rules,
+			}},
+			Results: results,
+		}},
+	}
+	enc := json.NewEncoder(w)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(log)
+}
+
+// --- JUnit XML ---
+
+type junitTestsuites struct {
+	XMLName  xml.Name         `xml:"testsuites"`
+	Name     string           `xml:"name,attr"`
+	Tests    int              `xml:"tests,attr"`
+	Failures int              `xml:"failures,attr"`
+	Time     string           `xml:"time,attr"`
+	Suites   []junitTestsuite `xml:"testsuite"`
+}
+
+type junitTestsuite struct {
+	Name     string          `xml:"name,attr"`
+	Tests    int             `xml:"tests,attr"`
+	Failures int             `xml:"failures,attr"`
+	Time     string          `xml:"time,attr"`
+	Cases    []junitTestcase `xml:"testcase"`
+}
+
+type junitTestcase struct {
+	Name      string        `xml:"name,attr"`
+	Classname string        `xml:"classname,attr"`
+	Failure   *junitFailure `xml:"failure,omitempty"`
+}
+
+type junitFailure struct {
+	Message string `xml:"message,attr"`
+	Type    string `xml:"type,attr"`
+	Body    string `xml:",chardata"`
+}
+
+func writeJUnit(w io.Writer, findings []linter.Finding, pipeline string) {
+	_, fails := countSeverities(findings)
+	_ = fails // re-derive below to count both errors and warnings as failures
+
+	var cases []junitTestcase
+	if len(findings) == 0 {
+		cases = []junitTestcase{{Name: "no issues found", Classname: pipeline}}
+	} else {
+		for _, f := range findings {
+			name := f.Rule
+			if name == "" {
+				name = "lint"
+			}
+			classname := f.File
+			if classname == "" {
+				classname = pipeline
+			}
+			if f.Job != "" {
+				classname += "#" + f.Job
+			}
+			msg := f.Message
+			if f.Job != "" {
+				msg = fmt.Sprintf("job %q: %s", f.Job, msg)
+			}
+			cases = append(cases, junitTestcase{
+				Name:      name,
+				Classname: classname,
+				Failure: &junitFailure{
+					Message: msg,
+					Type:    strings.ToLower(string(f.Severity)),
+					Body:    f.String(),
+				},
+			})
+		}
+	}
+
+	suite := junitTestsuite{
+		Name:     pipeline,
+		Tests:    len(cases),
+		Failures: len(findings), // all findings are failures
+		Time:     "0",
+		Cases:    cases,
+	}
+	suites := junitTestsuites{
+		Name:     "glint",
+		Tests:    len(cases),
+		Failures: len(findings),
+		Time:     "0",
+		Suites:   []junitTestsuite{suite},
+	}
+
+	fmt.Fprint(w, `<?xml version="1.0" encoding="UTF-8"?>`)
+	fmt.Fprintln(w)
+	enc := xml.NewEncoder(w)
+	enc.Indent("", "  ")
+	_ = enc.Encode(suites)
+	_ = enc.Flush()
+	fmt.Fprintln(w)
+}
+
+// --- GitHub Actions annotations ---
+
+// writeGitHub emits GitHub Actions workflow command annotation lines.
+// Each finding becomes an ::error:: or ::warning:: line that GitHub CI
+// renders as an inline comment on the relevant file in pull requests.
+func writeGitHub(w io.Writer, findings []linter.Finding) {
+	for _, f := range findings {
+		level := "warning"
+		if f.Severity == linter.Error {
+			level = "error"
+		}
+		msg := f.Message
+		if f.Job != "" {
+			msg = fmt.Sprintf("job %q: %s", f.Job, msg)
+		}
+		// GitHub annotation messages must not contain raw newlines, percent signs,
+		// carriage returns, or colons in the parameter block.
+		msg = strings.ReplaceAll(msg, "%", "%25")
+		msg = strings.ReplaceAll(msg, "\r", "%0D")
+		msg = strings.ReplaceAll(msg, "\n", "%0A")
+
+		var params []string
+		if f.File != "" {
+			params = append(params, "file="+f.File)
+			if f.Line > 0 {
+				params = append(params, fmt.Sprintf("line=%d", f.Line))
+			}
+		}
+		if f.Rule != "" {
+			params = append(params, "title="+f.Rule)
+		}
+
+		paramStr := ""
+		if len(params) > 0 {
+			paramStr = " " + strings.Join(params, ",")
+		}
+		fmt.Fprintf(w, "::%s%s::%s\n", level, paramStr, msg)
+	}
+}
+
+// --- shared helpers ---
+
+func countSeverities(findings []linter.Finding) (errors, warnings int) {
+	for _, f := range findings {
+		if f.Severity == linter.Error {
+			errors++
+		} else {
+			warnings++
+		}
+	}
+	return
+}

cmd/glint/format_test.go

@@ -0,0 +1,228 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"encoding/xml"
+	"strings"
+	"testing"
+
+	"git.k3nny.fr/glint/internal/linter"
+)
+
+var testFindings = []linter.Finding{
+	{
+		Severity: linter.Error,
+		Rule:     "GL004",
+		Job:      "deploy",
+		File:     ".gitlab-ci.yml",
+		Line:     14,
+		Message:  `stage "production" is not defined in 'stages'`,
+	},
+	{
+		Severity: linter.Warning,
+		Rule:     "GL007",
+		Job:      "old-job",
+		File:     ".gitlab-ci.yml",
+		Line:     31,
+		Message:  "'only'/'except' are deprecated; prefer 'rules'",
+	},
+}
+
+func TestWriteJSON(t *testing.T) {
+	t.Run("findings", func(t *testing.T) {
+		var buf bytes.Buffer
+		writeJSON(&buf, testFindings, ".gitlab-ci.yml")
+
+		var got jsonReport
+		if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+			t.Fatalf("invalid JSON: %v", err)
+		}
+		if got.SchemaVersion != 1 {
+			t.Errorf("schema_version = %d, want 1", got.SchemaVersion)
+		}
+		if len(got.Findings) != 2 {
+			t.Fatalf("got %d findings, want 2", len(got.Findings))
+		}
+		if got.Summary.Errors != 1 || got.Summary.Warnings != 1 {
+			t.Errorf("summary = %+v, want {2,1,1}", got.Summary)
+		}
+		if got.Findings[0].Rule != "GL004" || got.Findings[0].Severity != "error" {
+			t.Errorf("finding[0] = %+v", got.Findings[0])
+		}
+		if got.Findings[0].Job != "deploy" || got.Findings[0].Line != 14 {
+			t.Errorf("finding[0] job/line = %s/%d", got.Findings[0].Job, got.Findings[0].Line)
+		}
+	})
+
+	t.Run("empty", func(t *testing.T) {
+		var buf bytes.Buffer
+		writeJSON(&buf, nil, "ci.yml")
+
+		var got jsonReport
+		if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+			t.Fatalf("invalid JSON: %v", err)
+		}
+		if got.Findings == nil {
+			t.Error("findings must be [] not null")
+		}
+		if got.Summary.Total != 0 {
+			t.Errorf("total = %d, want 0", got.Summary.Total)
+		}
+	})
+}
+
+func TestWriteSARIF(t *testing.T) {
+	t.Run("findings", func(t *testing.T) {
+		var buf bytes.Buffer
+		writeSARIF(&buf, testFindings, ".gitlab-ci.yml")
+
+		var got sarifLog
+		if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+			t.Fatalf("invalid JSON: %v", err)
+		}
+		if got.Version != "2.1.0" {
+			t.Errorf("version = %q, want 2.1.0", got.Version)
+		}
+		if len(got.Runs) != 1 {
+			t.Fatalf("runs count = %d, want 1", len(got.Runs))
+		}
+		run := got.Runs[0]
+		if run.Tool.Driver.Name != "glint" {
+			t.Errorf("driver.name = %q", run.Tool.Driver.Name)
+		}
+		if len(run.Results) != 2 {
+			t.Fatalf("results count = %d, want 2", len(run.Results))
+		}
+		r0 := run.Results[0]
+		if r0.RuleID != "GL004" || r0.Level != "error" {
+			t.Errorf("result[0] ruleId/level = %s/%s", r0.RuleID, r0.Level)
+		}
+		if len(r0.Locations) != 1 {
+			t.Fatalf("result[0] locations count = %d, want 1", len(r0.Locations))
+		}
+		loc := r0.Locations[0].PhysicalLocation
+		if loc.ArtifactLocation.URI != ".gitlab-ci.yml" {
+			t.Errorf("artifactLocation.uri = %q", loc.ArtifactLocation.URI)
+		}
+		if loc.Region == nil || loc.Region.StartLine != 14 {
+			t.Errorf("region = %v", loc.Region)
+		}
+		// Message should include job name prefix.
+		if !strings.Contains(r0.Message.Text, `job "deploy"`) {
+			t.Errorf("message missing job prefix: %q", r0.Message.Text)
+		}
+	})
+
+	t.Run("empty", func(t *testing.T) {
+		var buf bytes.Buffer
+		writeSARIF(&buf, nil, "ci.yml")
+
+		var got sarifLog
+		if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+			t.Fatalf("invalid JSON: %v", err)
+		}
+		run := got.Runs[0]
+		if run.Results == nil {
+			t.Error("results must be [] not null")
+		}
+		if run.Tool.Driver.Rules == nil {
+			t.Error("rules must be [] not null")
+		}
+	})
+}
+
+func TestWriteJUnit(t *testing.T) {
+	t.Run("findings", func(t *testing.T) {
+		var buf bytes.Buffer
+		writeJUnit(&buf, testFindings, ".gitlab-ci.yml")
+
+		if !strings.HasPrefix(buf.String(), "<?xml") {
+			t.Error("output does not start with XML declaration")
+		}
+
+		var got junitTestsuites
+		if err := xml.Unmarshal(buf.Bytes(), &got); err != nil {
+			t.Fatalf("invalid XML: %v\noutput:\n%s", err, buf.String())
+		}
+		if got.Failures != 2 {
+			t.Errorf("failures = %d, want 2", got.Failures)
+		}
+		if len(got.Suites) != 1 {
+			t.Fatalf("suites count = %d, want 1", len(got.Suites))
+		}
+		suite := got.Suites[0]
+		if len(suite.Cases) != 2 {
+			t.Fatalf("test cases count = %d, want 2", len(suite.Cases))
+		}
+		if suite.Cases[0].Name != "GL004" {
+			t.Errorf("case[0].name = %q", suite.Cases[0].Name)
+		}
+		if suite.Cases[0].Failure == nil {
+			t.Error("case[0] has no failure element")
+		}
+	})
+
+	t.Run("empty_is_passing", func(t *testing.T) {
+		var buf bytes.Buffer
+		writeJUnit(&buf, nil, "ci.yml")
+
+		var got junitTestsuites
+		if err := xml.Unmarshal(buf.Bytes(), &got); err != nil {
+			t.Fatalf("invalid XML: %v", err)
+		}
+		if got.Failures != 0 {
+			t.Errorf("failures = %d, want 0", got.Failures)
+		}
+		suite := got.Suites[0]
+		if len(suite.Cases) != 1 || suite.Cases[0].Failure != nil {
+			t.Error("expected exactly one passing testcase when no findings")
+		}
+	})
+}
+
+func TestWriteGitHub(t *testing.T) {
+	cases := []struct {
+		name     string
+		findings []linter.Finding
+		wantLine string
+	}{
+		{
+			name:     "error with file and line",
+			findings: []linter.Finding{testFindings[0]},
+			wantLine: "::error file=.gitlab-ci.yml,line=14,title=GL004::job \"deploy\": stage \"production\" is not defined in 'stages'",
+		},
+		{
+			name:     "warning",
+			findings: []linter.Finding{testFindings[1]},
+			wantLine: "::warning file=.gitlab-ci.yml,line=31,title=GL007::job \"old-job\": 'only'/'except' are deprecated; prefer 'rules'",
+		},
+		{
+			name: "no file or line",
+			findings: []linter.Finding{{
+				Severity: linter.Error,
+				Rule:     "GL001",
+				Message:  "no stages defined",
+			}},
+			wantLine: "::error title=GL001::no stages defined",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			writeGitHub(&buf, tc.findings)
+			got := strings.TrimRight(buf.String(), "\n")
+			if got != tc.wantLine {
+				t.Errorf("\ngot:  %s\nwant: %s", got, tc.wantLine)
+			}
+		})
+	}
+}
+
+func TestCountSeverities(t *testing.T) {
+	errs, warns := countSeverities(testFindings)
+	if errs != 1 || warns != 1 {
+		t.Errorf("countSeverities = (%d, %d), want (1, 1)", errs, warns)
+	}
+}

cmd/glint/main.go

@@ -4,10 +4,12 @@ import (
 	"flag"
 	"fmt"
 	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 
 	"git.k3nny.fr/glint/internal/cicontext"
+	"git.k3nny.fr/glint/internal/config"
 	"git.k3nny.fr/glint/internal/fetcher"
 	"git.k3nny.fr/glint/internal/graph"
 	"git.k3nny.fr/glint/internal/linter"
@@ -15,6 +17,57 @@ import (
 	"git.k3nny.fr/glint/internal/resolver"
 )
 
+// version is set at build time via -ldflags "-X main.version=vX.Y.Z".
+var version = "dev"
+
+// defaultCacheDir returns the platform-default glint cache directory:
+// $XDG_CACHE_HOME/glint or ~/.cache/glint.
+func defaultCacheDir() string {
+	if xdg := os.Getenv("XDG_CACHE_HOME"); xdg != "" {
+		return filepath.Join(xdg, "glint")
+	}
+	if home, err := os.UserHomeDir(); err == nil {
+		return filepath.Join(home, ".cache", "glint")
+	}
+	return ""
+}
+
+const globalUsage = `glint: Lint and visualise GitLab CI pipelines locally.
+
+Usage: glint [OPTIONS] <COMMAND>
+
+Commands:
+  check    Lint a pipeline file — exits 0 (clean) or 1 (errors found)
+  graph    Visualise the pipeline as a job tree or Mermaid graph
+
+Options:
+  -h, --help     Print help
+  -v, --version  Print version
+
+For help with a specific command, see: ` + "`glint <command> --help`" + `.
+`
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Fprint(os.Stderr, globalUsage)
+		os.Exit(2)
+	}
+	switch os.Args[1] {
+	case "check":
+		cmdCheck(os.Args[2:])
+	case "graph":
+		cmdGraph(os.Args[2:])
+	case "-h", "--help", "help":
+		fmt.Fprintf(os.Stderr, "glint %s\n\n", version)
+		fmt.Fprint(os.Stderr, globalUsage)
+	case "-v", "--version", "version":
+		fmt.Printf("glint %s\n", version)
+	default:
+		fmt.Fprintf(os.Stderr, "glint: unknown command %q\n\n%s", os.Args[1], globalUsage)
+		os.Exit(2)
+	}
+}
+
 // multiFlag allows a flag to be specified multiple times.
 type multiFlag []string
 
@@ -24,31 +77,151 @@ func (f *multiFlag) Set(v string) error {
 	return nil
 }
 
-func main() {
-	var (
-		token     = flag.String("token", "", "GitLab personal access token (overrides GITLAB_TOKEN)")
-		gitlabURL = flag.String("gitlab-url", "", "GitLab instance URL (overrides CI_SERVER_URL / GITLAB_URL)")
-		graphMode = flag.String("graph", "", "graph mode: includes | pipeline | all")
-		graphOut  = flag.String("graph-out", "glint-out", "output directory for pipeline graph files")
-		branch    = flag.String("branch", "", "simulate a branch push (sets CI_COMMIT_BRANCH, …)")
-		tag       = flag.String("tag", "", "simulate a tag push (sets CI_COMMIT_TAG, …)")
-		source    = flag.String("source", "", "set CI_PIPELINE_SOURCE")
-		vars      multiFlag
-	)
-	flag.Var(&vars, "var", "set a CI variable as KEY=VALUE; repeatable")
-	flag.Usage = func() {
-		fmt.Fprintf(os.Stderr, "usage: glint [options] <pipeline.yml>\n\n")
-		flag.PrintDefaults()
-	}
-	flag.Parse()
+func cmdCheck(args []string) {
+	fs := flag.NewFlagSet("glint check", flag.ExitOnError)
+	token := fs.String("token", "", "GitLab personal access token (overrides GITLAB_TOKEN)")
+	gitlabURL := fs.String("gitlab-url", "", "GitLab instance URL (overrides CI_SERVER_URL / GITLAB_URL)")
+	cacheDir := fs.String("cache-dir", "", "directory to cache fetched remote includes (created if needed)")
+	offline := fs.Bool("offline", false, "skip all network calls; serve only from --cache-dir")
+	format := fs.String("format", "text", "output format: text, json, sarif, junit, github")
+	branch := fs.String("branch", "", "simulate a branch push (sets CI_COMMIT_BRANCH, …)")
+	tag := fs.String("tag", "", "simulate a tag push (sets CI_COMMIT_TAG, …)")
+	source := fs.String("source", "", "set CI_PIPELINE_SOURCE")
+	listVars := fs.Bool("list-vars", false, "print all collected pipeline variables (from root and included files) to stderr, then continue")
+	var vars multiFlag
+	fs.Var(&vars, "var", "set a CI variable as KEY=VALUE; repeatable")
+	fs.Usage = func() {
+		fmt.Fprintf(os.Stderr, "glint %s\n\n", version)
+		fmt.Fprint(os.Stderr, `Lint a GitLab CI pipeline file.
 
-	if flag.NArg() != 1 {
-		flag.Usage()
+Resolves local includes and extends chains, then runs all lint rules.
+Exits 0 when no errors are found, 1 when at least one error is reported.
+
+Usage: glint check [OPTIONS] <PIPELINE>
+
+Arguments:
+  <PIPELINE>  Path to the .gitlab-ci.yml file to lint
+
+Options:
+      --format <FORMAT>
+          Output format for findings.
+          [default: text] [possible values: text, json, sarif, junit, github]
+
+      --token <TOKEN>
+          GitLab personal access token. Required to fetch project: includes;
+          component: includes are attempted unauthenticated.
+          [env: GITLAB_TOKEN | CI_JOB_TOKEN | GITLAB_PRIVATE_TOKEN]
+
+      --gitlab-url <URL>
+          GitLab instance URL.
+          [env: CI_SERVER_URL | GITLAB_URL] [default: https://gitlab.com]
+
+      --cache-dir <DIR>
+          Cache fetched remote templates (project: and component: includes) in
+          DIR. The directory is created on first use. Subsequent runs read from
+          cache first, avoiding repeated network calls.
+
+      --offline
+          Do not make any network calls. All remote includes must already be
+          present in --cache-dir; missing entries emit a warning (same as
+          having no token). Implies the default cache dir (~/.cache/glint) when
+          --cache-dir is not set.
+
+      --branch <NAME>
+          Simulate a branch push. Populates: CI_COMMIT_BRANCH,
+          CI_COMMIT_REF_NAME, CI_COMMIT_REF_SLUG, CI_PIPELINE_SOURCE=push.
+          [default: main]
+
+      --tag <NAME>
+          Simulate a tag push. Populates: CI_COMMIT_TAG, CI_COMMIT_REF_NAME,
+          CI_COMMIT_REF_SLUG, CI_PIPELINE_SOURCE=push. Clears CI_COMMIT_BRANCH.
+
+      --source <EVENT>
+          Override CI_PIPELINE_SOURCE.
+          [default: push] [possible values: push, merge_request_event, schedule, web, api]
+
+      --var <KEY=VALUE>
+          Set or override a CI variable. Takes precedence over --branch, --tag,
+          and --source. Repeatable.
+
+      --list-vars
+          Print all pipeline-level variables collected from the root file and
+          every included file (sorted KEY=VALUE) to stderr, then continue
+          normally. Useful for debugging variable resolution and GL032 findings.
+
+  -h, --help
+          Print help
+
+Note: when none of --branch, --tag, --source, or --var are given, glint
+defaults to --branch main --source push so that rules:if: expressions are
+always evaluated.
+
+Examples:
+  glint check .gitlab-ci.yml
+  glint check --format json .gitlab-ci.yml
+  glint check --format sarif .gitlab-ci.yml | upload-to-github-code-scanning
+  glint check --format junit .gitlab-ci.yml > junit.xml
+  glint check --format github .gitlab-ci.yml
+  glint check --branch develop .gitlab-ci.yml
+  glint check --tag v1.0.0 .gitlab-ci.yml
+  glint check --source merge_request_event .gitlab-ci.yml
+  glint check --list-vars .gitlab-ci.yml
+  GITLAB_TOKEN=glpat-xxxx glint check .gitlab-ci.yml
+  glint check --token glpat-xxxx --gitlab-url https://gitlab.example.com .gitlab-ci.yml
+  glint check --branch main --var DEPLOY_ENV=production .gitlab-ci.yml
+  glint check --cache-dir ~/.cache/glint .gitlab-ci.yml
+  glint check --offline --cache-dir ~/.cache/glint .gitlab-ci.yml
+`)
+	}
+	_ = fs.Parse(args)
+
+	// Apply implicit defaults when no context flag is given at all.
+	if *branch == "" && *tag == "" && *source == "" && len(vars) == 0 {
+		*branch = "main"
+		*source = "push"
+	}
+
+	validFormats := map[string]bool{
+		"text": true, "json": true, "sarif": true, "junit": true, "github": true,
+	}
+	if !validFormats[*format] {
+		fmt.Fprintf(os.Stderr, "glint: unknown format %q; valid: text, json, sarif, junit, github\n", *format)
 		os.Exit(2)
 	}
-	path := flag.Arg(0)
 
-	cfg := fetcher.AutoConfig().WithOverrides(*gitlabURL, *token)
+	if fs.NArg() != 1 {
+		fs.Usage()
+		os.Exit(2)
+	}
+	path := fs.Arg(0)
+	rootDir := filepath.Dir(filepath.Clean(path))
+
+	// Load project config (.glint.yml), searching from the pipeline directory
+	// up to the git root.
+	glintCfg, cfgErr := config.Load(rootDir)
+	if cfgErr != nil {
+		fmt.Fprintf(os.Stderr, "%s: [warning] %s: %v\n", path, config.Filename, cfgErr)
+	}
+
+	// CLI flags take priority over config file values, which take priority over
+	// environment variables (read by AutoConfig).
+	fetcherToken := *token
+	if fetcherToken == "" {
+		fetcherToken = glintCfg.Token
+	}
+	fetcherURL := *gitlabURL
+	if fetcherURL == "" {
+		fetcherURL = glintCfg.URL
+	}
+	resolvedCacheDir := *cacheDir
+	if resolvedCacheDir == "" {
+		resolvedCacheDir = glintCfg.CacheDir
+	}
+	if *offline && resolvedCacheDir == "" {
+		resolvedCacheDir = defaultCacheDir()
+	}
+
+	cfg := fetcher.AutoConfig().WithOverrides(fetcherURL, fetcherToken, resolvedCacheDir, *offline)
 
 	p, err := model.Parse(path)
 	if err != nil {
@@ -56,80 +229,320 @@ func main() {
 		os.Exit(2)
 	}
 
-	warnings := resolver.ResolveIncludes(p, cfg)
-	for _, w := range warnings {
-		fmt.Fprintf(os.Stderr, "[WARNING] include %s\n", w)
+	// Merge config-defined stages into the pipeline before linting so that
+	// GL004 does not fire for jobs in stages declared only in .glint.yml.
+	stageSet := make(map[string]bool, len(p.Stages))
+	for _, s := range p.Stages {
+		stageSet[s] = true
+	}
+	for _, s := range glintCfg.Stages {
+		if !stageSet[s] {
+			p.Stages = append(p.Stages, s)
+			stageSet[s] = true
+		}
 	}
 
-	if err := resolver.Resolve(p); err != nil {
+	warnings, _ := resolver.ResolveIncludes(p, cfg, rootDir)
+	for _, w := range warnings {
+		fmt.Fprintf(os.Stderr, "%s: [warning] include %s\n", path, w)
+	}
+
+	extWarnings, err := resolver.Resolve(p)
+	if err != nil {
 		fmt.Fprintf(os.Stderr, "error: resolving extends: %v\n", err)
 		os.Exit(2)
 	}
-
-	if *graphMode != "" {
-		runGraph(p, path, *graphMode, *graphOut)
-		return
+	for _, w := range extWarnings {
+		fmt.Fprintf(os.Stderr, "%s: [warning] job %q extends unknown job %q; extends chain skipped\n", path, w.Job, w.Base)
 	}
 
 	ctx := cicontext.New(*branch, *tag, *source, vars)
 	if !ctx.IsEmpty() {
+		if !enrichContext(ctx, p) {
+			fmt.Fprintf(os.Stderr, "%s: [warning] workflow:rules: pipeline would not start for this context\n", path)
+		}
+	}
+	if *listVars {
+		printVars(p, ctx)
+	}
+	// Context summary only makes sense in plain-text output; suppress it in
+	// structured formats so stdout contains only the machine-readable payload.
+	if !ctx.IsEmpty() && *format == "text" {
 		printContext(p, ctx)
 	}
 
 	findings := linter.Lint(p)
-	hasErrors := false
-	for _, f := range findings {
-		fmt.Println(f)
-		if f.Severity == linter.Error {
-			hasErrors = true
-		}
+	findings = applyConfig(findings, glintCfg, p.Suppressions)
+	errCount, _ := countSeverities(findings)
+
+	// In structured formats the summary line goes to stderr so stdout is clean.
+	summaryOut := os.Stdout
+	if *format != "text" {
+		summaryOut = os.Stderr
 	}
 
-	jobCount := len(p.Jobs)
-	stageCount := len(p.Stages)
+	switch *format {
+	case "json":
+		writeJSON(os.Stdout, findings, path)
+	case "sarif":
+		writeSARIF(os.Stdout, findings, path)
+	case "junit":
+		writeJUnit(os.Stdout, findings, path)
+	case "github":
+		writeGitHub(os.Stdout, findings)
+	default: // "text"
+		for _, f := range findings {
+			fmt.Println(f)
+		}
+	}
 
 	if len(findings) == 0 {
-		fmt.Printf("OK: %s — no issues found (%d job(s), %d stage(s))\n", path, jobCount, stageCount)
+		fmt.Fprintf(summaryOut, "OK: %s — no issues found (%d job(s), %d stage(s))\n", path, len(p.Jobs), len(p.Stages))
 	} else {
-		errCount := 0
-		for _, f := range findings {
-			if f.Severity == linter.Error {
-				errCount++
-			}
-		}
-		fmt.Printf("%d finding(s): %d error(s)\n", len(findings), errCount)
+		fmt.Fprintf(summaryOut, "%d finding(s): %d error(s)\n", len(findings), errCount)
 	}
 
-	if hasErrors {
+	if errCount > 0 {
 		os.Exit(1)
 	}
 }
 
-func runGraph(p *model.Pipeline, path, mode, outDir string) {
+var knownGraphModes = map[string]bool{
+	"tree": true, "includes": true, "pipeline": true, "all": true,
+}
+
+func cmdGraph(args []string) {
+	// Optional mode word must come before any flags or the file path.
+	mode := "default"
+	if len(args) > 0 && !strings.HasPrefix(args[0], "-") && knownGraphModes[args[0]] {
+		mode = args[0]
+		args = args[1:]
+	}
+
+	fs := flag.NewFlagSet("glint graph", flag.ExitOnError)
+	token := fs.String("token", "", "GitLab personal access token (overrides GITLAB_TOKEN)")
+	gitlabURL := fs.String("gitlab-url", "", "GitLab instance URL (overrides CI_SERVER_URL / GITLAB_URL)")
+	cacheDir := fs.String("cache-dir", "", "directory to cache fetched remote includes (created if needed)")
+	offline := fs.Bool("offline", false, "skip all network calls; serve only from --cache-dir")
+	out := fs.String("out", "glint-out", "output directory for Mermaid graph files (pipeline mode)")
+	fs.Usage = func() {
+		fmt.Fprintf(os.Stderr, "glint %s\n\n", version)
+		fmt.Fprint(os.Stderr, `Visualise the pipeline as a job tree and/or Mermaid graph.
+
+Usage: glint graph [MODE] [OPTIONS] <PIPELINE>
+
+Arguments:
+  [MODE]      Graph mode; must appear before options [default: tree+includes]
+              [possible values: tree, includes, pipeline, all]
+  <PIPELINE>  Path to the .gitlab-ci.yml file
+
+Options:
+      --out <DIR>
+          Output directory for rendered graph files.
+          Used by the pipeline and all modes only. [default: glint-out]
+
+      --token <TOKEN>
+          GitLab personal access token. Used to fetch remote project: includes
+          when building the include dependency graph.
+          [env: GITLAB_TOKEN | CI_JOB_TOKEN | GITLAB_PRIVATE_TOKEN]
+
+      --gitlab-url <URL>
+          GitLab instance URL.
+          [env: CI_SERVER_URL | GITLAB_URL] [default: https://gitlab.com]
+
+      --branch <NAME>
+          Simulate a branch push. Jobs in tree output are annotated with their
+          evaluated state ([skipped] or [manual]; no tag means active).
+          Populates: CI_COMMIT_BRANCH, CI_COMMIT_REF_NAME, CI_COMMIT_REF_SLUG,
+          CI_PIPELINE_SOURCE=push.
+          [default: main]
+
+      --tag <NAME>
+          Simulate a tag push. Populates: CI_COMMIT_TAG, CI_COMMIT_REF_NAME,
+          CI_COMMIT_REF_SLUG, CI_PIPELINE_SOURCE=push. Clears CI_COMMIT_BRANCH.
+
+      --source <EVENT>
+          Override CI_PIPELINE_SOURCE.
+          [default: push] [possible values: push, merge_request_event, schedule, web, api]
+
+      --var <KEY=VALUE>
+          Set or override a CI variable. Repeatable.
+
+      --list-vars
+          Print all pipeline-level variables collected from the root file and
+          every included file (sorted KEY=VALUE) to stderr, then continue
+          normally. Useful for debugging variable resolution.
+
+  -h, --help
+          Print help
+
+Note: when none of --branch, --tag, --source, or --var are given, glint
+defaults to --branch main --source push so that rules:if: expressions are
+always evaluated.
+
+Examples:
+  glint graph .gitlab-ci.yml
+  glint graph tree .gitlab-ci.yml
+  glint graph tree --branch develop .gitlab-ci.yml
+  glint graph tree --tag v1.0.0 .gitlab-ci.yml
+  glint graph tree --list-vars .gitlab-ci.yml
+  glint graph includes .gitlab-ci.yml > includes.mmd
+  glint graph pipeline .gitlab-ci.yml
+  glint graph pipeline --out /tmp/graphs .gitlab-ci.yml
+  glint graph all .gitlab-ci.yml > includes.mmd
+`)
+	}
+	branch := fs.String("branch", "", "simulate a branch push (sets CI_COMMIT_BRANCH, …)")
+	tag := fs.String("tag", "", "simulate a tag push (sets CI_COMMIT_TAG, …)")
+	source := fs.String("source", "", "set CI_PIPELINE_SOURCE")
+	listVars := fs.Bool("list-vars", false, "print all collected pipeline variables to stderr, then continue")
+	var vars multiFlag
+	fs.Var(&vars, "var", "set a CI variable as KEY=VALUE; repeatable")
+	_ = fs.Parse(args)
+
+	// Apply implicit defaults when no context flag is given at all.
+	if *branch == "" && *tag == "" && *source == "" && len(vars) == 0 {
+		*branch = "main"
+		*source = "push"
+	}
+
+	if fs.NArg() != 1 {
+		fs.Usage()
+		os.Exit(2)
+	}
+	path := fs.Arg(0)
+
+	resolvedCacheDir := *cacheDir
+	if *offline && resolvedCacheDir == "" {
+		resolvedCacheDir = defaultCacheDir()
+	}
+
+	cfg := fetcher.AutoConfig().WithOverrides(*gitlabURL, *token, resolvedCacheDir, *offline)
+
+	p, err := model.Parse(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(2)
+	}
+
+	rootDir := filepath.Dir(filepath.Clean(path))
+	resolver.ResolveIncludes(p, cfg, rootDir) //nolint:errcheck
+	resolver.Resolve(p)                       //nolint:errcheck
+
+	ctx := cicontext.New(*branch, *tag, *source, vars)
+	if !ctx.IsEmpty() {
+		enrichContext(ctx, p)
+	}
+	if *listVars {
+		printVars(p, ctx)
+	}
+
 	switch mode {
+	case "default":
+		fmt.Print(graph.Tree(p, ctx))
+		fmt.Println("---")
+		fmt.Print(graph.Includes(path, p.Include, cfg))
+	case "tree":
+		fmt.Print(graph.Tree(p, ctx))
 	case "includes":
-		fmt.Print(graph.Includes(path, p.Include))
+		fmt.Print(graph.Includes(path, p.Include, cfg))
 	case "pipeline":
-		outPath, err := graph.RenderPipeline(p, outDir)
+		outPath, err := graph.RenderPipeline(p, *out)
 		if err != nil {
 			fmt.Fprintf(os.Stderr, "error: rendering pipeline graph: %v\n", err)
 			os.Exit(2)
 		}
 		fmt.Println(outPath)
 	case "all":
-		fmt.Print(graph.Includes(path, p.Include))
-		outPath, err := graph.RenderPipeline(p, outDir)
+		fmt.Print(graph.Includes(path, p.Include, cfg))
+		outPath, err := graph.RenderPipeline(p, *out)
 		if err != nil {
 			fmt.Fprintf(os.Stderr, "error: rendering pipeline graph: %v\n", err)
 			os.Exit(2)
 		}
 		fmt.Fprintln(os.Stderr, outPath)
-	default:
-		fmt.Fprintf(os.Stderr, "error: unknown --graph value %q; use: includes, pipeline, all\n", mode)
-		os.Exit(2)
 	}
 }
 
+// printVars prints the collected variable namespaces to stderr:
+//  1. Pipeline variables — declared in variables: blocks across the root file
+//     and all included files (merged by ResolveIncludes).
+//  2. Workflow-rule variables — union of variables: from every workflow:rules
+//     entry; any one of them may be injected at runtime.
+//  3. Effective context variables — only when ctx is non-empty; shows the
+//     fully merged set visible to job rules:if: after enrichContext.
+func printVars(p *model.Pipeline, ctx *cicontext.Context) {
+	fmt.Fprintln(os.Stderr, "Pipeline variables (YAML, root + includes):")
+	printVarMap(p.Variables)
+
+	if p.Workflow != nil {
+		union := map[string]any{}
+		for _, rule := range p.Workflow.Rules {
+			for k, v := range rule.Variables {
+				union[k] = v
+			}
+		}
+		if len(union) > 0 {
+			fmt.Fprintln(os.Stderr, "Workflow-rule variables (union across all rules):")
+			printVarMap(union)
+		}
+	}
+
+	if !ctx.IsEmpty() {
+		fmt.Fprintln(os.Stderr, "Effective context variables (after workflow + CLI flags):")
+		keys := make([]string, 0, len(ctx.Vars))
+		for k := range ctx.Vars {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			fmt.Fprintf(os.Stderr, "  %s=%s\n", k, ctx.Vars[k])
+		}
+	}
+}
+
+func printVarMap(m map[string]any) {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	if len(keys) == 0 {
+		fmt.Fprintln(os.Stderr, "  (none)")
+		return
+	}
+	for _, k := range keys {
+		fmt.Fprintf(os.Stderr, "  %s=%s\n", k, varValueString(m[k]))
+	}
+}
+
+func varValueString(v any) string {
+	if s, ok := cicontext.ScalarString(v); ok {
+		return s
+	}
+	return "(complex)"
+}
+
+// enrichContext injects pipeline-level variable defaults and then
+// workflow-rule-generated variables into ctx before job evaluation.
+// Injection respects pinned variables (--branch/--tag/--source/--var always win).
+// Returns false when workflow:rules: would prevent the pipeline from starting.
+func enrichContext(ctx *cicontext.Context, p *model.Pipeline) bool {
+	// Pipeline variables: injected as defaults (lowest priority).
+	for k, v := range cicontext.ExtractStringVars(p.Variables) {
+		ctx.Inject(k, v)
+	}
+	// Workflow rules: evaluate to find which rule matches, then inject its variables.
+	runs, ruleVars := cicontext.EvalWorkflow(p, ctx)
+	for k, v := range ruleVars {
+		ctx.Inject(k, v)
+	}
+	// Expand $VAR / ${VAR} references within variable values now that all
+	// sources (pipeline, workflow rules, CLI) have been merged.
+	ctx.ExpandVars()
+	return runs
+}
+
 func printContext(p *model.Pipeline, ctx *cicontext.Context) {
 	fmt.Printf("Context: %s\n\n", ctx.Summary())
 

go.mod

@@ -2,4 +2,14 @@ module git.k3nny.fr/glint
 
 go 1.26.4
 
-require gopkg.in/yaml.v3 v3.0.1 // indirect
+require (
+	github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c // indirect
+	golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678 // indirect
+	golang.org/x/mod v0.31.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/tools v0.40.1-0.20260108161641-ca281cf95054 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	honnef.co/go/tools v0.7.0 // indirect
+)
+
+tool honnef.co/go/tools/cmd/staticcheck

go.sum

@@ -1,3 +1,16 @@
+github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c h1:pxW6RcqyfI9/kWtOwnv/G+AzdKuy2ZrqINhenH4HyNs=
+github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
+golang.org/x/exp v0.0.0-20231110203233-9a3e6036ecaa h1:FRnLl4eNAQl8hwxVVC17teOw8kdjVDVAiFMtgUdTSRQ=
+golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678 h1:1P7xPZEwZMoBoz0Yze5Nx2/4pxj6nw9ZqHWXqP0iRgQ=
+golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678/go.mod h1:AbB0pIl9nAr9wVwH+Z2ZpaocVmF5I4GyWCDIsVjR0bk=
+golang.org/x/mod v0.31.0 h1:HaW9xtz0+kOcWKwli0ZXy79Ix+UW/vOfmWI5QVd2tgI=
+golang.org/x/mod v0.31.0/go.mod h1:43JraMp9cGx1Rx3AqioxrbrhNsLl2l/iNAvuBkrezpg=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/tools v0.40.1-0.20260108161641-ca281cf95054 h1:CHVDrNHx9ZoOrNN9kKWYIbT5Rj+WF2rlwPkhbQQ5V4U=
+golang.org/x/tools v0.40.1-0.20260108161641-ca281cf95054/go.mod h1:Ik/tzLRlbscWpqqMRjyWYDisX8bG13FrdXp3o4Sr9lc=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+honnef.co/go/tools v0.7.0 h1:w6WUp1VbkqPEgLz4rkBzH/CSU6HkoqNLp6GstyTx3lU=
+honnef.co/go/tools v0.7.0/go.mod h1:pm29oPxeP3P82ISxZDgIYeOaf9ta6Pi0EWvCFoLG2vc=

internal/cicontext/context.go

@@ -1,12 +1,16 @@
 package cicontext
 
-import "strings"
+import (
+	"fmt"
+	"strings"
+)
 
 // Context holds the simulated CI execution environment used for context-aware
 // pipeline evaluation (rules:if:, only:, except:, workflow:rules:).
 // Variables are keyed by their name without the leading $.
 type Context struct {
-	Vars map[string]string
+	Vars   map[string]string
+	pinned map[string]bool // vars set via --var or shortcuts; never overwritten by Inject
 }
 
 // New builds a Context from high-level shortcut values and optional KEY=VALUE
@@ -17,46 +21,55 @@ type Context struct {
 // preserving the existing linting behaviour when no context flags are given.
 //
 // Override priority (highest wins): extraVars > branch/tag/source shortcuts.
+// Both shortcut-derived and extraVar variables are pinned — they will not be
+// overwritten by Inject (used for pipeline-level and workflow-rule variables).
 func New(branch, tag, source string, extraVars []string) *Context {
 	if branch == "" && tag == "" && source == "" && len(extraVars) == 0 {
 		return &Context{}
 	}
 
 	vars := make(map[string]string)
+	pinned := make(map[string]bool)
+
+	pin := func(k, v string) {
+		vars[k] = v
+		pinned[k] = true
+	}
 
 	if branch != "" {
-		vars["CI_COMMIT_BRANCH"] = branch
-		vars["CI_COMMIT_REF_NAME"] = branch
-		vars["CI_COMMIT_REF_SLUG"] = slugify(branch)
+		pin("CI_COMMIT_BRANCH", branch)
+		pin("CI_COMMIT_REF_NAME", branch)
+		pin("CI_COMMIT_REF_SLUG", slugify(branch))
 		if source == "" {
 			source = "push"
 		}
 	}
 	if tag != "" {
-		vars["CI_COMMIT_TAG"] = tag
-		vars["CI_COMMIT_REF_NAME"] = tag
-		vars["CI_COMMIT_REF_SLUG"] = slugify(tag)
-		delete(vars, "CI_COMMIT_BRANCH") // tag pushes have no branch variable
+		pin("CI_COMMIT_TAG", tag)
+		pin("CI_COMMIT_REF_NAME", tag)
+		pin("CI_COMMIT_REF_SLUG", slugify(tag))
+		delete(vars, "CI_COMMIT_BRANCH")
+		delete(pinned, "CI_COMMIT_BRANCH")
 		if source == "" {
 			source = "push"
 		}
 	}
 	if source != "" {
-		vars["CI_PIPELINE_SOURCE"] = source
+		pin("CI_PIPELINE_SOURCE", source)
 	}
 	if _, ok := vars["CI_DEFAULT_BRANCH"]; !ok {
 		vars["CI_DEFAULT_BRANCH"] = "main"
 	}
 
-	// KEY=VALUE overrides win over shortcuts.
+	// KEY=VALUE overrides win over shortcuts and everything else.
 	for _, kv := range extraVars {
 		k, v, ok := strings.Cut(kv, "=")
 		if ok {
-			vars[k] = v
+			pin(k, v)
 		}
 	}
 
-	return &Context{Vars: vars}
+	return &Context{Vars: vars, pinned: pinned}
 }
 
 // IsEmpty reports whether no variables have been set (no context flags given).
@@ -73,6 +86,21 @@ func (c *Context) Get(key string) string {
 	return c.Vars[key]
 }
 
+// Inject sets key=value only if key is not already pinned (i.e. not set via
+// --branch / --tag / --source / --var). Used to inject pipeline-level variable
+// defaults and workflow-rule variables without overriding explicit user input.
+// Calling Inject in order from lowest-priority to highest-priority source
+// ensures later calls win over earlier ones.
+func (c *Context) Inject(key, value string) {
+	if c.pinned[key] {
+		return
+	}
+	if c.Vars == nil {
+		c.Vars = make(map[string]string)
+	}
+	c.Vars[key] = value
+}
+
 // Summary returns a short human-readable description of the context for CLI output.
 func (c *Context) Summary() string {
 	if c.IsEmpty() {
@@ -90,6 +118,133 @@ func (c *Context) Summary() string {
 	return strings.Join(parts, ", ")
 }
 
+// ExtractStringVars converts a map[string]any variable block (as used by
+// Pipeline.Variables and Rule.Variables) to a flat map[string]string.
+// Plain string values are used directly. Extended {value: ...} map form uses
+// the "value" key. Scalar non-string values (bool, int, float64) are
+// converted to their string representation, matching GitLab's own behaviour
+// where all CI variable values are strings.
+func ExtractStringVars(m map[string]any) map[string]string {
+	if len(m) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(m))
+	for k, v := range m {
+		if s, ok := ScalarString(v); ok {
+			out[k] = s
+		}
+	}
+	return out
+}
+
+// ScalarString converts a YAML-decoded CI variable value to its string
+// representation. Handles plain scalars and the extended {value: ...} map
+// form. Returns (s, true) on success, ("", false) for unrecognised forms.
+func ScalarString(v any) (string, bool) {
+	switch val := v.(type) {
+	case string:
+		return val, true
+	case bool:
+		return fmt.Sprintf("%t", val), true
+	case int:
+		return fmt.Sprintf("%d", val), true
+	case float64:
+		return fmt.Sprintf("%g", val), true
+	case map[string]any:
+		inner, ok := val["value"]
+		if !ok {
+			return "", false
+		}
+		return ScalarString(inner)
+	}
+	return "", false
+}
+
+// ExpandVars expands $VAR and ${VAR} references within every value in
+// ctx.Vars, using the same map as the expansion source. Iteration repeats
+// (up to 10 passes) so transitive chains like A=$B, B=$C resolve fully.
+// Variables that form circular references are left as-is after the limit.
+func (c *Context) ExpandVars() {
+	if c == nil || len(c.Vars) == 0 {
+		return
+	}
+	for range 10 {
+		changed := false
+		for k, v := range c.Vars {
+			expanded := expandVarRefs(v, c.Vars)
+			if expanded != v {
+				c.Vars[k] = expanded
+				changed = true
+			}
+		}
+		if !changed {
+			return
+		}
+	}
+}
+
+// expandVarRefs replaces $VAR and ${VAR} occurrences in s with their values
+// from vars. Unknown variables are left unchanged.
+func expandVarRefs(s string, vars map[string]string) string {
+	if !strings.Contains(s, "$") {
+		return s
+	}
+	var sb strings.Builder
+	i := 0
+	for i < len(s) {
+		if s[i] != '$' {
+			sb.WriteByte(s[i])
+			i++
+			continue
+		}
+		i++ // consume '$'
+		if i >= len(s) {
+			sb.WriteByte('$')
+			break
+		}
+		if s[i] == '{' {
+			i++ // consume '{'
+			j := i
+			for j < len(s) && isIdentByte(s[j]) {
+				j++
+			}
+			if j < len(s) && s[j] == '}' {
+				name := s[i:j]
+				if val, ok := vars[name]; ok {
+					sb.WriteString(val)
+				} else {
+					sb.WriteString("${")
+					sb.WriteString(name)
+					sb.WriteByte('}')
+				}
+				i = j + 1
+			} else {
+				// Malformed ${…} — emit literally
+				sb.WriteString("${")
+				i = j
+			}
+		} else {
+			j := i
+			for j < len(s) && isIdentByte(s[j]) {
+				j++
+			}
+			if j > i {
+				name := s[i:j]
+				if val, ok := vars[name]; ok {
+					sb.WriteString(val)
+				} else {
+					sb.WriteByte('$')
+					sb.WriteString(name)
+				}
+				i = j
+			} else {
+				sb.WriteByte('$')
+			}
+		}
+	}
+	return sb.String()
+}
+
 // slugify converts a ref name to its GitLab slug form:
 // lowercased, non-alphanumeric characters replaced with '-', leading/trailing '-' removed.
 func slugify(s string) string {

internal/cicontext/eval.go

@@ -9,21 +9,35 @@ import (
 // variable resolver.
 //
 // Supported:
-//   - Variable references: $VAR_NAME
+//   - Variable references: $VAR_NAME or ${VAR_NAME}
 //   - String literals:     "value" or 'value'
 //   - Null keyword:        null
-//   - Comparison:          == != =~ !~
+//   - Comparison:          == != =~ !~  (single = is accepted as == for user convenience)
 //   - Boolean:             && || !
 //   - Grouping:            ( )
+//   - Regex flags:         /pattern/i (case-insensitive), /pattern/m, /pattern/s
+//   - Multi-line:          newlines between tokens are treated as whitespace
+//   - Variable regex RHS:  $VAR =~ $PATTERN when $PATTERN holds a /regex/ string
 //
 // Regex patterns use Go's regexp syntax, which covers the common RE2 subset
 // used by GitLab CI. Unsupported or unparseable expressions fall back to true
 // (permissive) so the linter never silently drops jobs it cannot evaluate.
 func EvalIf(expr string, vars func(string) string) bool {
+	return evalIf(expr, vars, true)
+}
+
+// EvalIfStrict is like EvalIf but returns false (instead of true) when the
+// expression cannot be fully parsed. Use for workflow:rules: evaluation where
+// a failed parse should skip to the next rule rather than matching everything.
+func EvalIfStrict(expr string, vars func(string) string) bool {
+	return evalIf(expr, vars, false)
+}
+
+func evalIf(expr string, vars func(string) string, permissive bool) bool {
 	p := &exprParser{s: strings.TrimSpace(expr), vars: vars}
 	result, ok := p.parseOr()
 	if !ok || p.pos < len(p.s) {
-		return true // unparseable → permissive
+		return permissive
 	}
 	return result
 }
@@ -56,8 +70,13 @@ func (p *exprParser) consume(tok string) bool {
 }
 
 func (p *exprParser) skipWS() {
-	for p.pos < len(p.s) && (p.s[p.pos] == ' ' || p.s[p.pos] == '\t') {
-		p.pos++
+	for p.pos < len(p.s) {
+		b := p.s[p.pos]
+		if b == ' ' || b == '\t' || b == '\n' || b == '\r' {
+			p.pos++
+			continue
+		}
+		break
 	}
 }
 
@@ -67,11 +86,11 @@ func (p *exprParser) skipWS() {
 //   and_expr   → not_expr ( '&&' not_expr )*
 //   not_expr   → '!' not_expr | primary
 //   primary    → '(' or_expr ')' | comparison
-//   comparison → value ( op value | regex_op regex )? | value
-//   value      → '$' ident | '"' … '"' | "'" … "'" | 'null'
+//   comparison → value ( op value | regex_op regex_rhs )?
+//   value      → '$' '{' ident '}' | '$' ident | '"' … '"' | "'" … "'" | 'null'
 //   op         → '==' | '!='
 //   regex_op   → '=~' | '!~'
-//   regex      → '/' … '/'
+//   regex_rhs  → '/' … '/' flags? | '$' ident (where ident value is '/…/flags')
 
 func (p *exprParser) parseOr() (bool, bool) {
 	left, ok := p.parseAnd()
@@ -165,8 +184,11 @@ func (p *exprParser) parseComparison() (bool, bool) {
 
 	case p.consume("=~"):
 		p.skipWS()
-		pat, ok := p.parseRegexLiteral()
-		if !ok {
+		pat, patOk, permissive := p.parseRegexRHS()
+		if permissive {
+			return true, true
+		}
+		if !patOk {
 			return false, false
 		}
 		re, err := regexp.Compile(pat)
@@ -177,8 +199,11 @@ func (p *exprParser) parseComparison() (bool, bool) {
 
 	case p.consume("!~"):
 		p.skipWS()
-		pat, ok := p.parseRegexLiteral()
-		if !ok {
+		pat, patOk, permissive := p.parseRegexRHS()
+		if permissive {
+			return true, true
+		}
+		if !patOk {
 			return false, false
 		}
 		re, err := regexp.Compile(pat)
@@ -186,19 +211,66 @@ func (p *exprParser) parseComparison() (bool, bool) {
 			return true, true // bad pattern → permissive
 		}
 		return !re.MatchString(leftStr), true
+
+	// Single = not followed by = or ~ — accepted as == (common user mistake;
+	// GitLab CI only supports == but = is frequently written by accident).
+	case p.peek() == '=' && !p.startsWith("==") && !p.startsWith("=~"):
+		p.pos++ // consume '='
+		p.skipWS()
+		rightStr, ok := p.parseValue()
+		if !ok {
+			return false, false
+		}
+		return leftStr == rightStr, true
 	}
 
 	// No operator: variable is truthy when non-empty (defined and non-null).
 	return leftStr != "", true
 }
 
-// parseValue reads $VAR, "string", 'string', or null.
-// null and undefined variables both produce an empty string.
+// parseRegexRHS parses the right-hand side of =~ / !~ operators.
+// Returns (pattern, ok, permissive):
+//   - /regex/flags literal  → (pattern, true, false)
+//   - $VAR whose value is /regex/flags → (pattern, true, false)
+//   - $VAR whose value is empty or not a /regex/ → ("", false, true) — caller uses permissive true
+//   - parse error → ("", false, false)
+func (p *exprParser) parseRegexRHS() (pat string, ok bool, permissive bool) {
+	if p.peek() == '/' {
+		pat, ok = p.parseRegexLiteral()
+		return pat, ok, false
+	}
+	if p.peek() == '$' {
+		varVal, varOk := p.parseValue()
+		if !varOk {
+			return "", false, false
+		}
+		pat, ok = extractRegexFromString(varVal)
+		if !ok {
+			return "", false, true // variable is not a /regex/ value → permissive
+		}
+		return pat, true, false
+	}
+	return "", false, false
+}
+
+// parseValue reads $VAR, ${VAR}, "string", 'string', null, true, false, or an
+// integer literal. null and undefined variables both produce an empty string.
+// true/false and integers produce their string representations (GitLab CI
+// compares all values as strings).
 func (p *exprParser) parseValue() (string, bool) {
 	p.skipWS()
 
 	if p.peek() == '$' {
 		p.pos++ // consume '$'
+		if p.peek() == '{' {
+			p.pos++ // consume '{'
+			name := p.parseIdent()
+			if name == "" || p.peek() != '}' {
+				return "", false
+			}
+			p.pos++ // consume '}'
+			return p.vars(name), true
+		}
 		name := p.parseIdent()
 		if name == "" {
 			return "", false
@@ -206,12 +278,18 @@ func (p *exprParser) parseValue() (string, bool) {
 		return p.vars(name), true
 	}
 
-	// null keyword — must not be a prefix of a longer identifier.
-	if p.startsWith("null") {
-		end := p.pos + 4
-		if end >= len(p.s) || !isIdentByte(p.s[end]) {
-			p.pos += 4
-			return "", true // null → empty string
+	// Keywords and string literals must not be prefixes of longer identifiers.
+	for _, kw := range []struct{ tok, val string }{
+		{"null", ""},
+		{"true", "true"},
+		{"false", "false"},
+	} {
+		if p.startsWith(kw.tok) {
+			end := p.pos + len(kw.tok)
+			if end >= len(p.s) || !isIdentByte(p.s[end]) {
+				p.pos += len(kw.tok)
+				return kw.val, true
+			}
 		}
 	}
 
@@ -219,6 +297,15 @@ func (p *exprParser) parseValue() (string, bool) {
 		return p.parseStringLiteral()
 	}
 
+	// Integer literal — returned as its decimal string for string comparison.
+	if p.peek() >= '0' && p.peek() <= '9' {
+		start := p.pos
+		for p.pos < len(p.s) && p.s[p.pos] >= '0' && p.s[p.pos] <= '9' {
+			p.pos++
+		}
+		return p.s[start:p.pos], true
+	}
+
 	return "", false
 }
 
@@ -261,7 +348,8 @@ func (p *exprParser) parseRegexLiteral() (string, bool) {
 		b := p.s[p.pos]
 		if b == '/' {
 			p.pos++ // consume closing '/'
-			return sb.String(), true
+			flags := p.parseRegexFlags()
+			return applyRegexFlags(flags, sb.String()), true
 		}
 		if b == '\\' && p.pos+1 < len(p.s) {
 			p.pos++
@@ -275,6 +363,68 @@ func (p *exprParser) parseRegexLiteral() (string, bool) {
 	return "", false // unterminated regex
 }
 
+// parseRegexFlags reads zero or more regex flag letters (i, m, s) after the
+// closing '/'. Unknown letters are consumed but ignored.
+func (p *exprParser) parseRegexFlags() string {
+	start := p.pos
+	for p.pos < len(p.s) && isIdentByte(p.s[p.pos]) {
+		p.pos++
+	}
+	return p.s[start:p.pos]
+}
+
+// applyRegexFlags prepends Go regexp flag groups to pattern (e.g. (?i) for 'i').
+// Unknown flags are silently ignored.
+func applyRegexFlags(flags, pattern string) string {
+	if flags == "" {
+		return pattern
+	}
+	var prefix strings.Builder
+	for _, f := range flags {
+		switch f {
+		case 'i':
+			prefix.WriteString("(?i)")
+		case 'm':
+			prefix.WriteString("(?m)")
+		case 's':
+			prefix.WriteString("(?s)")
+		}
+	}
+	return prefix.String() + pattern
+}
+
+// extractRegexFromString parses a /pattern/flags string (typically from a CI
+// variable) and returns a Go regexp pattern with flags applied.
+func extractRegexFromString(s string) (string, bool) {
+	s = strings.TrimSpace(s)
+	if len(s) == 0 || s[0] != '/' {
+		return "", false
+	}
+	var sb strings.Builder
+	i := 1
+	for i < len(s) {
+		b := s[i]
+		if b == '/' {
+			i++ // past closing '/'
+			var flags strings.Builder
+			for i < len(s) && isIdentByte(s[i]) {
+				flags.WriteByte(s[i])
+				i++
+			}
+			return applyRegexFlags(flags.String(), sb.String()), true
+		}
+		if b == '\\' && i+1 < len(s) {
+			i++
+			sb.WriteByte('\\')
+			sb.WriteByte(s[i])
+		} else {
+			sb.WriteByte(b)
+		}
+		i++
+	}
+	return "", false // unterminated
+}
+
 func isIdentByte(b byte) bool {
 	return (b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z') || (b >= '0' && b <= '9') || b == '_'
 }

internal/cicontext/eval_test.go

@@ -5,10 +5,14 @@ import "testing"
 func TestEvalIf(t *testing.T) {
 	vars := func(key string) string {
 		m := map[string]string{
-			"CI_COMMIT_BRANCH": "develop",
-			"CI_COMMIT_TAG":    "",
+			"CI_COMMIT_BRANCH":  "develop",
+			"CI_COMMIT_TAG":     "",
 			"CI_PIPELINE_SOURCE": "push",
-			"DEPLOY_ENV":       "staging",
+			"DEPLOY_ENV":        "staging",
+			"BRANCH_PATTERN":    "/^dev/",
+			"BRANCH_PATTERN_CI": "/^DEV/i",
+			"EMPTY_PATTERN":     "",
+			"PLAIN_PATTERN":     "develop",
 		}
 		return m[key]
 	}
@@ -69,9 +73,59 @@ func TestEvalIf(t *testing.T) {
 		{"extra spaces", `  $CI_COMMIT_BRANCH  ==  "develop"  `, true},
 		{"tabs", "$CI_COMMIT_BRANCH\t==\t\"develop\"", true},
 
+		// ── Multi-line expressions (newlines between tokens) ──────────────────
+		{"multiline or true", "$CI_COMMIT_BRANCH == \"develop\" ||\n$CI_COMMIT_TAG != null", true},
+		{"multiline or false", "$CI_COMMIT_BRANCH == \"main\" ||\n$CI_COMMIT_TAG != null", false},
+		{"multiline and true", "$CI_COMMIT_BRANCH == \"develop\" &&\n$CI_PIPELINE_SOURCE == \"push\"", true},
+		{"multiline and false", "$CI_COMMIT_BRANCH == \"main\" &&\n$CI_PIPELINE_SOURCE == \"push\"", false},
+		{"multiline with crlf", "$CI_COMMIT_BRANCH == \"develop\" ||\r\n$CI_COMMIT_TAG != null", true},
+
+		// ── ${VAR} curly-brace syntax ─────────────────────────────────────────
+		{"curly var eq match", `${CI_COMMIT_BRANCH} == "develop"`, true},
+		{"curly var eq no match", `${CI_COMMIT_BRANCH} == "main"`, false},
+		{"curly var truthiness", `${CI_COMMIT_BRANCH}`, true},
+		{"curly var falsy", `${CI_COMMIT_TAG}`, false},
+		{"curly var neq null", `${CI_COMMIT_BRANCH} != null`, true},
+		{"curly mixed", `${CI_COMMIT_BRANCH} == "develop" && $CI_PIPELINE_SOURCE == "push"`, true},
+
+		// ── Regex flags (/pattern/i etc.) ─────────────────────────────────────
+		{"regex flag i match", `$CI_COMMIT_BRANCH =~ /^DEV/i`, true},
+		{"regex flag i no match", `$CI_COMMIT_BRANCH =~ /^MAIN/i`, false},
+		{"regex flag i not match", `$CI_COMMIT_BRANCH !~ /^MAIN/i`, true},
+		{"regex no flag case sensitive", `$CI_COMMIT_BRANCH =~ /^DEV/`, false},
+		{"regex flag i version tag", `$CI_PIPELINE_SOURCE =~ /^PUSH$/i`, true},
+
+		// ── Variable on right side of =~ ──────────────────────────────────────
+		{"var regex rhs match", `$CI_COMMIT_BRANCH =~ $BRANCH_PATTERN`, true},
+		{"var regex rhs no match", `$CI_PIPELINE_SOURCE =~ $BRANCH_PATTERN`, false},
+		{"var regex rhs ci flag match", `$CI_COMMIT_BRANCH =~ $BRANCH_PATTERN_CI`, true},
+		{"var regex rhs empty permissive", `$CI_COMMIT_BRANCH =~ $EMPTY_PATTERN`, true},
+		{"var regex rhs plain permissive", `$CI_COMMIT_BRANCH =~ $PLAIN_PATTERN`, true},
+		{"var regex rhs not match", `$CI_COMMIT_BRANCH !~ $BRANCH_PATTERN`, false},
+
+		// ── Bare true/false keywords ─────────────────────────────────────────
+		// GitLab CI treats true/false as the string values "true"/"false".
+		{"bare true match", `$CI_PIPELINE_SOURCE == true`, false},       // "push" != "true"
+		{"bare false match", `$CI_COMMIT_TAG == false`, false},           // "" != "false"
+		{"bare true var set to true", `$DEPLOY_ENV == true`, false},      // "staging" != "true"
+		{"bare false neq", `$CI_COMMIT_BRANCH != false`, true},           // "develop" != "false"
+		{"bare true in compound", `$CI_COMMIT_BRANCH != null && $CI_COMMIT_TAG == false`, false},
+
+		// ── Integer literals ──────────────────────────────────────────────────
+		// Compared as decimal strings (GitLab CI converts integers to strings).
+		{"int eq match", `$CI_PIPELINE_SOURCE != 0`, true},  // "push" != "0"
+		{"int eq no match", `$CI_COMMIT_TAG == 0`, false},    // "" != "0"
+		{"int in compound", `$CI_COMMIT_BRANCH != null && $CI_COMMIT_BRANCH != 0`, true},
+
 		// ── Permissive fallback ───────────────────────────────────────────────
 		{"unparseable returns true", `this is not valid syntax %%%`, true},
 		{"empty expr returns true", ``, true},
+
+		// ── Single = as alias for == ──────────────────────────────────────────
+		{"single eq match", `$CI_COMMIT_BRANCH = "develop"`, true},
+		{"single eq no match", `$CI_COMMIT_BRANCH = "main"`, false},
+		{"single eq in compound", `$CI_COMMIT_BRANCH = "develop" && $CI_PIPELINE_SOURCE = "push"`, true},
+		{"single eq compound false", `$CI_COMMIT_BRANCH = "main" && $CI_PIPELINE_SOURCE = "push"`, false},
 	}
 
 	for _, tc := range tests {
@@ -83,3 +137,48 @@ func TestEvalIf(t *testing.T) {
 		})
 	}
 }
+
+func TestEvalIfStrict(t *testing.T) {
+	vars := func(key string) string {
+		m := map[string]string{
+			"CI_COMMIT_BRANCH":   "develop",
+			"CI_PIPELINE_SOURCE": "push",
+			"WORKFLOW":           "",
+		}
+		return m[key]
+	}
+
+	tests := []struct {
+		name string
+		expr string
+		want bool
+	}{
+		// Parseable expressions behave identically to EvalIf.
+		{"parseable match", `$CI_COMMIT_BRANCH == "develop"`, true},
+		{"parseable no match", `$CI_COMMIT_BRANCH == "main"`, false},
+		{"single eq match", `$CI_COMMIT_BRANCH = "develop"`, true},
+		// Empty expression: ruleIfMatchesStrict handles the empty→true case
+		// before calling EvalIfStrict, so empty falls through to false here.
+		{"empty expr", ``, false},
+
+		// Unparseable expressions return false (strict) instead of true (permissive).
+		{"unparseable returns false", `this is not valid syntax %%%`, false},
+
+		// The key workflow-rule scenario: a complex condition with an
+		// unevaluable sub-expression should not match (strict=false) so that
+		// later workflow rules can be evaluated.
+		{"workflow rule complex no match", `$WORKFLOW = "gitflow" && $CI_PIPELINE_SOURCE == /(push|web)/`, false},
+
+		// Compound with a bad second operand: strict returns false.
+		{"and with bad rhs strict false", `$CI_COMMIT_BRANCH == "develop" && !(((`, false},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := EvalIfStrict(tc.expr, vars)
+			if got != tc.want {
+				t.Errorf("EvalIfStrict(%q) = %v, want %v", tc.expr, got, tc.want)
+			}
+		})
+	}
+}

internal/cicontext/reachability.go

@@ -28,26 +28,34 @@ func (s JobState) String() string {
 	}
 }
 
-// EvalWorkflow returns false when the pipeline's workflow:rules block would
-// prevent any pipeline from starting in the given context.
-// Returns true when ctx is empty, when there is no workflow block, or when no
-// rule is configured.
-func EvalWorkflow(p *model.Pipeline, ctx *Context) bool {
+// EvalWorkflow evaluates the pipeline's workflow:rules block against ctx.
+// Returns (runs, ruleVars):
+//   - runs=false means the pipeline would not start for this context.
+//   - ruleVars holds any variables: defined on the matching rule; inject these
+//     into the context so job rules can reference them.
+//
+// Returns (true, nil) when ctx is empty, when there is no workflow block, or
+// when no rules are configured.
+func EvalWorkflow(p *model.Pipeline, ctx *Context) (bool, map[string]string) {
 	if ctx.IsEmpty() || p.Workflow == nil || len(p.Workflow.Rules) == 0 {
-		return true
+		return true, nil
 	}
 	vars := ctx.Get
 	for _, rule := range p.Workflow.Rules {
-		if !ruleIfMatches(rule.If, vars) {
+		// Workflow rules use strict evaluation: an unparseable condition is
+		// treated as no-match so later rules (with valid conditions or a
+		// bare when:) are reached. Permissive-true would cause an early rule
+		// with a complex/invalid condition to block all subsequent rules.
+		if !ruleIfMatchesStrict(rule.If, vars) {
 			continue
 		}
 		when := rule.When
 		if when == "" {
 			when = "always"
 		}
-		return when != "never"
+		return when != "never", ExtractStringVars(rule.Variables)
 	}
-	return false // no rule matched → pipeline does not run
+	return false, nil // no rule matched → pipeline does not run
 }
 
 // EvalJob returns the effective JobState for job in the given context.
@@ -90,6 +98,13 @@ func ruleIfMatches(ifExpr string, vars func(string) string) bool {
 	return EvalIf(ifExpr, vars)
 }
 
+func ruleIfMatchesStrict(ifExpr string, vars func(string) string) bool {
+	if ifExpr == "" {
+		return true // no if: condition → rule always matches
+	}
+	return EvalIfStrict(ifExpr, vars)
+}
+
 func whenToState(when string) JobState {
 	switch when {
 	case "never":

internal/cicontext/reachability_test.go

@@ -0,0 +1,243 @@
+package cicontext
+
+import (
+	"testing"
+
+	"git.k3nny.fr/glint/internal/model"
+)
+
+func TestEvalWorkflow(t *testing.T) {
+	makePipeline := func(rules []model.Rule) *model.Pipeline {
+		return &model.Pipeline{Workflow: &model.Workflow{Rules: rules}}
+	}
+
+	tests := []struct {
+		name     string
+		rules    []model.Rule
+		branch   string
+		wantRuns bool
+		wantVars map[string]string
+	}{
+		{
+			name:     "no workflow block",
+			rules:    nil,
+			branch:   "main",
+			wantRuns: true,
+			wantVars: nil,
+		},
+		{
+			name: "matching rule runs always",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`, When: "always"},
+			},
+			branch:   "main",
+			wantRuns: true,
+		},
+		{
+			name: "matching rule when never",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`, When: "never"},
+			},
+			branch:   "main",
+			wantRuns: false,
+		},
+		{
+			name: "no rule matched",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`},
+			},
+			branch:   "develop",
+			wantRuns: false,
+		},
+		{
+			name: "matching rule with variables",
+			rules: []model.Rule{
+				{
+					If:   `$CI_COMMIT_BRANCH == "main"`,
+					When: "always",
+					Variables: map[string]any{
+						"DEPLOY_TARGET": "production",
+						"ENVIRONMENT":   "prod",
+					},
+				},
+				{When: "always"},
+			},
+			branch:   "main",
+			wantRuns: true,
+			wantVars: map[string]string{
+				"DEPLOY_TARGET": "production",
+				"ENVIRONMENT":   "prod",
+			},
+		},
+		{
+			name: "fallback rule with different variables",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`, Variables: map[string]any{"DEPLOY_TARGET": "production"}},
+				{When: "always", Variables: map[string]any{"DEPLOY_TARGET": "staging"}},
+			},
+			branch:   "develop",
+			wantRuns: true,
+			wantVars: map[string]string{"DEPLOY_TARGET": "staging"},
+		},
+		{
+			name: "empty context always runs",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`, When: "never"},
+			},
+			branch:   "", // no context
+			wantRuns: true,
+			wantVars: nil,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			var p *model.Pipeline
+			if tc.rules == nil {
+				p = &model.Pipeline{}
+			} else {
+				p = makePipeline(tc.rules)
+			}
+			ctx := New(tc.branch, "", "", nil)
+			runs, vars := EvalWorkflow(p, ctx)
+			if runs != tc.wantRuns {
+				t.Errorf("EvalWorkflow runs = %v, want %v", runs, tc.wantRuns)
+			}
+			for k, want := range tc.wantVars {
+				if got := vars[k]; got != want {
+					t.Errorf("EvalWorkflow vars[%q] = %q, want %q", k, got, want)
+				}
+			}
+			if len(vars) != len(tc.wantVars) {
+				t.Errorf("EvalWorkflow returned %d vars, want %d; got %v", len(vars), len(tc.wantVars), vars)
+			}
+		})
+	}
+}
+
+func TestContextInject(t *testing.T) {
+	t.Run("inject does not overwrite pinned var", func(t *testing.T) {
+		ctx := New("main", "", "", []string{"DEPLOY_TARGET=override"})
+		ctx.Inject("DEPLOY_TARGET", "workflow-value")
+		if got := ctx.Get("DEPLOY_TARGET"); got != "override" {
+			t.Errorf("Inject overwrote pinned var: got %q, want %q", got, "override")
+		}
+	})
+	t.Run("inject does not overwrite shortcut var", func(t *testing.T) {
+		ctx := New("main", "", "", nil)
+		ctx.Inject("CI_COMMIT_BRANCH", "other")
+		if got := ctx.Get("CI_COMMIT_BRANCH"); got != "main" {
+			t.Errorf("Inject overwrote shortcut var: got %q, want %q", got, "main")
+		}
+	})
+	t.Run("inject sets new variable", func(t *testing.T) {
+		ctx := New("main", "", "", nil)
+		ctx.Inject("DEPLOY_TARGET", "production")
+		if got := ctx.Get("DEPLOY_TARGET"); got != "production" {
+			t.Errorf("Inject did not set variable: got %q", got)
+		}
+	})
+	t.Run("inject later call overrides earlier call", func(t *testing.T) {
+		ctx := New("main", "", "", nil)
+		ctx.Inject("DEPLOY_TARGET", "pipeline-default")
+		ctx.Inject("DEPLOY_TARGET", "workflow-override")
+		if got := ctx.Get("DEPLOY_TARGET"); got != "workflow-override" {
+			t.Errorf("second Inject did not win: got %q, want %q", got, "workflow-override")
+		}
+	})
+}
+
+func TestExtractStringVars(t *testing.T) {
+	tests := []struct {
+		name string
+		in   map[string]any
+		want map[string]string
+	}{
+		{
+			name: "plain strings",
+			in:   map[string]any{"A": "hello", "B": "world"},
+			want: map[string]string{"A": "hello", "B": "world"},
+		},
+		{
+			name: "extended value form",
+			in: map[string]any{
+				"KEY": map[string]any{"value": "extended", "description": "some desc"},
+			},
+			want: map[string]string{"KEY": "extended"},
+		},
+		{
+			name: "mixed forms",
+			in: map[string]any{
+				"PLAIN":   "str",
+				"COMPLEX": map[string]any{"value": "val"},
+			},
+			want: map[string]string{"PLAIN": "str", "COMPLEX": "val"},
+		},
+		{
+			name: "nil map",
+			in:   nil,
+			want: nil,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := ExtractStringVars(tc.in)
+			for k, want := range tc.want {
+				if got[k] != want {
+					t.Errorf("ExtractStringVars[%q] = %q, want %q", k, got[k], want)
+				}
+			}
+			if len(got) != len(tc.want) {
+				t.Errorf("ExtractStringVars returned %d entries, want %d", len(got), len(tc.want))
+			}
+		})
+	}
+}
+
+// TestWorkflowVarsJobEval verifies the end-to-end flow: workflow rule injects
+// DEPLOY_TARGET, which is then used in a job's rules:if: expression.
+func TestWorkflowVarsJobEval(t *testing.T) {
+	rules := []model.Rule{
+		{If: `$CI_COMMIT_BRANCH == "main"`, Variables: map[string]any{"DEPLOY_TARGET": "production"}},
+		{When: "always", Variables: map[string]any{"DEPLOY_TARGET": "staging"}},
+	}
+	p := &model.Pipeline{
+		Workflow: &model.Workflow{Rules: rules},
+		Jobs: map[string]model.Job{
+			"deploy-prod": {
+				Rules: []model.Rule{
+					{If: `$DEPLOY_TARGET == "production"`, When: "on_success"},
+					{When: "never"},
+				},
+			},
+			"deploy-staging": {
+				Rules: []model.Rule{
+					{If: `$DEPLOY_TARGET == "staging"`, When: "on_success"},
+					{When: "never"},
+				},
+			},
+		},
+	}
+
+	for _, tc := range []struct {
+		branch      string
+		wantProd    JobState
+		wantStaging JobState
+	}{
+		{"main", JobActive, JobSkipped},
+		{"develop", JobSkipped, JobActive},
+	} {
+		ctx := New(tc.branch, "", "", nil)
+		_, ruleVars := EvalWorkflow(p, ctx)
+		for k, v := range ruleVars {
+			ctx.Inject(k, v)
+		}
+		if got := EvalJob(p.Jobs["deploy-prod"], ctx); got != tc.wantProd {
+			t.Errorf("branch=%q deploy-prod = %v, want %v", tc.branch, got, tc.wantProd)
+		}
+		if got := EvalJob(p.Jobs["deploy-staging"], ctx); got != tc.wantStaging {
+			t.Errorf("branch=%q deploy-staging = %v, want %v", tc.branch, got, tc.wantStaging)
+		}
+	}
+}

internal/config/config.go

@@ -0,0 +1,75 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Filename is the name of the project-level glint configuration file.
+const Filename = ".glint.yml"
+
+// Config holds project-level glint configuration loaded from .glint.yml.
+type Config struct {
+	// Ignore lists rule IDs to suppress entirely (e.g. ["GL007", "GL032"]).
+	Ignore []string `yaml:"ignore"`
+
+	// Severity maps rule IDs to overridden severity levels.
+	// Valid values: "error", "warning", "ignore".
+	// "ignore" is equivalent to listing the rule in Ignore.
+	Severity map[string]string `yaml:"severity"`
+
+	// Stages lists additional stage names that are considered valid for this
+	// project, beyond what is declared in the pipeline's own stages: block.
+	// Jobs in these stages are not flagged by GL004.
+	Stages []string `yaml:"stages"`
+
+	// Token is a default GitLab personal access token used when neither the
+	// --token flag nor GITLAB_TOKEN (/ CI_JOB_TOKEN / GITLAB_PRIVATE_TOKEN)
+	// environment variables are set.
+	Token string `yaml:"token"`
+
+	// URL is the default GitLab instance URL. Overridden by --gitlab-url and
+	// the CI_SERVER_URL / GITLAB_URL environment variables.
+	URL string `yaml:"url"`
+
+	// CacheDir is the default directory for caching fetched remote includes.
+	// Overridden by the --cache-dir flag.
+	CacheDir string `yaml:"cache_dir"`
+}
+
+// Load searches for a .glint.yml file starting from dir and walking up toward
+// the filesystem root. The walk stops at the first .git directory found (the
+// repository root) or at the filesystem root. Returns an empty Config (and no
+// error) when no config file is found.
+func Load(dir string) (Config, error) {
+	dir = filepath.Clean(dir)
+	for {
+		candidate := filepath.Join(dir, Filename)
+		data, err := os.ReadFile(candidate)
+		if err == nil {
+			var cfg Config
+			if yerr := yaml.Unmarshal(data, &cfg); yerr != nil {
+				return Config{}, fmt.Errorf("parsing %s: %w", candidate, yerr)
+			}
+			return cfg, nil
+		}
+		if !os.IsNotExist(err) {
+			return Config{}, fmt.Errorf("reading %s: %w", candidate, err)
+		}
+
+		// Stop when we reach a git root so we don't wander into parent repos.
+		if _, serr := os.Stat(filepath.Join(dir, ".git")); serr == nil {
+			break
+		}
+
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			break // filesystem root
+		}
+		dir = parent
+	}
+	return Config{}, nil
+}

internal/config/config_test.go

@@ -0,0 +1,112 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoad_NotFound(t *testing.T) {
+	tmp := t.TempDir()
+	cfg, err := Load(tmp)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(cfg.Ignore) != 0 || cfg.Token != "" || cfg.URL != "" {
+		t.Errorf("expected empty config, got %+v", cfg)
+	}
+}
+
+func TestLoad_Found(t *testing.T) {
+	tmp := t.TempDir()
+	content := `
+ignore:
+  - GL007
+  - GL032
+severity:
+  GL004: warning
+stages:
+  - quality
+token: glpat-test
+url: https://gitlab.example.com
+cache_dir: /tmp/glint-cache
+`
+	if err := os.WriteFile(filepath.Join(tmp, Filename), []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(tmp)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if len(cfg.Ignore) != 2 || cfg.Ignore[0] != "GL007" {
+		t.Errorf("ignore = %v", cfg.Ignore)
+	}
+	if cfg.Severity["GL004"] != "warning" {
+		t.Errorf("severity = %v", cfg.Severity)
+	}
+	if len(cfg.Stages) != 1 || cfg.Stages[0] != "quality" {
+		t.Errorf("stages = %v", cfg.Stages)
+	}
+	if cfg.Token != "glpat-test" {
+		t.Errorf("token = %q", cfg.Token)
+	}
+	if cfg.URL != "https://gitlab.example.com" {
+		t.Errorf("url = %q", cfg.URL)
+	}
+	if cfg.CacheDir != "/tmp/glint-cache" {
+		t.Errorf("cache_dir = %q", cfg.CacheDir)
+	}
+}
+
+func TestLoad_WalksUp(t *testing.T) {
+	tmp := t.TempDir()
+	sub := filepath.Join(tmp, "subdir", "pipeline")
+	if err := os.MkdirAll(sub, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// Config at the top-level (no .git, so walk continues to tmp).
+	if err := os.WriteFile(filepath.Join(tmp, Filename), []byte("token: walked-up\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(sub)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if cfg.Token != "walked-up" {
+		t.Errorf("token = %q, want walked-up", cfg.Token)
+	}
+}
+
+func TestLoad_StopsAtGitRoot(t *testing.T) {
+	tmp := t.TempDir()
+	sub := filepath.Join(tmp, "repo", "src")
+	if err := os.MkdirAll(sub, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// .git marks the repo root — walk must stop here.
+	if err := os.Mkdir(filepath.Join(tmp, "repo", ".git"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// Config placed ABOVE the .git root should not be found.
+	if err := os.WriteFile(filepath.Join(tmp, Filename), []byte("token: should-not-load\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(sub)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if cfg.Token != "" {
+		t.Errorf("token = %q, should not have crossed .git boundary", cfg.Token)
+	}
+}
+
+func TestLoad_InvalidYAML(t *testing.T) {
+	tmp := t.TempDir()
+	if err := os.WriteFile(filepath.Join(tmp, Filename), []byte("ignore: [unclosed\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	_, err := Load(tmp)
+	if err == nil {
+		t.Error("expected error for invalid YAML")
+	}
+}

internal/fetcher/cache.go

@@ -0,0 +1,41 @@
+package fetcher
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// cacheRead returns the cached bytes for the given cache key, or (nil, false)
+// on a miss (key not present, dir empty, or any read error).
+func cacheRead(dir, key string) ([]byte, bool) {
+	if dir == "" {
+		return nil, false
+	}
+	data, err := os.ReadFile(cachePath(dir, key))
+	if err != nil {
+		return nil, false
+	}
+	return data, true
+}
+
+// cacheWrite stores bytes in the cache for the given key. Write errors are
+// silently ignored so cache failures never block the normal fetch path.
+func cacheWrite(dir, key string, data []byte) {
+	if dir == "" {
+		return
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return
+	}
+	_ = os.WriteFile(cachePath(dir, key), data, 0o644)
+}
+
+// cachePath returns the filesystem path for a cache entry.
+// The filename is the SHA-256 hex digest of the key so arbitrary keys (URLs,
+// "project:file@ref" strings) map to safe, stable filenames.
+func cachePath(dir, key string) string {
+	h := sha256.Sum256([]byte(key))
+	return filepath.Join(dir, fmt.Sprintf("%x.yml", h))
+}

internal/fetcher/gitlab.go

@@ -22,9 +22,11 @@ const (
 
 // GitLabConfig holds everything needed to reach a GitLab instance.
 type GitLabConfig struct {
-	BaseURL string
-	Token   string
-	Source  TokenSource
+	BaseURL  string
+	Token    string
+	Source   TokenSource
+	CacheDir string // local cache directory; empty = caching disabled
+	Offline  bool   // when true, return an error instead of making network calls
 }
 
 // AutoConfig builds a GitLabConfig from environment variables.
@@ -54,8 +56,11 @@ func AutoConfig() GitLabConfig {
 	return cfg
 }
 
-// WithOverrides returns a copy of cfg with non-empty overrides applied.
-func (cfg GitLabConfig) WithOverrides(baseURL, token string) GitLabConfig {
+// WithOverrides returns a copy of cfg with the provided overrides applied.
+// Non-empty strings overwrite the corresponding field; booleans are always
+// applied (so offline: false explicitly clears offline mode).
+// cacheDir: empty string disables caching.
+func (cfg GitLabConfig) WithOverrides(baseURL, token, cacheDir string, offline bool) GitLabConfig {
 	if baseURL != "" {
 		cfg.BaseURL = strings.TrimRight(baseURL, "/")
 	}
@@ -63,6 +68,8 @@ func (cfg GitLabConfig) WithOverrides(baseURL, token string) GitLabConfig {
 		cfg.Token = token
 		cfg.Source = TokenPrivate
 	}
+	cfg.CacheDir = cacheDir
+	cfg.Offline = offline
 	return cfg
 }
 
@@ -84,16 +91,24 @@ func (cfg GitLabConfig) HasToken() bool { return cfg.Token != "" }
 //   - filePath — repository file path, e.g. "/templates/ci.yml"
 //   - ref      — branch, tag, or commit SHA; empty string defaults to HEAD
 func (cfg GitLabConfig) FetchFile(project, filePath, ref string) ([]byte, error) {
+	if ref == "" {
+		ref = "HEAD"
+	}
+
+	cKey := cfg.BaseURL + "|" + project + "|" + filePath + "|" + ref
+	if data, ok := cacheRead(cfg.CacheDir, cKey); ok {
+		return data, nil
+	}
+	if cfg.Offline {
+		return nil, fmt.Errorf("offline mode: %s:%s@%s is not in the local cache (run without --offline first to populate the cache)", project, filePath, ref)
+	}
+
 	encodedProject := url.PathEscape(project)
 	encodedFile := url.PathEscape(strings.TrimPrefix(filePath, "/"))
 
 	apiURL := fmt.Sprintf("%s/api/v4/projects/%s/repository/files/%s/raw",
 		cfg.BaseURL, encodedProject, encodedFile)
 
-	if ref == "" {
-		ref = "HEAD"
-	}
-
 	req, err := http.NewRequest(http.MethodGet, apiURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("building request: %w", err)
@@ -139,6 +154,34 @@ func (cfg GitLabConfig) FetchFile(project, filePath, ref string) ([]byte, error)
 		}
 	}
 
+	cacheWrite(cfg.CacheDir, cKey, body)
+	return body, nil
+}
+
+// FetchURL downloads the content at a plain HTTPS URL without authentication.
+// Used for include: remote: entries which are public by definition.
+// Responses are read from and written to the local cache when CacheDir is set.
+func (cfg GitLabConfig) FetchURL(rawURL string) ([]byte, error) {
+	if data, ok := cacheRead(cfg.CacheDir, rawURL); ok {
+		return data, nil
+	}
+	if cfg.Offline {
+		return nil, fmt.Errorf("offline mode: %s is not in the local cache (run without --offline first to populate the cache)", rawURL)
+	}
+
+	resp, err := http.Get(rawURL) //nolint:noctx
+	if err != nil {
+		return nil, fmt.Errorf("GET %s: %w", rawURL, err)
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading body: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("GET %s: status %d", rawURL, resp.StatusCode)
+	}
+	cacheWrite(cfg.CacheDir, rawURL, body)
 	return body, nil
 }
 

internal/graph/includes.go

@@ -2,12 +2,226 @@ package graph
 
 import (
 	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
 	"strings"
+
+	"git.k3nny.fr/glint/internal/fetcher"
+	"git.k3nny.fr/glint/internal/model"
 )
 
-// Includes returns a Mermaid flowchart showing include file dependencies.
-// sourcePath is the path to the main pipeline file; rawIncludes is Pipeline.Include.
-func Includes(sourcePath string, rawIncludes []any) string {
+// Includes returns a Mermaid flowchart of the full include dependency tree.
+// Each node shows the jobs defined directly in that file, connected with
+// dashed arrows (solid arrows represent the include hierarchy itself).
+// It recurses into project:, component:, and local: includes to expose
+// transitive dependencies. Includes that cannot be fetched are shown but not expanded.
+func Includes(sourcePath string, rawIncludes []any, cfg fetcher.GitLabConfig) string {
+	b := &treeBuilder{
+		visited: map[string]bool{},
+		cfg:     cfg,
+		baseDir: filepath.Dir(sourcePath),
+	}
+	root := &treeNode{
+		id:    "root",
+		label: mermaidLabel(sourcePath),
+		class: "main",
+		jobs:  directJobs(sourcePath),
+	}
+	b.buildChildren(root, rawIncludes)
+	return renderTree(root)
+}
+
+type treeNode struct {
+	id       string
+	label    string
+	class    string
+	children []*treeNode
+	jobs     []string // job names defined directly in this file
+}
+
+// treeBuilder accumulates state while recursively traversing include entries.
+type treeBuilder struct {
+	counter int
+	visited map[string]bool // prevents infinite loops on circular includes
+	cfg     fetcher.GitLabConfig
+	baseDir string // directory of the current pipeline file; changes for local includes
+}
+
+func (b *treeBuilder) nextID() string {
+	b.counter++
+	return fmt.Sprintf("inc%d", b.counter)
+}
+
+func (b *treeBuilder) buildChildren(parent *treeNode, rawIncludes []any) {
+	for _, entry := range rawIncludes {
+		parent.children = append(parent.children, b.parseEntry(entry)...)
+	}
+}
+
+func (b *treeBuilder) parseEntry(entry any) []*treeNode {
+	switch v := entry.(type) {
+	case string:
+		node := &treeNode{id: b.nextID(), label: "local: " + mermaidLabel(v), class: "local"}
+		b.recurseLocal(node, v)
+		return []*treeNode{node}
+	case map[string]any:
+		return b.parseMap(v)
+	}
+	return nil
+}
+
+func (b *treeBuilder) parseMap(m map[string]any) []*treeNode {
+	if comp, ok := m["component"].(string); ok {
+		node := &treeNode{
+			id:    b.nextID(),
+			label: "component:<br>" + mermaidLabel(comp),
+			class: "component",
+		}
+		b.recurseComponent(node, comp)
+		return []*treeNode{node}
+	}
+	if proj, ok := m["project"].(string); ok {
+		ref, _ := m["ref"].(string)
+		if ref == "" {
+			ref = "HEAD"
+		}
+		files := includeFileList(m["file"])
+		if len(files) == 0 {
+			return []*treeNode{{
+				id:    b.nextID(),
+				label: fmt.Sprintf("project: %s @ %s", mermaidLabel(proj), ref),
+				class: "project",
+			}}
+		}
+		var nodes []*treeNode
+		for _, f := range files {
+			node := &treeNode{
+				id:    b.nextID(),
+				label: fmt.Sprintf("project: %s<br>%s @ %s", mermaidLabel(proj), mermaidLabel(f), ref),
+				class: "project",
+			}
+			b.recurseProject(node, proj, f, ref)
+			nodes = append(nodes, node)
+		}
+		return nodes
+	}
+	if local, ok := m["local"].(string); ok {
+		node := &treeNode{id: b.nextID(), label: "local: " + mermaidLabel(local), class: "local"}
+		b.recurseLocal(node, local)
+		return []*treeNode{node}
+	}
+	if remote, ok := m["remote"].(string); ok {
+		node := &treeNode{id: b.nextID(), label: "remote:<br>" + mermaidLabel(remote), class: "remote"}
+		b.recurseRemote(node, remote)
+		return []*treeNode{node}
+	}
+	if tmpl, ok := m["template"].(string); ok {
+		return []*treeNode{{id: b.nextID(), label: "template:<br>" + mermaidLabel(tmpl), class: "template"}}
+	}
+	return nil
+}
+
+func (b *treeBuilder) recurseLocal(node *treeNode, path string) {
+	absPath := filepath.Join(b.baseDir, path)
+	key := "local:" + absPath
+	if b.visited[key] {
+		return
+	}
+	b.visited[key] = true
+
+	data, err := os.ReadFile(absPath)
+	if err != nil {
+		return
+	}
+	p, err := model.ParseBytes(data)
+	if err != nil {
+		return
+	}
+	node.jobs = jobNames(p)
+	if len(p.Include) == 0 {
+		return
+	}
+	orig := b.baseDir
+	b.baseDir = filepath.Dir(absPath)
+	b.buildChildren(node, p.Include)
+	b.baseDir = orig
+}
+
+func (b *treeBuilder) recurseProject(node *treeNode, project, filePath, ref string) {
+	key := fmt.Sprintf("project:%s:%s@%s", project, filePath, ref)
+	if b.visited[key] || !b.cfg.HasToken() || filePath == "" {
+		return
+	}
+	b.visited[key] = true
+
+	data, err := b.cfg.FetchFile(project, filePath, ref)
+	if err != nil {
+		return
+	}
+	p, err := model.ParseBytes(data)
+	if err != nil {
+		return
+	}
+	node.jobs = jobNames(p)
+	if len(p.Include) == 0 {
+		return
+	}
+	b.buildChildren(node, p.Include)
+}
+
+func (b *treeBuilder) recurseRemote(node *treeNode, rawURL string) {
+	key := "remote:" + rawURL
+	if b.visited[key] {
+		return
+	}
+	b.visited[key] = true
+
+	data, err := b.cfg.FetchURL(rawURL)
+	if err != nil {
+		return
+	}
+	p, err := model.ParseBytes(data)
+	if err != nil {
+		return
+	}
+	node.jobs = jobNames(p)
+	if len(p.Include) == 0 {
+		return
+	}
+	b.buildChildren(node, p.Include)
+}
+
+func (b *treeBuilder) recurseComponent(node *treeNode, ref string) {
+	if strings.ContainsRune(ref, '$') {
+		return
+	}
+	key := "component:" + ref
+	if b.visited[key] {
+		return
+	}
+	b.visited[key] = true
+
+	host, project, component, version, err := parseComponentRef(ref)
+	if err != nil {
+		return
+	}
+	data, err := fetchComponentFile(b.cfg.ForHost(host), project, component, version)
+	if err != nil {
+		return
+	}
+	p, err := model.ParseBytes(data)
+	if err != nil {
+		return
+	}
+	node.jobs = jobNames(p)
+	if len(p.Include) == 0 {
+		return
+	}
+	b.buildChildren(node, p.Include)
+}
+
+func renderTree(root *treeNode) string {
 	var sb strings.Builder
 	w := func(s string) { sb.WriteString(s + "\n") }
 	wf := func(f string, a ...any) { fmt.Fprintf(&sb, f+"\n", a...) }
@@ -22,85 +236,84 @@ func Includes(sourcePath string, rawIncludes []any) string {
 	w("    classDef local fill:#428fdc,stroke:#1068bf,color:#fff")
 	w("    classDef remote fill:#868686,stroke:#686868,color:#fff")
 	w("    classDef template fill:#fc6d26,stroke:#e56b1f,color:#fff")
-	w("")
-	wf("    root[\"%s\"]:::main", mermaidLabel(sourcePath))
-
-	if len(rawIncludes) == 0 {
-		return sb.String()
-	}
-
+	w("    classDef job fill:#f5f5ff,stroke:#7175a0,color:#333")
 	w("")
 
-	counter := 0
-	for _, entry := range rawIncludes {
-		for _, n := range parseIncludeEntry(entry, &counter) {
-			wf("    %s[\"%s\"]:::%s", n.id, n.label, n.class)
-			wf("    root --> %s", n.id)
+	jobCounter := 0
+	var emit func(n *treeNode)
+	emit = func(n *treeNode) {
+		wf("    %s[\"%s\"]:::%s", n.id, n.label, n.class)
+		for _, jobName := range n.jobs {
+			jobCounter++
+			jobID := fmt.Sprintf("job%d", jobCounter)
+			wf("    %s(\"%s\"):::job", jobID, mermaidLabel(jobName))
+			wf("    %s -.-> %s", n.id, jobID)
+		}
+		for _, child := range n.children {
+			emit(child)
+			wf("    %s --> %s", n.id, child.id)
 		}
 	}
+	emit(root)
 
 	return sb.String()
 }
 
-type incNode struct {
-	id, label, class string
+// directJobs parses a single pipeline file (without include resolution) and
+// returns the sorted list of job names defined directly in it.
+func directJobs(path string) []string {
+	p, err := model.Parse(path)
+	if err != nil {
+		return nil
+	}
+	return jobNames(p)
 }
 
-func parseIncludeEntry(entry any, counter *int) []incNode {
-	newID := func() string {
-		*counter++
-		return fmt.Sprintf("inc%d", *counter)
+// jobNames returns a sorted slice of all job names defined in p.
+func jobNames(p *model.Pipeline) []string {
+	if len(p.Jobs) == 0 {
+		return nil
 	}
-	switch v := entry.(type) {
-	case string:
-		return []incNode{{id: newID(), label: mermaidLabel(v), class: "local"}}
-	case map[string]any:
-		return parseIncludeMap(v, newID)
+	names := make([]string, 0, len(p.Jobs))
+	for name := range p.Jobs {
+		names = append(names, name)
 	}
-	return nil
+	sort.Strings(names)
+	return names
 }
 
-func parseIncludeMap(m map[string]any, newID func() string) []incNode {
-	if comp, ok := m["component"].(string); ok {
-		return []incNode{{
-			id:    newID(),
-			label: "component:<br>" + mermaidLabel(comp),
-			class: "component",
-		}}
+// parseComponentRef parses a CI/CD component reference of the form
+// <host>/<project-path>/<component-name>@<version>.
+func parseComponentRef(ref string) (host, project, component, version string, err error) {
+	atIdx := strings.LastIndex(ref, "@")
+	if atIdx < 0 || atIdx == len(ref)-1 {
+		err = fmt.Errorf("component reference %q must include a version", ref)
+		return
 	}
-	if proj, ok := m["project"].(string); ok {
-		ref, _ := m["ref"].(string)
-		if ref == "" {
-			ref = "HEAD"
-		}
-		files := includeFileList(m["file"])
-		if len(files) == 0 {
-			return []incNode{{
-				id:    newID(),
-				label: fmt.Sprintf("project: %s @ %s", mermaidLabel(proj), ref),
-				class: "project",
-			}}
-		}
-		var nodes []incNode
-		for _, f := range files {
-			nodes = append(nodes, incNode{
-				id:    newID(),
-				label: fmt.Sprintf("project: %s<br>%s @ %s", mermaidLabel(proj), mermaidLabel(f), ref),
-				class: "project",
-			})
-		}
-		return nodes
+	version = ref[atIdx+1:]
+	path := ref[:atIdx]
+	parts := strings.Split(path, "/")
+	if len(parts) < 3 {
+		err = fmt.Errorf("component reference %q must be <host>/<project>/<component>@<version>", ref)
+		return
 	}
-	if local, ok := m["local"].(string); ok {
-		return []incNode{{id: newID(), label: "local: " + mermaidLabel(local), class: "local"}}
+	host = parts[0]
+	component = parts[len(parts)-1]
+	project = strings.Join(parts[1:len(parts)-1], "/")
+	return
+}
+
+// fetchComponentFile fetches a component's template YAML, trying the single-file
+// layout first and the directory layout as fallback.
+func fetchComponentFile(cfg fetcher.GitLabConfig, project, component, version string) ([]byte, error) {
+	if data, err := cfg.FetchFile(project, "templates/"+component+".yml", version); err == nil {
+		return data, nil
 	}
-	if remote, ok := m["remote"].(string); ok {
-		return []incNode{{id: newID(), label: "remote:<br>" + mermaidLabel(remote), class: "remote"}}
+	data, err := cfg.FetchFile(project, "templates/"+component+"/template.yml", version)
+	if err != nil {
+		return nil, fmt.Errorf("component %s/%s@%s not found", project, component, version)
 	}
-	if tmpl, ok := m["template"].(string); ok {
-		return []incNode{{id: newID(), label: "template:<br>" + mermaidLabel(tmpl), class: "template"}}
-	}
-	return nil
+	return data, nil
 }
 
 func includeFileList(v any) []string {

internal/graph/tree.go

@@ -0,0 +1,113 @@
+package graph
+
+import (
+	"sort"
+	"strings"
+
+	"git.k3nny.fr/glint/internal/cicontext"
+	"git.k3nny.fr/glint/internal/model"
+)
+
+// Tree returns a tree-command-style text representation of pipeline jobs
+// grouped by stage.
+//
+// Hidden template jobs (names starting with ".") are excluded.
+// When ctx is non-nil and non-empty, each job is annotated with its evaluated
+// state ([skipped] or [manual]); active jobs carry no annotation.
+// Without a context, job-type annotations ([manual], [delayed], [trigger]) are
+// shown instead.
+func Tree(p *model.Pipeline, ctx *cicontext.Context) string {
+	var sb strings.Builder
+
+	// Collect visible jobs.
+	var visible []string
+	for name := range p.Jobs {
+		if !strings.HasPrefix(name, ".") {
+			visible = append(visible, name)
+		}
+	}
+	sort.Strings(visible)
+
+	// Group by stage.
+	byStage := make(map[string][]string)
+	for _, name := range visible {
+		stage := p.Jobs[name].Stage
+		if stage == "" {
+			stage = "test"
+		}
+		byStage[stage] = append(byStage[stage], name)
+	}
+
+	// Build ordered stage list: declared first, then extras.
+	seen := make(map[string]bool)
+	var stages []string
+	for _, s := range p.Stages {
+		if len(byStage[s]) > 0 && !seen[s] {
+			stages = append(stages, s)
+			seen[s] = true
+		}
+	}
+	for _, name := range visible {
+		stage := p.Jobs[name].Stage
+		if stage == "" {
+			stage = "test"
+		}
+		if !seen[stage] {
+			stages = append(stages, stage)
+			seen[stage] = true
+		}
+	}
+
+	sb.WriteString("pipeline\n")
+
+	for si, stage := range stages {
+		lastStage := si == len(stages)-1
+		stagePrefix, childPrefix := branchChars(lastStage)
+
+		sb.WriteString(stagePrefix + stage + "\n")
+
+		jobs := byStage[stage]
+		sort.Strings(jobs)
+		for ji, name := range jobs {
+			lastJob := ji == len(jobs)-1
+			jobBranch, _ := branchChars(lastJob)
+			sb.WriteString(childPrefix + jobBranch + jobLabel(p.Jobs[name], name, ctx) + "\n")
+		}
+	}
+
+	return sb.String()
+}
+
+func branchChars(last bool) (branch, continuation string) {
+	if last {
+		return "└── ", "    "
+	}
+	return "├── ", "│   "
+}
+
+func jobLabel(job model.Job, name string, ctx *cicontext.Context) string {
+	if ctx != nil && !ctx.IsEmpty() {
+		switch cicontext.EvalJob(job, ctx) {
+		case cicontext.JobSkipped:
+			return name + " [skipped]"
+		case cicontext.JobManual:
+			return name + " [manual]"
+		}
+		return name
+	}
+	// No context: annotate by job type.
+	var tags []string
+	if job.When == "manual" {
+		tags = append(tags, "manual")
+	}
+	if job.When == "delayed" {
+		tags = append(tags, "delayed")
+	}
+	if job.Trigger != nil {
+		tags = append(tags, "trigger")
+	}
+	if len(tags) == 0 {
+		return name
+	}
+	return name + " [" + strings.Join(tags, ", ") + "]"
+}

internal/linter/dead_rules_test.go

@@ -0,0 +1,90 @@
+package linter
+
+import (
+	"testing"
+
+	"git.k3nny.fr/glint/internal/model"
+)
+
+func TestCheckDeadRules(t *testing.T) {
+	cases := []struct {
+		name     string
+		rules    []model.Rule
+		wantHit  bool // whether GL033 should fire
+	}{
+		{
+			name:    "no rules — not dead",
+			rules:   nil,
+			wantHit: false,
+		},
+		{
+			name:    "single bare when:never — dead",
+			rules:   []model.Rule{{When: "never"}},
+			wantHit: true,
+		},
+		{
+			name: "all rules when:never with if — dead",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`, When: "never"},
+				{If: `$CI_COMMIT_BRANCH == "develop"`, When: "never"},
+				{When: "never"},
+			},
+			wantHit: true,
+		},
+		{
+			name: "first rule on_success — not dead",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`, When: "on_success"},
+				{When: "never"},
+			},
+			wantHit: false,
+		},
+		{
+			name: "rule with empty when (defaults to on_success) — not dead",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`},
+				{When: "never"},
+			},
+			wantHit: false,
+		},
+		{
+			name:    "when:manual — not dead",
+			rules:   []model.Rule{{When: "manual"}},
+			wantHit: false,
+		},
+		{
+			name:    "when:always — not dead",
+			rules:   []model.Rule{{When: "always"}},
+			wantHit: false,
+		},
+		{
+			name:    "when:on_failure — not dead",
+			rules:   []model.Rule{{When: "on_failure"}},
+			wantHit: false,
+		},
+		{
+			name: "mixed never and manual — not dead",
+			rules: []model.Rule{
+				{If: `$CI_COMMIT_BRANCH == "main"`, When: "never"},
+				{When: "manual"},
+			},
+			wantHit: false,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			job := model.Job{Rules: tc.rules}
+			findings := checkDeadRules("test-job", job)
+			hit := false
+			for _, f := range findings {
+				if f.Rule == RuleDeadRules {
+					hit = true
+				}
+			}
+			if hit != tc.wantHit {
+				t.Errorf("checkDeadRules: got hit=%v, want hit=%v; findings=%v", hit, tc.wantHit, findings)
+			}
+		})
+	}
+}

internal/linter/dependencies.go

@@ -23,7 +23,10 @@ func checkDependencies(p *model.Pipeline) []Finding {
 			if !exists {
 				findings = append(findings, Finding{
 					Severity: Error,
+					Rule:     RuleUnknownDependency,
 					Job:      name,
+					File:     job.File,
+					Line:     job.Line,
 					Message:  fmt.Sprintf("'dependencies' references unknown job %q", dep),
 				})
 				continue
@@ -33,7 +36,10 @@ func checkDependencies(p *model.Pipeline) []Finding {
 				if depHasStage && depIdx >= jobStageIdx {
 					findings = append(findings, Finding{
 						Severity: Error,
+						Rule:     RuleDependencyStage,
 						Job:      name,
+						File:     job.File,
+						Line:     job.Line,
 						Message:  fmt.Sprintf("'dependencies' job %q must be in an earlier stage (in %q, current job is in %q)", dep, depJob.Stage, job.Stage),
 					})
 				}

internal/linter/keywords.go

@@ -8,6 +8,15 @@ import (
 	"git.k3nny.fr/glint/internal/model"
 )
 
+// dnsLabelPattern matches a valid hostname label: starts and ends with
+// alphanumeric, middle may contain hyphens and dots; max 63 chars per label.
+var dnsLabelPattern = regexp.MustCompile(`^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$`)
+
+// timeoutPattern matches a GitLab CI duration string: one or more pairs of
+// "<number> <unit>" where unit is a recognised time word or abbreviation.
+var timeoutPattern = regexp.MustCompile(
+	`(?i)^\s*(\d+\s*(weeks?|w|days?|d|hours?|h|minutes?|mins?|m|seconds?|secs?|s)\s*)+$`)
+
 var validJobWhen = map[string]bool{
 	"on_success": true,
 	"on_failure": true,
@@ -95,8 +104,16 @@ func checkJobKeywords(name string, job model.Job) []Finding {
 	findings = append(findings, checkArtifacts(name, job)...)
 	findings = append(findings, checkCache(name, job)...)
 	findings = append(findings, checkRules(name, job)...)
+	findings = append(findings, checkDeadRules(name, job)...)
 	findings = append(findings, checkImage(name, job)...)
 	findings = append(findings, checkInherit(name, job)...)
+	findings = append(findings, checkServices(name, job)...)
+	findings = append(findings, checkRulesGlobs(name, job)...)
+	findings = append(findings, checkTimeout(name, job)...)
+	findings = append(findings, checkIDTokens(name, job)...)
+	findings = append(findings, checkSecrets(name, job)...)
+	findings = append(findings, checkPagesKeyword(name, job)...)
+	findings = append(findings, checkCacheKeyFiles(name, job)...)
 	return findings
 }
 
@@ -105,6 +122,7 @@ func checkWhen(name string, job model.Job) []Finding {
 	if job.When != "" && !validJobWhen[job.When] {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleInvalidWhen,
 			Job:      name,
 			Message:  fmt.Sprintf("'when' has invalid value %q; valid: on_success, on_failure, always, manual, delayed, never", job.When),
 		})
@@ -112,6 +130,7 @@ func checkWhen(name string, job model.Job) []Finding {
 	if job.When == "delayed" && job.StartIn == "" {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleDelayedNoStartIn,
 			Job:      name,
 			Message:  "'when: delayed' requires 'start_in' (e.g. 'start_in: 30 minutes')",
 		})
@@ -119,6 +138,7 @@ func checkWhen(name string, job model.Job) []Finding {
 	if job.When != "delayed" && job.StartIn != "" {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleStartInNoDelayed,
 			Job:      name,
 			Message:  "'start_in' is only valid when 'when: delayed'",
 		})
@@ -135,6 +155,7 @@ func checkParallel(name string, job model.Job) []Finding {
 		if v < 2 || v > 200 {
 			return []Finding{{
 				Severity: Error,
+				Rule:     RuleInvalidParallel,
 				Job:      name,
 				Message:  fmt.Sprintf("'parallel' must be between 2 and 200, got %d", v),
 			}}
@@ -143,6 +164,7 @@ func checkParallel(name string, job model.Job) []Finding {
 		if _, ok := v["matrix"]; !ok {
 			return []Finding{{
 				Severity: Error,
+				Rule:     RuleInvalidParallel,
 				Job:      name,
 				Message:  "'parallel' map form must have a 'matrix' key",
 			}}
@@ -150,6 +172,7 @@ func checkParallel(name string, job model.Job) []Finding {
 	default:
 		return []Finding{{
 			Severity: Error,
+			Rule:     RuleInvalidParallel,
 			Job:      name,
 			Message:  "'parallel' must be an integer (2–200) or a map with 'matrix'",
 		}}
@@ -166,6 +189,7 @@ func checkRetry(name string, job model.Job) []Finding {
 		if v < 0 || v > 2 {
 			return []Finding{{
 				Severity: Error,
+				Rule:     RuleInvalidRetry,
 				Job:      name,
 				Message:  fmt.Sprintf("'retry' must be 0, 1, or 2; got %d", v),
 			}}
@@ -176,6 +200,7 @@ func checkRetry(name string, job model.Job) []Finding {
 			if n, ok := maxVal.(int); ok && (n < 0 || n > 2) {
 				findings = append(findings, Finding{
 					Severity: Error,
+					Rule:     RuleInvalidRetry,
 					Job:      name,
 					Message:  fmt.Sprintf("'retry.max' must be 0, 1, or 2; got %d", n),
 				})
@@ -188,6 +213,7 @@ func checkRetry(name string, job model.Job) []Finding {
 	default:
 		return []Finding{{
 			Severity: Error,
+			Rule:     RuleInvalidRetry,
 			Job:      name,
 			Message:  "'retry' must be an integer (0–2) or a map with 'max'/'when'",
 		}}
@@ -201,6 +227,7 @@ func validateRetryWhen(name string, val any) []Finding {
 		if !validRetryWhen[s] {
 			findings = append(findings, Finding{
 				Severity: Error,
+				Rule:     RuleInvalidRetryWhen,
 				Job:      name,
 				Message:  fmt.Sprintf("'retry.when' has invalid value %q", s),
 			})
@@ -230,6 +257,7 @@ func checkAllowFailure(name string, job model.Job) []Finding {
 		if _, ok := v["exit_codes"]; !ok {
 			return []Finding{{
 				Severity: Error,
+				Rule:     RuleInvalidAllowFailure,
 				Job:      name,
 				Message:  "'allow_failure' map form must contain 'exit_codes'",
 			}}
@@ -238,6 +266,7 @@ func checkAllowFailure(name string, job model.Job) []Finding {
 		_ = v
 		return []Finding{{
 			Severity: Error,
+			Rule:     RuleInvalidAllowFailure,
 			Job:      name,
 			Message:  "'allow_failure' must be a boolean or a map with 'exit_codes'",
 		}}
@@ -252,6 +281,7 @@ func checkInterruptible(name string, job model.Job) []Finding {
 	if _, ok := job.Interruptible.(bool); !ok {
 		return []Finding{{
 			Severity: Error,
+			Rule:     RuleInvalidInterruptible,
 			Job:      name,
 			Message:  "'interruptible' must be a boolean",
 		}}
@@ -264,9 +294,10 @@ func checkTrigger(name string, job model.Job) []Finding {
 		return nil
 	}
 	var findings []Finding
-	if len(job.Script) > 0 {
+	if scriptNonEmpty(job.Script) {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleTriggerWithScript,
 			Job:      name,
 			Message:  "jobs with 'trigger' cannot use 'script'",
 		})
@@ -277,6 +308,7 @@ func checkTrigger(name string, job model.Job) []Finding {
 		if !hasProject && !hasInclude {
 			findings = append(findings, Finding{
 				Severity: Error,
+				Rule:     RuleInvalidTrigger,
 				Job:      name,
 				Message:  "'trigger' map must specify 'project' or 'include'",
 			})
@@ -294,6 +326,7 @@ func checkCoverage(name string, job model.Job) []Finding {
 	if !coveragePattern.MatchString(job.Coverage) {
 		return []Finding{{
 			Severity: Error,
+			Rule:     RuleInvalidCoverage,
 			Job:      name,
 			Message:  fmt.Sprintf("'coverage' must be a regex pattern wrapped in '/' (e.g. '/\\d+\\.?\\d*%%/'), got %q", job.Coverage),
 		}}
@@ -309,6 +342,7 @@ func checkRelease(name string, job model.Job) []Finding {
 	if !ok {
 		return []Finding{{
 			Severity: Error,
+			Rule:     RuleInvalidRelease,
 			Job:      name,
 			Message:  "'release' must be a map",
 		}}
@@ -317,6 +351,7 @@ func checkRelease(name string, job model.Job) []Finding {
 	if !exists || tagName == "" || tagName == nil {
 		return []Finding{{
 			Severity: Error,
+			Rule:     RuleInvalidRelease,
 			Job:      name,
 			Message:  "'release' requires 'tag_name'",
 		}}
@@ -334,11 +369,12 @@ func checkEnvironment(name string, job model.Job) []Finding {
 		return nil
 	}
 	var findings []Finding
-	envName, _ := m["name"]
+	envName := m["name"]
 	_, hasURL := m["url"]
 	if (envName == nil || envName == "") && hasURL {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleInvalidEnvironment,
 			Job:      name,
 			Message:  "'environment.url' requires 'environment.name' to be set",
 		})
@@ -346,6 +382,7 @@ func checkEnvironment(name string, job model.Job) []Finding {
 	if action, ok := m["action"].(string); ok && !validEnvironmentAction[action] {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleInvalidEnvironment,
 			Job:      name,
 			Message:  fmt.Sprintf("'environment.action' has invalid value %q; valid: start, stop, prepare, verify, access", action),
 		})
@@ -365,22 +402,25 @@ func checkArtifacts(name string, job model.Job) []Finding {
 	if w, ok := m["when"].(string); ok && !validArtifactsWhen[w] {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleInvalidArtifacts,
 			Job:      name,
 			Message:  fmt.Sprintf("'artifacts.when' has invalid value %q; valid: on_success, on_failure, always", w),
 		})
 	}
 	if _, hasExposeAs := m["expose_as"]; hasExposeAs {
-		paths, _ := m["paths"]
+		paths := m["paths"]
 		if paths == nil {
 			findings = append(findings, Finding{
 				Severity: Error,
+				Rule:     RuleInvalidArtifacts,
 				Job:      name,
 				Message:  "'artifacts.expose_as' requires 'artifacts.paths'",
 			})
 		}
 	}
-	// Pages job should publish to public/
-	if name == "pages" {
+	// Pages job should publish to public/. Skip when pages: keyword is set;
+	// GL039 (checkPagesKeyword) handles that case with a more precise check.
+	if name == "pages" && job.Pages == nil {
 		if paths, ok := m["paths"].([]any); ok {
 			found := false
 			for _, p := range paths {
@@ -392,6 +432,7 @@ func checkArtifacts(name string, job model.Job) []Finding {
 			if !found {
 				findings = append(findings, Finding{
 					Severity: Warning,
+					Rule:     RulePagesPublic,
 					Job:      name,
 					Message:  "the 'pages' job should include 'public' in 'artifacts.paths' for GitLab Pages to deploy",
 				})
@@ -421,6 +462,7 @@ func checkCache(name string, job model.Job) []Finding {
 		if w, ok := m["when"].(string); ok && !validCacheWhen[w] {
 			findings = append(findings, Finding{
 				Severity: Error,
+				Rule:     RuleInvalidCache,
 				Job:      name,
 				Message:  fmt.Sprintf("'cache.when' has invalid value %q; valid: on_success, on_failure, always", w),
 			})
@@ -428,6 +470,7 @@ func checkCache(name string, job model.Job) []Finding {
 		if p, ok := m["policy"].(string); ok && !validCachePolicy[p] {
 			findings = append(findings, Finding{
 				Severity: Error,
+				Rule:     RuleInvalidCache,
 				Job:      name,
 				Message:  fmt.Sprintf("'cache.policy' has invalid value %q; valid: pull, push, pull-push", p),
 			})
@@ -442,6 +485,7 @@ func checkRules(name string, job model.Job) []Finding {
 		if rule.When != "" && !validRuleWhen[rule.When] {
 			findings = append(findings, Finding{
 				Severity: Error,
+				Rule:     RuleInvalidRulesWhen,
 				Job:      name,
 				Message:  fmt.Sprintf("rules[%d].when has invalid value %q; valid: on_success, on_failure, always, manual, delayed, never", i, rule.When),
 			})
@@ -450,6 +494,28 @@ func checkRules(name string, job model.Job) []Finding {
 	return findings
 }
 
+// checkDeadRules reports when every rule in a job's rules: block has an
+// explicit when: never, making the job permanently unreachable. This is a
+// provably-correct static claim: no matter which if: condition matches, the
+// outcome is always "never"; and if no rule matches, the implicit fallback is
+// also skip. No if: evaluation is required.
+func checkDeadRules(name string, job model.Job) []Finding {
+	if len(job.Rules) == 0 {
+		return nil
+	}
+	for _, r := range job.Rules {
+		if r.When != "never" {
+			return nil
+		}
+	}
+	return []Finding{{
+		Severity: Warning,
+		Rule:     RuleDeadRules,
+		Job:      name,
+		Message:  "rules: block can never activate; every rule has 'when: never' — job is permanently excluded from the pipeline",
+	}}
+}
+
 func checkImage(name string, job model.Job) []Finding {
 	if job.Image == nil {
 		return nil
@@ -458,10 +524,11 @@ func checkImage(name string, job model.Job) []Finding {
 	if !ok {
 		return nil // String form is valid.
 	}
-	imgName, _ := m["name"]
+	imgName := m["name"]
 	if imgName == nil || imgName == "" {
 		return []Finding{{
 			Severity: Error,
+			Rule:     RuleInvalidImage,
 			Job:      name,
 			Message:  "'image' map form requires a 'name' key",
 		}}
@@ -489,6 +556,7 @@ func checkInherit(name string, job model.Job) []Finding {
 		default:
 			findings = append(findings, Finding{
 				Severity: Error,
+				Rule:     RuleInvalidInherit,
 				Job:      name,
 				Message:  fmt.Sprintf("'inherit.%s' must be a boolean or a list of names", key),
 			})
@@ -496,3 +564,289 @@ func checkInherit(name string, job model.Job) []Finding {
 	}
 	return findings
 }
+
+// GL034: services: map form requires 'name'; 'alias' must be a valid DNS label.
+func checkServices(name string, job model.Job) []Finding {
+	if len(job.Services) == 0 {
+		return nil
+	}
+	var findings []Finding
+	for i, svc := range job.Services {
+		m, ok := svc.(map[string]any)
+		if !ok {
+			continue // string form is valid
+		}
+		n := m["name"]
+		if n == nil || n == "" {
+			findings = append(findings, Finding{
+				Severity: Error,
+				Rule:     RuleInvalidService,
+				Job:      name,
+				Message:  fmt.Sprintf("services[%d]: map form requires a 'name' key", i),
+			})
+		}
+		if alias, ok := m["alias"].(string); ok && alias != "" {
+			if !dnsLabelPattern.MatchString(alias) {
+				findings = append(findings, Finding{
+					Severity: Error,
+					Rule:     RuleInvalidService,
+					Job:      name,
+					Message:  fmt.Sprintf("services[%d]: alias %q is not a valid DNS label (only letters, digits, hyphens, and dots; must start and end with alphanumeric)", i, alias),
+				})
+			}
+		}
+	}
+	return findings
+}
+
+// GL035: rules:changes and rules:exists paths must not be absolute.
+func checkRulesGlobs(name string, job model.Job) []Finding {
+	var findings []Finding
+	for i, rule := range job.Rules {
+		findings = append(findings, checkAbsolutePaths(name, fmt.Sprintf("rules[%d].changes", i), rule.Changes)...)
+		findings = append(findings, checkAbsolutePaths(name, fmt.Sprintf("rules[%d].exists", i), rule.Exists)...)
+	}
+	return findings
+}
+
+func checkAbsolutePaths(name, field string, val any) []Finding {
+	var paths []string
+	switch v := val.(type) {
+	case []any:
+		for _, item := range v {
+			if s, ok := item.(string); ok {
+				paths = append(paths, s)
+			}
+		}
+	case map[string]any:
+		if ps, ok := v["paths"].([]any); ok {
+			for _, item := range ps {
+				if s, ok := item.(string); ok {
+					paths = append(paths, s)
+				}
+			}
+		}
+	}
+	var findings []Finding
+	for _, p := range paths {
+		if strings.HasPrefix(p, "/") {
+			findings = append(findings, Finding{
+				Severity: Warning,
+				Rule:     RuleAbsoluteGlobPath,
+				Job:      name,
+				Message:  fmt.Sprintf("%s: path %q is absolute; GitLab CI paths are relative to the repository root — absolute paths will never match", field, p),
+			})
+		}
+	}
+	return findings
+}
+
+// GL036: timeout: must be a valid GitLab CI duration string.
+func checkTimeout(name string, job model.Job) []Finding {
+	if job.Timeout == "" {
+		return nil
+	}
+	if !timeoutPattern.MatchString(job.Timeout) {
+		return []Finding{{
+			Severity: Error,
+			Rule:     RuleInvalidTimeout,
+			Job:      name,
+			Message:  fmt.Sprintf("'timeout' has invalid value %q; expected a duration like '1h 30m', '90 minutes', '2 hours'", job.Timeout),
+		}}
+	}
+	return nil
+}
+
+// CheckDefaultTimeout validates the pipeline-level default: timeout: field.
+// Exported so it can be called from linter.go.
+func checkDefaultTimeout(timeout, file string) []Finding {
+	if timeout == "" {
+		return nil
+	}
+	if !timeoutPattern.MatchString(timeout) {
+		return []Finding{{
+			Severity: Error,
+			Rule:     RuleInvalidTimeout,
+			File:     file,
+			Message:  fmt.Sprintf("'default.timeout' has invalid value %q; expected a duration like '1h 30m', '90 minutes', '2 hours'", timeout),
+		}}
+	}
+	return nil
+}
+
+// GL037: id_tokens: each entry must have an 'aud' key.
+func checkIDTokens(name string, job model.Job) []Finding {
+	if job.IDTokens == nil {
+		return nil
+	}
+	m, ok := job.IDTokens.(map[string]any)
+	if !ok {
+		return nil
+	}
+	var findings []Finding
+	for tokenName, tokenVal := range m {
+		tokenMap, ok := tokenVal.(map[string]any)
+		if !ok {
+			findings = append(findings, Finding{
+				Severity: Error,
+				Rule:     RuleInvalidIDToken,
+				Job:      name,
+				Message:  fmt.Sprintf("id_tokens.%s: must be a map with an 'aud' key", tokenName),
+			})
+			continue
+		}
+		if _, hasAud := tokenMap["aud"]; !hasAud {
+			findings = append(findings, Finding{
+				Severity: Error,
+				Rule:     RuleInvalidIDToken,
+				Job:      name,
+				Message:  fmt.Sprintf("id_tokens.%s: missing required 'aud' key", tokenName),
+			})
+		}
+	}
+	return findings
+}
+
+// GL038: secrets: each entry must have a provider key (vault, gcp_secret_manager, azure_key_vault).
+func checkSecrets(name string, job model.Job) []Finding {
+	if job.Secrets == nil {
+		return nil
+	}
+	m, ok := job.Secrets.(map[string]any)
+	if !ok {
+		return nil
+	}
+	validProviders := []string{"vault", "gcp_secret_manager", "azure_key_vault"}
+	var findings []Finding
+	for secretName, secretVal := range m {
+		secretMap, ok := secretVal.(map[string]any)
+		if !ok {
+			findings = append(findings, Finding{
+				Severity: Error,
+				Rule:     RuleInvalidSecret,
+				Job:      name,
+				Message:  fmt.Sprintf("secrets.%s: must be a map with a provider key (vault, gcp_secret_manager, or azure_key_vault)", secretName),
+			})
+			continue
+		}
+		hasProvider := false
+		for _, provider := range validProviders {
+			if _, ok := secretMap[provider]; ok {
+				hasProvider = true
+				break
+			}
+		}
+		if !hasProvider {
+			findings = append(findings, Finding{
+				Severity: Error,
+				Rule:     RuleInvalidSecret,
+				Job:      name,
+				Message:  fmt.Sprintf("secrets.%s: missing provider key; must include one of: vault, gcp_secret_manager, azure_key_vault", secretName),
+			})
+		}
+	}
+	return findings
+}
+
+// GL039: a job with the pages: keyword must have the publish directory in artifacts.paths.
+func checkPagesKeyword(name string, job model.Job) []Finding {
+	if job.Pages == nil {
+		return nil
+	}
+	publishDir := "public"
+	if m, ok := job.Pages.(map[string]any); ok {
+		if p, ok := m["publish"].(string); ok && p != "" {
+			publishDir = p
+		}
+	}
+	if job.Artifacts == nil {
+		return []Finding{{
+			Severity: Warning,
+			Rule:     RulePagesPublish,
+			Job:      name,
+			Message:  fmt.Sprintf("job uses 'pages:' keyword with publish dir %q but has no 'artifacts:' block — GitLab Pages will not deploy", publishDir),
+		}}
+	}
+	m, ok := job.Artifacts.(map[string]any)
+	if !ok {
+		return nil
+	}
+	paths, ok := m["paths"].([]any)
+	if !ok || len(paths) == 0 {
+		return []Finding{{
+			Severity: Warning,
+			Rule:     RulePagesPublish,
+			Job:      name,
+			Message:  fmt.Sprintf("job uses 'pages:' keyword with publish dir %q but 'artifacts.paths' is missing — GitLab Pages will not deploy", publishDir),
+		}}
+	}
+	for _, p := range paths {
+		if s, ok := p.(string); ok && (s == publishDir || strings.HasPrefix(s, publishDir+"/")) {
+			return nil
+		}
+	}
+	return []Finding{{
+		Severity: Warning,
+		Rule:     RulePagesPublish,
+		Job:      name,
+		Message:  fmt.Sprintf("'pages.publish' is %q but 'artifacts.paths' does not include it — GitLab Pages will not deploy", publishDir),
+	}}
+}
+
+// GL041: cache.key.files must be a list of exact file paths, not glob patterns.
+func checkCacheKeyFiles(name string, job model.Job) []Finding {
+	if job.Cache == nil {
+		return nil
+	}
+	var maps []map[string]any
+	switch v := job.Cache.(type) {
+	case map[string]any:
+		maps = []map[string]any{v}
+	case []any:
+		for _, item := range v {
+			if m, ok := item.(map[string]any); ok {
+				maps = append(maps, m)
+			}
+		}
+	}
+	var findings []Finding
+	for _, m := range maps {
+		keyVal, ok := m["key"]
+		if !ok {
+			continue
+		}
+		keyMap, ok := keyVal.(map[string]any)
+		if !ok {
+			continue
+		}
+		filesVal, ok := keyMap["files"]
+		if !ok {
+			continue
+		}
+		filesList, ok := filesVal.([]any)
+		if !ok {
+			findings = append(findings, Finding{
+				Severity: Error,
+				Rule:     RuleInvalidCacheKeyFiles,
+				Job:      name,
+				Message:  "'cache.key.files' must be a list of file paths",
+			})
+			continue
+		}
+		for _, item := range filesList {
+			s, ok := item.(string)
+			if !ok {
+				continue
+			}
+			if strings.ContainsAny(s, "*?[") {
+				findings = append(findings, Finding{
+					Severity: Warning,
+					Rule:     RuleInvalidCacheKeyFiles,
+					Job:      name,
+					Message:  fmt.Sprintf("cache.key.files: %q looks like a glob pattern; 'key.files' must be exact file paths, not globs", s),
+				})
+			}
+		}
+	}
+	return findings
+}

internal/linter/linter.go

@@ -1,7 +1,9 @@
 package linter
 
 import (
+	"cmp"
 	"fmt"
+	"slices"
 	"strings"
 
 	"git.k3nny.fr/glint/internal/model"
@@ -16,25 +18,59 @@ const (
 
 type Finding struct {
 	Severity Severity
+	Rule     string // stable rule ID, e.g. "GL003" — see rules.go
 	Job      string // empty for pipeline-level findings
+	File     string // source file where the finding originates
+	Line     int    // line number in File (0 = unknown)
 	Message  string
 }
 
 func (f Finding) String() string {
-	if f.Job != "" {
-		return fmt.Sprintf("[%s] job %q: %s", f.Severity, f.Job, f.Message)
+	var loc string
+	if f.File != "" {
+		if f.Line > 0 {
+			loc = fmt.Sprintf("%s:%d: ", f.File, f.Line)
+		} else {
+			loc = fmt.Sprintf("%s: ", f.File)
+		}
 	}
-	return fmt.Sprintf("[%s] %s", f.Severity, f.Message)
+
+	rule := ""
+	if f.Rule != "" {
+		rule = f.Rule + " "
+	}
+
+	sev := "[" + strings.ToLower(string(f.Severity)) + "]"
+
+	msg := f.Message
+	if f.Job != "" {
+		msg = fmt.Sprintf("job %q: %s", f.Job, f.Message)
+	}
+
+	return fmt.Sprintf("%s%s%s %s", loc, rule, sev, msg)
 }
 
-// Lint runs all rules against p and returns findings sorted by job name.
+// Lint runs all rules against p and returns findings sorted by (File, Line, Rule).
+// Findings with no File (pipeline-level) sort before file-scoped ones.
 func Lint(p *model.Pipeline) []Finding {
 	var findings []Finding
 	findings = append(findings, checkStages(p)...)
+	findings = append(findings, checkDuplicateStages(p)...)
+	findings = append(findings, checkDefault(p)...)
 	findings = append(findings, checkWorkflow(p)...)
 	findings = append(findings, checkJobs(p)...)
 	findings = append(findings, checkNeeds(p)...)
 	findings = append(findings, checkDependencies(p)...)
+	findings = append(findings, checkVariableRefs(p)...)
+	slices.SortStableFunc(findings, func(a, b Finding) int {
+		if c := cmp.Compare(a.File, b.File); c != 0 {
+			return c
+		}
+		if c := cmp.Compare(a.Line, b.Line); c != 0 {
+			return c
+		}
+		return cmp.Compare(a.Rule, b.Rule)
+	})
 	return findings
 }
 
@@ -43,12 +79,40 @@ func checkStages(p *model.Pipeline) []Finding {
 	if len(p.Stages) == 0 {
 		findings = append(findings, Finding{
 			Severity: Warning,
+			Rule:     RuleNoStages,
+			File:     p.SourceFile,
 			Message:  "no stages defined; GitLab will use default stages (build, test, deploy)",
 		})
 	}
 	return findings
 }
 
+// GL040: warn when a stage name appears more than once in stages:.
+func checkDuplicateStages(p *model.Pipeline) []Finding {
+	seen := make(map[string]bool, len(p.Stages))
+	var findings []Finding
+	for _, s := range p.Stages {
+		if seen[s] {
+			findings = append(findings, Finding{
+				Severity: Warning,
+				Rule:     RuleDuplicateStage,
+				File:     p.SourceFile,
+				Message:  fmt.Sprintf("stage %q appears more than once in 'stages'; GitLab silently merges duplicate stage entries", s),
+			})
+		}
+		seen[s] = true
+	}
+	return findings
+}
+
+// checkDefault validates the pipeline-level default: block.
+func checkDefault(p *model.Pipeline) []Finding {
+	if p.Default == nil {
+		return nil
+	}
+	return checkDefaultTimeout(p.Default.Timeout, p.SourceFile)
+}
+
 func checkWorkflow(p *model.Pipeline) []Finding {
 	if p.Workflow == nil {
 		return nil
@@ -58,6 +122,8 @@ func checkWorkflow(p *model.Pipeline) []Finding {
 		if rule.When != "" && !validWorkflowRuleWhen[rule.When] {
 			findings = append(findings, Finding{
 				Severity: Error,
+				Rule:     RuleWorkflowWhen,
+				File:     p.SourceFile,
 				Message:  fmt.Sprintf("workflow.rules[%d].when has invalid value %q; valid: always, never", i, rule.When),
 			})
 		}
@@ -88,10 +154,17 @@ func checkJob(name string, job model.Job, stageSet map[string]bool) []Finding {
 
 	// After extends resolution, a job with no script/run is an error.
 	// Exceptions: trigger jobs, pages jobs (use pages: keyword), and template jobs.
-	hasScript := len(job.Script) > 0 || job.Run != nil
+	// When the job has extends:, the script may come from a base that couldn't be
+	// fetched (e.g. a remote include without a token), so downgrade to warning.
+	hasScript := scriptNonEmpty(job.Script) || job.Run != nil
 	if !isTemplate && !isTrigger && job.Pages == nil && !hasScript {
+		sev := Error
+		if job.Extends != nil {
+			sev = Warning
+		}
 		findings = append(findings, Finding{
-			Severity: Error,
+			Severity: sev,
+			Rule:     RuleMissingScript,
 			Job:      name,
 			Message:  "missing required field 'script' (or 'run')",
 		})
@@ -103,6 +176,7 @@ func checkJob(name string, job model.Job, stageSet map[string]bool) []Finding {
 	if job.Stage != "" && !strings.Contains(job.Stage, "$[[") && len(stageSet) > 0 && !stageSet[job.Stage] {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleUnknownStage,
 			Job:      name,
 			Message:  fmt.Sprintf("stage %q is not defined in 'stages'", job.Stage),
 		})
@@ -112,6 +186,7 @@ func checkJob(name string, job model.Job, stageSet map[string]bool) []Finding {
 	if job.Only != nil && len(job.Rules) > 0 {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleOnlyRulesConflict,
 			Job:      name,
 			Message:  "'only' and 'rules' cannot be used together",
 		})
@@ -121,6 +196,7 @@ func checkJob(name string, job model.Job, stageSet map[string]bool) []Finding {
 	if job.Except != nil && len(job.Rules) > 0 {
 		findings = append(findings, Finding{
 			Severity: Error,
+			Rule:     RuleExceptRulesConflict,
 			Job:      name,
 			Message:  "'except' and 'rules' cannot be used together",
 		})
@@ -130,6 +206,7 @@ func checkJob(name string, job model.Job, stageSet map[string]bool) []Finding {
 	if job.Only != nil || job.Except != nil {
 		findings = append(findings, Finding{
 			Severity: Warning,
+			Rule:     RuleDeprecatedOnly,
 			Job:      name,
 			Message:  "'only'/'except' are deprecated; prefer 'rules'",
 		})
@@ -137,5 +214,24 @@ func checkJob(name string, job model.Job, stageSet map[string]bool) []Finding {
 
 	findings = append(findings, checkJobKeywords(name, job)...)
 
+	// Attach source location to every job-scoped finding collected above.
+	for i := range findings {
+		if findings[i].Job != "" && findings[i].File == "" {
+			findings[i].File = job.File
+			findings[i].Line = job.Line
+		}
+	}
 	return findings
 }
+
+// scriptNonEmpty reports whether a script/before_script/after_script field
+// (which may be a []any list or a plain string) is non-empty.
+func scriptNonEmpty(v any) bool {
+	switch s := v.(type) {
+	case []any:
+		return len(s) > 0
+	case string:
+		return s != ""
+	}
+	return false
+}

internal/linter/needs.go

@@ -6,6 +6,12 @@ import (
 	"git.k3nny.fr/glint/internal/model"
 )
 
+// needEntry is a parsed element from a job's needs: list.
+type needEntry struct {
+	job      string
+	optional bool // true when the needs entry carries optional: true
+}
+
 func checkNeeds(p *model.Pipeline) []Finding {
 	var findings []Finding
 
@@ -15,7 +21,7 @@ func checkNeeds(p *model.Pipeline) []Finding {
 		stageIndex[s] = i
 	}
 
-	// needsGraph maps each job to the list of jobs it depends on.
+	// needsGraph maps each job to the jobs it depends on (existing jobs only).
 	// Used for cycle detection after individual checks.
 	needsGraph := make(map[string][]string)
 
@@ -24,32 +30,47 @@ func checkNeeds(p *model.Pipeline) []Finding {
 			continue
 		}
 
-		neededNames := parseNeedJobNames(job.Needs)
-		needsGraph[name] = neededNames
-
+		entries := parseNeedEntries(job.Needs)
 		jobStageIdx, jobHasStage := stageIndex[job.Stage]
 
-		for _, needed := range neededNames {
-			neededJob, exists := p.Jobs[needed]
+		for _, entry := range entries {
+			neededJob, exists := p.Jobs[entry.job]
 			if !exists {
+				// optional: true means GitLab CI will silently skip the
+				// dependency when the job is absent (e.g. from a conditional
+				// include). Downgrade to warning so users are informed without
+				// failing the lint.
+				sev := Error
+				if entry.optional {
+					sev = Warning
+				}
 				findings = append(findings, Finding{
-					Severity: Error,
+					Severity: sev,
+					Rule:     RuleNeedsUnknown,
 					Job:      name,
-					Message:  fmt.Sprintf("needs unknown job %q", needed),
+					File:     job.File,
+					Line:     job.Line,
+					Message:  fmt.Sprintf("needs unknown job %q", entry.job),
 				})
 				continue
 			}
 
+			// Add to the cycle-detection graph only when the dep exists.
+			needsGraph[name] = append(needsGraph[name], entry.job)
+
 			// A job cannot need a job in a later stage.
 			if len(p.Stages) > 0 && jobHasStage && neededJob.Stage != "" {
 				neededStageIdx, neededHasStage := stageIndex[neededJob.Stage]
 				if neededHasStage && neededStageIdx > jobStageIdx {
 					findings = append(findings, Finding{
 						Severity: Error,
+						Rule:     RuleNeedsStageOrder,
 						Job:      name,
+						File:     job.File,
+						Line:     job.Line,
 						Message: fmt.Sprintf(
 							"needs %q which is in a later stage (%q after %q)",
-							needed, neededJob.Stage, job.Stage,
+							entry.job, neededJob.Stage, job.Stage,
 						),
 					})
 				}
@@ -57,32 +78,33 @@ func checkNeeds(p *model.Pipeline) []Finding {
 		}
 	}
 
-	findings = append(findings, detectNeedsCycles(needsGraph)...)
+	findings = append(findings, detectNeedsCycles(needsGraph, p.Jobs)...)
 	return findings
 }
 
-// parseNeedJobNames extracts job names from a needs: list.
-// Each element is either a plain string or a map with a "job" key.
-// Cross-pipeline needs (maps with a "pipeline" key) are skipped.
-func parseNeedJobNames(needs []any) []string {
-	var names []string
+// parseNeedEntries extracts needs entries from a needs: list, preserving the
+// optional flag. Each element is a plain string (job name) or a map with a
+// "job" key. Cross-pipeline needs (maps with a "pipeline" key) are skipped.
+func parseNeedEntries(needs []any) []needEntry {
+	var entries []needEntry
 	for _, n := range needs {
 		switch v := n.(type) {
 		case string:
-			names = append(names, v)
+			entries = append(entries, needEntry{job: v})
 		case map[string]any:
 			if _, crossPipeline := v["pipeline"]; crossPipeline {
 				continue
 			}
 			if job, ok := v["job"].(string); ok {
-				names = append(names, job)
+				optional, _ := v["optional"].(bool)
+				entries = append(entries, needEntry{job: job, optional: optional})
 			}
 		}
 	}
-	return names
+	return entries
 }
 
-func detectNeedsCycles(graph map[string][]string) []Finding {
+func detectNeedsCycles(graph map[string][]string, jobs map[string]model.Job) []Finding {
 	const (
 		unvisited = 0
 		visiting  = 1
@@ -101,9 +123,13 @@ func detectNeedsCycles(graph map[string][]string) []Finding {
 		case visiting:
 			if !reported[name] {
 				reported[name] = true
+				j := jobs[name]
 				findings = append(findings, Finding{
 					Severity: Error,
+					Rule:     RuleNeedsCycle,
 					Job:      name,
+					File:     j.File,
+					Line:     j.Line,
 					Message:  fmt.Sprintf("circular dependency in needs: %v → %s", path, name),
 				})
 			}

internal/linter/rules.go

@@ -0,0 +1,146 @@
+package linter
+
+// Rule ID constants. Each ID is stable across versions and uniquely identifies
+// one lint check. Use these when filtering output, writing suppression rules,
+// or referencing a check in documentation.
+//
+// Prefix GL = Glint / GitLab CI lint.
+// Numbering is sequential by category; gaps may appear as rules are added.
+const (
+	// ── Pipeline-level ──────────────────────────────────────────────────────
+
+	// GL001: no stages: block defined; GitLab falls back to default stages.
+	RuleNoStages = "GL001"
+
+	// GL002: workflow.rules[n].when has an invalid value (only always/never allowed).
+	RuleWorkflowWhen = "GL002"
+
+	// ── Job structure ────────────────────────────────────────────────────────
+
+	// GL003: job is missing a required script: (or run:) field.
+	RuleMissingScript = "GL003"
+
+	// GL004: job references a stage not declared in stages:.
+	RuleUnknownStage = "GL004"
+
+	// GL005: only: and rules: used together on the same job.
+	RuleOnlyRulesConflict = "GL005"
+
+	// GL006: except: and rules: used together on the same job.
+	RuleExceptRulesConflict = "GL006"
+
+	// GL007: only:/except: used (deprecated; prefer rules:).
+	RuleDeprecatedOnly = "GL007"
+
+	// ── Keyword constraints ──────────────────────────────────────────────────
+
+	// GL008: when: has an invalid value.
+	RuleInvalidWhen = "GL008"
+
+	// GL009: when: delayed without start_in:.
+	RuleDelayedNoStartIn = "GL009"
+
+	// GL010: start_in: set when when: is not delayed.
+	RuleStartInNoDelayed = "GL010"
+
+	// GL011: parallel: value is invalid (integer out of range or map missing matrix:).
+	RuleInvalidParallel = "GL011"
+
+	// GL012: retry: integer is out of range 0–2, or retry: is neither int nor map.
+	RuleInvalidRetry = "GL012"
+
+	// GL013: retry.when: contains an unrecognised failure type.
+	RuleInvalidRetryWhen = "GL013"
+
+	// GL014: allow_failure: is not a boolean or a map with exit_codes:.
+	RuleInvalidAllowFailure = "GL014"
+
+	// GL015: interruptible: is not a boolean.
+	RuleInvalidInterruptible = "GL015"
+
+	// GL016: trigger: job also defines script: (mutually exclusive).
+	RuleTriggerWithScript = "GL016"
+
+	// GL017: trigger: map does not specify project: or include:.
+	RuleInvalidTrigger = "GL017"
+
+	// GL018: coverage: is not a regex pattern wrapped in /.
+	RuleInvalidCoverage = "GL018"
+
+	// GL019: release: is missing required tag_name:, or is not a map.
+	RuleInvalidRelease = "GL019"
+
+	// GL020: environment: has an invalid url/action configuration.
+	RuleInvalidEnvironment = "GL020"
+
+	// GL021: artifacts: has an invalid when/expose_as configuration.
+	RuleInvalidArtifacts = "GL021"
+
+	// GL022: pages job artifacts.paths does not include public/.
+	RulePagesPublic = "GL022"
+
+	// GL023: cache: has an invalid when/policy value.
+	RuleInvalidCache = "GL023"
+
+	// GL024: rules[n].when has an invalid value.
+	RuleInvalidRulesWhen = "GL024"
+
+	// GL025: image: map form is missing a name: key.
+	RuleInvalidImage = "GL025"
+
+	// GL026: inherit.default or inherit.variables is not a boolean or list.
+	RuleInvalidInherit = "GL026"
+
+	// ── Cross-job graph ──────────────────────────────────────────────────────
+
+	// GL027: needs: references a job that does not exist in the pipeline.
+	RuleNeedsUnknown = "GL027"
+
+	// GL028: needs: references a job in a later stage than the current job.
+	RuleNeedsStageOrder = "GL028"
+
+	// GL029: circular dependency detected in the needs: graph.
+	RuleNeedsCycle = "GL029"
+
+	// GL030: dependencies: references a job that does not exist.
+	RuleUnknownDependency = "GL030"
+
+	// GL031: dependencies: references a job in the same or a later stage.
+	RuleDependencyStage = "GL031"
+
+	// ── Expression validation ────────────────────────────────────────────────
+
+	// GL032: rules:if: references a variable not declared in pipeline variables:,
+	// the job's own variables:, or any workflow:rules:variables: block.
+	// May be a false positive for variables set in GitLab CI/CD project settings.
+	RuleUndeclaredVariable = "GL032"
+
+	// GL033: every rule in a job's rules: block has when: never, so the job
+	// can never be included in any pipeline run.
+	RuleDeadRules = "GL033"
+
+	// GL034: services: map form is missing 'name', or 'alias' is not a valid DNS label.
+	RuleInvalidService = "GL034"
+
+	// GL035: rules:changes or rules:exists contains an absolute path (starts with /);
+	// GitLab CI paths are relative to the repository root and absolute paths never match.
+	RuleAbsoluteGlobPath = "GL035"
+
+	// GL036: timeout: is not a valid GitLab CI duration string (e.g. '1h 30m', '90 minutes').
+	RuleInvalidTimeout = "GL036"
+
+	// GL037: id_tokens: entry is missing the required 'aud' key.
+	RuleInvalidIDToken = "GL037"
+
+	// GL038: secrets: entry is missing a provider key (vault, gcp_secret_manager, or azure_key_vault).
+	RuleInvalidSecret = "GL038"
+
+	// GL039: a job has the pages: keyword but artifacts.paths does not include the publish directory.
+	RulePagesPublish = "GL039"
+
+	// GL040: a stage name appears more than once in stages:; GitLab silently merges duplicates.
+	RuleDuplicateStage = "GL040"
+
+	// GL041: cache.key.files contains a glob pattern; it must be a list of exact file paths.
+	RuleInvalidCacheKeyFiles = "GL041"
+)

internal/linter/samba_test.go

@@ -0,0 +1,89 @@
+package linter_test
+
+import (
+	"path/filepath"
+	"testing"
+
+	"git.k3nny.fr/glint/internal/fetcher"
+	"git.k3nny.fr/glint/internal/linter"
+	"git.k3nny.fr/glint/internal/model"
+	"git.k3nny.fr/glint/internal/resolver"
+)
+
+// TestSambaCI verifies that the Samba project's .gitlab-ci.yml (a real-world
+// pipeline that is valid on GitLab) produces no Error findings.
+// These files exercise local include resolution and multi-level extends chains.
+func TestSambaCI(t *testing.T) {
+	entryPoint := "../../testdata/samba/.gitlab-ci.yml"
+
+	p, err := model.Parse(entryPoint)
+	if err != nil {
+		t.Fatalf("Parse: %v", err)
+	}
+
+	rootDir := filepath.Dir(filepath.Clean(entryPoint))
+	incWarnings, _ := resolver.ResolveIncludes(p, fetcher.GitLabConfig{}, rootDir)
+	for _, w := range incWarnings {
+		t.Logf("include warning: %s", w)
+	}
+
+	extWarnings, err := resolver.Resolve(p)
+	if err != nil {
+		t.Fatalf("Resolve: %v", err)
+	}
+	for _, w := range extWarnings {
+		t.Logf("extends warning: job %q extends unknown %q", w.Job, w.Base)
+	}
+
+	findings := linter.Lint(p)
+
+	for _, f := range findings {
+		if f.Severity == linter.Error {
+			t.Errorf("unexpected error finding on valid Samba CI: %s", f)
+		}
+	}
+}
+
+// TestSambaCIEntryFiles verifies all of the Samba entry-point files
+// (files that can each act as the top-level CI file) lint without errors.
+func TestSambaCIEntryFiles(t *testing.T) {
+	entryPoints := []struct {
+		name string
+		path string
+	}{
+		{"default", "../../testdata/samba/.gitlab-ci.yml"},
+		{"coverage", "../../testdata/samba/.gitlab-ci-coverage.yml"},
+		{"private", "../../testdata/samba/.gitlab-ci-private.yml"},
+	}
+
+	for _, tc := range entryPoints {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			p, err := model.Parse(tc.path)
+			if err != nil {
+				t.Fatalf("Parse: %v", err)
+			}
+
+			rootDir := filepath.Dir(filepath.Clean(tc.path))
+			incWarnings, _ := resolver.ResolveIncludes(p, fetcher.GitLabConfig{}, rootDir)
+			for _, w := range incWarnings {
+				t.Logf("include warning: %s", w)
+			}
+
+			extWarnings, err := resolver.Resolve(p)
+			if err != nil {
+				t.Fatalf("Resolve: %v", err)
+			}
+			for _, w := range extWarnings {
+				t.Logf("extends warning: job %q extends unknown %q", w.Job, w.Base)
+			}
+
+			findings := linter.Lint(p)
+			for _, f := range findings {
+				if f.Severity == linter.Error {
+					t.Errorf("unexpected error finding: %s", f)
+				}
+			}
+		})
+	}
+}

internal/linter/variables.go

@@ -0,0 +1,158 @@
+package linter
+
+import (
+	"fmt"
+	"strings"
+
+	"git.k3nny.fr/glint/internal/model"
+)
+
+// predefinedVarPrefixes lists GitLab-maintained variable namespaces that are
+// always available without an explicit declaration in variables: blocks.
+var predefinedVarPrefixes = []string{
+	"CI_",      // most predefined CI variables (CI_COMMIT_BRANCH, CI_JOB_ID, …)
+	"GITLAB_",  // user/project metadata (GITLAB_USER_ID, GITLAB_FEATURES, …)
+	"FF_",      // GitLab feature flags
+	"RUNNER_",  // runner-level variables
+	"TRIGGER_", // trigger token variables passed from upstream pipelines
+	"CHAT_",    // ChatOps variables
+}
+
+func isPredefinedVar(name string) bool {
+	for _, prefix := range predefinedVarPrefixes {
+		if strings.HasPrefix(name, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+// extractIfVars returns every variable name referenced in a rules:if: expression.
+// String literals are skipped so that dollar signs inside quoted values are
+// not mistaken for variable references.
+func extractIfVars(expr string) []string {
+	var names []string
+	i := 0
+	for i < len(expr) {
+		switch expr[i] {
+		case '"', '\'':
+			quote := expr[i]
+			i++
+			for i < len(expr) && expr[i] != quote {
+				if expr[i] == '\\' {
+					i++ // skip escaped character
+				}
+				i++
+			}
+			if i < len(expr) {
+				i++ // consume closing quote
+			}
+		case '$':
+			i++ // consume '$'
+			if i < len(expr) && expr[i] == '{' {
+				i++ // consume '{'
+				start := i
+				for i < len(expr) && isVarNameByte(expr[i]) {
+					i++
+				}
+				if i < len(expr) && expr[i] == '}' && i > start {
+					names = append(names, expr[start:i])
+					i++ // consume '}'
+				}
+			} else {
+				start := i
+				for i < len(expr) && isVarNameByte(expr[i]) {
+					i++
+				}
+				if i > start {
+					names = append(names, expr[start:i])
+				}
+			}
+		default:
+			i++
+		}
+	}
+	return names
+}
+
+func isVarNameByte(b byte) bool {
+	return (b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z') || (b >= '0' && b <= '9') || b == '_'
+}
+
+// checkVariableRefs warns when a rules:if: expression references a variable that
+// is not declared in pipeline variables:, the job's own variables:, or any
+// workflow:rules:variables: block. Predefined GitLab CI variables (CI_*, GITLAB_*,
+// …) are always exempt. Variables set in GitLab CI/CD project settings are
+// invisible to glint, so the finding is a WARNING rather than an error.
+func checkVariableRefs(p *model.Pipeline) []Finding {
+	pipelineVars := make(map[string]bool, len(p.Variables))
+	for k := range p.Variables {
+		pipelineVars[k] = true
+	}
+
+	// Union of all variables any workflow rule might inject into the context.
+	workflowRuleVars := make(map[string]bool)
+	if p.Workflow != nil {
+		for _, rule := range p.Workflow.Rules {
+			for k := range rule.Variables {
+				workflowRuleVars[k] = true
+			}
+		}
+	}
+
+	var findings []Finding
+
+	// Check workflow rules:if: expressions.
+	if p.Workflow != nil {
+		seen := make(map[string]bool)
+		for i, rule := range p.Workflow.Rules {
+			if rule.If == "" {
+				continue
+			}
+			for _, varName := range extractIfVars(rule.If) {
+				if isPredefinedVar(varName) || pipelineVars[varName] || seen[varName] {
+					continue
+				}
+				seen[varName] = true
+				findings = append(findings, Finding{
+					Severity: Warning,
+					Rule:     RuleUndeclaredVariable,
+					File:     p.SourceFile,
+					Message:  fmt.Sprintf("workflow.rules[%d].if: $%s is not declared in pipeline variables:", i, varName),
+				})
+			}
+		}
+	}
+
+	// Check each job's rules:if: expressions.
+	for name, job := range p.Jobs {
+		jobVars := make(map[string]bool, len(job.Variables))
+		for k := range job.Variables {
+			jobVars[k] = true
+		}
+
+		// Deduplicate per (job, varName): report each undeclared variable once per job.
+		seen := make(map[string]bool)
+		for i, rule := range job.Rules {
+			if rule.If == "" {
+				continue
+			}
+			for _, varName := range extractIfVars(rule.If) {
+				if isPredefinedVar(varName) || pipelineVars[varName] || jobVars[varName] || workflowRuleVars[varName] || seen[varName] {
+					continue
+				}
+				seen[varName] = true
+				findings = append(findings, Finding{
+					Severity: Warning,
+					Rule:     RuleUndeclaredVariable,
+					Job:      name,
+					File:     job.File,
+					Line:     job.Line,
+					Message:  fmt.Sprintf("rules[%d].if: $%s is not declared in pipeline or job variables:", i, varName),
+				})
+			}
+		}
+	}
+
+	return findings
+}

internal/linter/variables_test.go

@@ -0,0 +1,214 @@
+package linter
+
+import (
+	"testing"
+
+	"git.k3nny.fr/glint/internal/model"
+)
+
+func TestExtractIfVars(t *testing.T) {
+	cases := []struct {
+		name string
+		expr string
+		want []string
+	}{
+		{
+			name: "simple variable",
+			expr: `$MY_VAR == "value"`,
+			want: []string{"MY_VAR"},
+		},
+		{
+			name: "curly brace syntax",
+			expr: `${MY_VAR} != null`,
+			want: []string{"MY_VAR"},
+		},
+		{
+			name: "multiple variables",
+			expr: `$BRANCH == "main" && $DEPLOY_ENV == "prod"`,
+			want: []string{"BRANCH", "DEPLOY_ENV"},
+		},
+		{
+			name: "dollar sign inside string literal is skipped",
+			expr: `$REAL_VAR == "$not_a_var"`,
+			want: []string{"REAL_VAR"},
+		},
+		{
+			name: "no variables",
+			expr: `"main" == "main"`,
+			want: nil,
+		},
+		{
+			name: "regex rhs variable",
+			expr: `$BRANCH =~ $PATTERN`,
+			want: []string{"BRANCH", "PATTERN"},
+		},
+		{
+			name: "multiline expression",
+			expr: "$BRANCH == \"main\" ||\n$BRANCH == \"develop\"",
+			want: []string{"BRANCH", "BRANCH"},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := extractIfVars(tc.expr)
+			if len(got) != len(tc.want) {
+				t.Fatalf("extractIfVars(%q) = %v, want %v", tc.expr, got, tc.want)
+			}
+			for i, v := range got {
+				if v != tc.want[i] {
+					t.Errorf("[%d] got %q, want %q", i, v, tc.want[i])
+				}
+			}
+		})
+	}
+}
+
+func TestIsPredefinedVar(t *testing.T) {
+	cases := []struct {
+		input string
+		want  bool
+	}{
+		{"CI_COMMIT_BRANCH", true},
+		{"CI_JOB_TOKEN", true},
+		{"GITLAB_USER_ID", true},
+		{"GITLAB_FEATURES", true},
+		{"FF_SOME_FLAG", true},
+		{"RUNNER_ID", true},
+		{"TRIGGER_PAYLOAD", true},
+		{"CHAT_INPUT", true},
+		{"MY_CUSTOM_VAR", false},
+		{"DEPLOY_ENV", false},
+		{"FEATURE_ENABLED", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.input, func(t *testing.T) {
+			if got := isPredefinedVar(tc.input); got != tc.want {
+				t.Errorf("isPredefinedVar(%q) = %v, want %v", tc.input, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestCheckVariableRefs(t *testing.T) {
+	cases := []struct {
+		name         string
+		pipeline     *model.Pipeline
+		wantWarnings int
+	}{
+		{
+			name: "declared pipeline variable — no warning",
+			pipeline: &model.Pipeline{
+				Variables: map[string]any{"MY_VAR": "value"},
+				Jobs: map[string]model.Job{
+					"job-a": {Rules: []model.Rule{{If: `$MY_VAR == "value"`}}},
+				},
+			},
+			wantWarnings: 0,
+		},
+		{
+			name: "predefined CI variable — no warning",
+			pipeline: &model.Pipeline{
+				Jobs: map[string]model.Job{
+					"job-a": {Rules: []model.Rule{{If: `$CI_COMMIT_BRANCH == "main"`}}},
+				},
+			},
+			wantWarnings: 0,
+		},
+		{
+			name: "undeclared variable — one warning",
+			pipeline: &model.Pipeline{
+				Jobs: map[string]model.Job{
+					"job-a": {Rules: []model.Rule{{If: `$UNDEFINED_VAR == "yes"`}}},
+				},
+			},
+			wantWarnings: 1,
+		},
+		{
+			name: "same undeclared var in multiple rules — one warning per job",
+			pipeline: &model.Pipeline{
+				Jobs: map[string]model.Job{
+					"job-a": {
+						Rules: []model.Rule{
+							{If: `$UNDEFINED_VAR == "yes"`},
+							{If: `$UNDEFINED_VAR == "no"`},
+						},
+					},
+				},
+			},
+			wantWarnings: 1,
+		},
+		{
+			name: "job-level variable — no warning",
+			pipeline: &model.Pipeline{
+				Jobs: map[string]model.Job{
+					"job-a": {
+						Variables: map[string]any{"LOCAL_VAR": "value"},
+						Rules:     []model.Rule{{If: `$LOCAL_VAR == "value"`}},
+					},
+				},
+			},
+			wantWarnings: 0,
+		},
+		{
+			name: "workflow rule variable available to job rules — no warning",
+			pipeline: &model.Pipeline{
+				Workflow: &model.Workflow{
+					Rules: []model.Rule{
+						{
+							If:        `$CI_COMMIT_BRANCH == "main"`,
+							Variables: map[string]any{"DEPLOY_ENV": "production"},
+						},
+					},
+				},
+				Jobs: map[string]model.Job{
+					"job-a": {Rules: []model.Rule{{If: `$DEPLOY_ENV == "production"`}}},
+				},
+			},
+			wantWarnings: 0,
+		},
+		{
+			name: "undeclared variable in workflow rules:if",
+			pipeline: &model.Pipeline{
+				Workflow: &model.Workflow{
+					Rules: []model.Rule{{If: `$UNDECLARED == "main"`}},
+				},
+				Jobs: map[string]model.Job{},
+			},
+			wantWarnings: 1,
+		},
+		{
+			name: "two jobs each with a different undeclared variable — two warnings",
+			pipeline: &model.Pipeline{
+				Jobs: map[string]model.Job{
+					"job-a": {Rules: []model.Rule{{If: `$UNDEF_A == "x"`}}},
+					"job-b": {Rules: []model.Rule{{If: `$UNDEF_B == "y"`}}},
+				},
+			},
+			wantWarnings: 2,
+		},
+		{
+			name: "no rules — no warnings",
+			pipeline: &model.Pipeline{
+				Jobs: map[string]model.Job{
+					"job-a": {Script: "echo ok"},
+				},
+			},
+			wantWarnings: 0,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			findings := checkVariableRefs(tc.pipeline)
+			count := 0
+			for _, f := range findings {
+				if f.Severity == Warning && f.Rule == RuleUndeclaredVariable {
+					count++
+				}
+			}
+			if count != tc.wantWarnings {
+				t.Errorf("got %d GL032 warnings, want %d; findings: %v", count, tc.wantWarnings, findings)
+			}
+		})
+	}
+}

internal/model/parser.go

@@ -3,6 +3,7 @@ package model
 import (
 	"fmt"
 	"os"
+	"strings"
 
 	"gopkg.in/yaml.v3"
 )
@@ -13,14 +14,24 @@ func Parse(path string) (*Pipeline, error) {
 	if err != nil {
 		return nil, fmt.Errorf("reading file: %w", err)
 	}
-	return ParseBytes(data)
+	p, err := ParseBytes(data)
+	if err != nil {
+		return nil, err
+	}
+	p.SourceFile = path
+	p.SetJobOrigin(path)
+	return p, nil
 }
 
 // ParseBytes parses YAML from an in-memory byte slice.
 func ParseBytes(data []byte) (*Pipeline, error) {
-	// First pass: decode into a raw map to extract job keys.
-	var raw map[string]yaml.Node
-	if err := yaml.Unmarshal(data, &raw); err != nil {
+	data = sanitizeYAMLEscapes(data)
+
+	// First pass: parse into a yaml.Node document to extract job keys with
+	// their exact source line numbers (key nodes carry the line, value nodes
+	// carry the body we decode into Job / map[string]any).
+	var doc yaml.Node
+	if err := yaml.Unmarshal(data, &doc); err != nil {
 		return nil, fmt.Errorf("parsing YAML: %w", err)
 	}
 
@@ -32,23 +43,139 @@ func ParseBytes(data []byte) (*Pipeline, error) {
 
 	p.Jobs = make(map[string]Job)
 	p.RawJobs = make(map[string]map[string]any)
-	for key, node := range raw {
+
+	if doc.Kind != yaml.DocumentNode || len(doc.Content) == 0 {
+		return p, nil
+	}
+	root := doc.Content[0]
+	if root.Kind != yaml.MappingNode {
+		return p, nil
+	}
+
+	// Walk root mapping in key/value pairs.
+	for i := 0; i+1 < len(root.Content); i += 2 {
+		keyNode := root.Content[i]
+		valNode := root.Content[i+1]
+		key := keyNode.Value
 		if ReservedKeys[key] {
 			continue
 		}
+
+		// Extract any inline suppression directive from the job's head or line comment.
+		if rules := parseSuppressComment(keyNode.HeadComment, keyNode.LineComment); len(rules) > 0 {
+			if p.Suppressions == nil {
+				p.Suppressions = map[string][]string{}
+			}
+			p.Suppressions[key] = rules
+		}
+
 		var rawMap map[string]any
-		if err := node.Decode(&rawMap); err != nil {
+		if err := valNode.Decode(&rawMap); err != nil {
 			return nil, fmt.Errorf("parsing raw job %q: %w", key, err)
 		}
 		p.RawJobs[key] = rawMap
 
 		var j Job
-		if err := node.Decode(&j); err != nil {
+		if err := valNode.Decode(&j); err != nil {
 			return nil, fmt.Errorf("parsing job %q: %w", key, err)
 		}
 		j.Name = key
+		j.Line = keyNode.Line // exact line of the job name key
 		p.Jobs[key] = j
 	}
 
 	return p, nil
 }
+
+// parseSuppressComment scans head/line comments from a YAML key node for a
+// "# glint: ignore RULE [RULE ...]" directive. Returns the list of rule IDs
+// to suppress (uppercased), or []string{"*"} for "# glint: ignore all".
+// Returns nil when no directive is found.
+func parseSuppressComment(headComment, lineComment string) []string {
+	for _, raw := range []string{headComment, lineComment} {
+		for _, line := range strings.Split(raw, "\n") {
+			line = strings.TrimLeft(line, "# \t")
+			if !strings.HasPrefix(line, "glint:") {
+				continue
+			}
+			rest := strings.TrimSpace(strings.TrimPrefix(line, "glint:"))
+			if !strings.HasPrefix(rest, "ignore") {
+				continue
+			}
+			rest = strings.TrimSpace(strings.TrimPrefix(rest, "ignore"))
+			if rest == "" || strings.EqualFold(rest, "all") {
+				return []string{"*"}
+			}
+			var rules []string
+			for _, part := range strings.FieldsFunc(rest, func(r rune) bool {
+				return r == ',' || r == ' ' || r == '\t'
+			}) {
+				if p := strings.TrimSpace(part); p != "" {
+					rules = append(rules, strings.ToUpper(p))
+				}
+			}
+			return rules
+		}
+	}
+	return nil
+}
+
+// sanitizeYAMLEscapes rewrites double-quoted YAML strings, replacing the \/
+// escape sequence (unrecognised by gopkg.in/yaml.v3) with \\/ so that the
+// parser produces a literal backslash+slash — preserving regex patterns like
+// /^us\// that appear in GitLab CI if: expressions.
+func sanitizeYAMLEscapes(data []byte) []byte {
+	type state int
+	const (
+		stOutside state = iota
+		stSingleQ
+		stDoubleQ
+		stEscape
+	)
+
+	out := make([]byte, 0, len(data))
+	s := stOutside
+
+	for i := 0; i < len(data); i++ {
+		b := data[i]
+		switch s {
+		case stOutside:
+			out = append(out, b)
+			switch b {
+			case '"':
+				s = stDoubleQ
+			case '\'':
+				s = stSingleQ
+			}
+		case stSingleQ:
+			out = append(out, b)
+			if b == '\'' {
+				if i+1 < len(data) && data[i+1] == '\'' {
+					// '' inside a single-quoted string is an escaped single-quote
+					out = append(out, data[i+1])
+					i++
+				} else {
+					s = stOutside
+				}
+			}
+		case stDoubleQ:
+			out = append(out, b)
+			switch b {
+			case '\\':
+				s = stEscape
+			case '"':
+				s = stOutside
+			}
+		case stEscape:
+			if b == '/' {
+				// \/ is not recognised by yaml.v3; rewrite as \\/ which
+				// the parser resolves to a literal backslash + slash.
+				out = append(out, '\\', '/')
+			} else {
+				out = append(out, b)
+			}
+			s = stDoubleQ
+		}
+	}
+	return out
+}

internal/model/parser_suppress_test.go

@@ -0,0 +1,125 @@
+package model
+
+import "testing"
+
+func TestParseSuppressComment(t *testing.T) {
+	cases := []struct {
+		name        string
+		head        string
+		line        string
+		wantRules   []string
+		wantNil     bool
+	}{
+		{
+			name:    "no comment",
+			head:    "",
+			line:    "",
+			wantNil: true,
+		},
+		{
+			name:      "single rule head comment",
+			head:      "# glint: ignore GL007",
+			wantRules: []string{"GL007"},
+		},
+		{
+			name:      "multiple rules comma-separated",
+			head:      "# glint: ignore GL007, GL032",
+			wantRules: []string{"GL007", "GL032"},
+		},
+		{
+			name:      "multiple rules space-separated",
+			head:      "# glint: ignore GL007 GL032",
+			wantRules: []string{"GL007", "GL032"},
+		},
+		{
+			name:      "ignore all",
+			head:      "# glint: ignore all",
+			wantRules: []string{"*"},
+		},
+		{
+			name:      "ignore all bare",
+			head:      "# glint: ignore",
+			wantRules: []string{"*"},
+		},
+		{
+			name:      "lowercase rule ID is uppercased",
+			head:      "# glint: ignore gl007",
+			wantRules: []string{"GL007"},
+		},
+		{
+			name:      "line comment",
+			head:      "",
+			line:      "# glint: ignore GL004",
+			wantRules: []string{"GL004"},
+		},
+		{
+			name:    "unrelated comment",
+			head:    "# This job deploys to production",
+			wantNil: true,
+		},
+		{
+			name:    "partial match - not a glint directive",
+			head:    "# hint: ignore this",
+			wantNil: true,
+		},
+		{
+			name:      "multi-line head comment with directive on second line",
+			head:      "# Some description\n# glint: ignore GL007",
+			wantRules: []string{"GL007"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := parseSuppressComment(tc.head, tc.line)
+			if tc.wantNil {
+				if got != nil {
+					t.Errorf("expected nil, got %v", got)
+				}
+				return
+			}
+			if len(got) != len(tc.wantRules) {
+				t.Fatalf("got %v, want %v", got, tc.wantRules)
+			}
+			for i, r := range tc.wantRules {
+				if got[i] != r {
+					t.Errorf("[%d] got %q, want %q", i, got[i], r)
+				}
+			}
+		})
+	}
+}
+
+func TestParseBytes_Suppressions(t *testing.T) {
+	yaml := `
+stages:
+  - build
+
+# glint: ignore GL007
+deprecated-job:
+  stage: build
+  only:
+    - main
+
+normal-job:
+  stage: build
+  script: echo ok
+`
+	p, err := ParseBytes([]byte(yaml))
+	if err != nil {
+		t.Fatalf("ParseBytes: %v", err)
+	}
+	if p.Suppressions == nil {
+		t.Fatal("Suppressions is nil")
+	}
+	rules, ok := p.Suppressions["deprecated-job"]
+	if !ok {
+		t.Fatal("no suppression for deprecated-job")
+	}
+	if len(rules) != 1 || rules[0] != "GL007" {
+		t.Errorf("rules = %v, want [GL007]", rules)
+	}
+	if _, ok := p.Suppressions["normal-job"]; ok {
+		t.Error("normal-job should have no suppressions")
+	}
+}

internal/model/pipeline.go

@@ -3,20 +3,36 @@ package model
 // Pipeline represents the top-level structure of a .gitlab-ci.yml file.
 // Unknown top-level keys are collected into Jobs.
 type Pipeline struct {
-	Stages    []string          `yaml:"stages"`
-	Variables map[string]string `yaml:"variables"`
-	Default   *DefaultConfig    `yaml:"default"`
-	Include   []any             `yaml:"include"`
-	Workflow  *Workflow         `yaml:"workflow"`
+	SourceFile string         // path of the root pipeline file; set by Parse
+	Stages     []string       `yaml:"stages"`
+	Variables  map[string]any `yaml:"variables"` // string or {value,description,options} map
+	Default    *DefaultConfig `yaml:"default"`
+	Include    []any          `yaml:"include"`
+	Workflow   *Workflow      `yaml:"workflow"`
 	// Jobs holds every non-reserved top-level key (i.e. job definitions).
-	Jobs    map[string]Job                 `yaml:"-"`
-	RawJobs map[string]map[string]any      `yaml:"-"` // pre-resolution raw maps, used by the resolver
+	Jobs    map[string]Job            `yaml:"-"`
+	RawJobs map[string]map[string]any `yaml:"-"` // pre-resolution raw maps, used by the resolver
+	// Suppressions maps job names to lists of suppressed rule IDs parsed from
+	// "# glint: ignore RULE" comments in the pipeline YAML. Only populated for
+	// the root pipeline file (not for included templates).
+	Suppressions map[string][]string `yaml:"-"`
+}
+
+// SetJobOrigin sets the File field on all jobs that don't already have one.
+// Called after ParseBytes to record which file each job came from.
+func (p *Pipeline) SetJobOrigin(file string) {
+	for name, j := range p.Jobs {
+		if j.File == "" {
+			j.File = file
+		}
+		p.Jobs[name] = j
+	}
 }
 
 type DefaultConfig struct {
-	Image        string   `yaml:"image"`
-	BeforeScript []string `yaml:"before_script"`
-	AfterScript  []string `yaml:"after_script"`
+	Image        any      `yaml:"image"`        // string or {name,pull_policy,...} map
+	BeforeScript any      `yaml:"before_script"` // []string or string (block scalar)
+	AfterScript  any      `yaml:"after_script"`  // []string or string
 	Cache        any      `yaml:"cache"`
 	Artifacts    any      `yaml:"artifacts"`
 	Retry        any      `yaml:"retry"`
@@ -29,16 +45,18 @@ type Workflow struct {
 }
 
 type Job struct {
-	Name         string   // set by parser, not from YAML
+	Name string // set by parser, not from YAML
+	File string // source file; set by Parse / resolver
+	Line int    // line of the job key in its source file; set by parser
 	Stage        string   `yaml:"stage"`
-	Script       []string `yaml:"script"`
-	Run          any      `yaml:"run"` // alternative to script (CI steps)
-	BeforeScript []string `yaml:"before_script"`
-	AfterScript  []string `yaml:"after_script"`
+	Script       any `yaml:"script"`       // []string or string (block scalar)
+	Run          any `yaml:"run"`          // alternative to script (CI steps)
+	BeforeScript any `yaml:"before_script"` // []string or string
+	AfterScript  any `yaml:"after_script"`  // []string or string
 	Image        any      `yaml:"image"`
 	Services     []any    `yaml:"services"`
-	Variables    map[string]string `yaml:"variables"`
-	Rules        []Rule   `yaml:"rules"`
+	Variables    map[string]any `yaml:"variables"` // string or {value,description,options} map
+	Rules        []Rule         `yaml:"rules"`
 	Only         any      `yaml:"only"`
 	Except       any      `yaml:"except"`
 	Needs        []any    `yaml:"needs"`
@@ -66,10 +84,11 @@ type Job struct {
 }
 
 type Rule struct {
-	If      string `yaml:"if"`
-	When    string `yaml:"when"`
-	Changes []string `yaml:"changes"`
-	Exists  []string `yaml:"exists"`
+	If        string         `yaml:"if"`
+	When      string         `yaml:"when"`
+	Changes   any            `yaml:"changes"`   // []string or {paths,compare_to} map
+	Exists    any            `yaml:"exists"`    // []string or map form
+	Variables map[string]any `yaml:"variables"` // set/override variables when rule matches (GitLab CI 15.0+)
 }
 
 // ReservedKeys are top-level GitLab CI keys that are NOT job definitions.

internal/resolver/extends.go

@@ -10,33 +10,45 @@ import (
 // Resolve resolves all extends: references in p.Jobs in place.
 // Jobs are merged depth-first so that base definitions are resolved before
 // derived ones. Mutates p.Jobs with the fully merged Job structs.
-func Resolve(p *model.Pipeline) error {
+//
+// The first return value lists extends references whose base job could not be
+// found (e.g. it lives in a remote include that was not fetched). Those jobs
+// are left unmerged but still passed to the linter. A non-nil error is only
+// returned for unrecoverable situations such as circular dependencies.
+func Resolve(p *model.Pipeline) ([]ExtendWarning, error) {
+	var extWarnings []ExtendWarning
+
 	// Build extends graph: jobName -> ordered list of base job names.
 	extendsGraph := make(map[string][]string, len(p.Jobs))
 	for name, job := range p.Jobs {
 		bases, err := parseExtends(job.Extends)
 		if err != nil {
-			return fmt.Errorf("job %q: invalid extends: %w", name, err)
+			return extWarnings, fmt.Errorf("job %q: invalid extends: %w", name, err)
 		}
 		if len(bases) == 0 {
 			continue
 		}
+		skip := false
 		for _, base := range bases {
 			if _, ok := p.RawJobs[base]; !ok {
-				return fmt.Errorf("job %q extends unknown job %q", name, base)
+				extWarnings = append(extWarnings, ExtendWarning{Job: name, Base: base})
+				skip = true
 			}
 		}
+		if skip {
+			continue // leave this job unmerged; still linted with its own fields
+		}
 		extendsGraph[name] = bases
 	}
 
 	if len(extendsGraph) == 0 {
-		return nil
+		return extWarnings, nil
 	}
 
 	// Topological sort — bases must be resolved before derived jobs.
 	order, err := topoSort(extendsGraph)
 	if err != nil {
-		return err
+		return extWarnings, err
 	}
 
 	// resolved holds the final merged raw map for each processed job.
@@ -61,17 +73,22 @@ func Resolve(p *model.Pipeline) error {
 		// Re-decode the merged map into a Job struct.
 		data, err := yaml.Marshal(merged)
 		if err != nil {
-			return fmt.Errorf("job %q: re-encoding merged definition: %w", name, err)
+			return extWarnings, fmt.Errorf("job %q: re-encoding merged definition: %w", name, err)
 		}
 		var j model.Job
 		if err := yaml.Unmarshal(data, &j); err != nil {
-			return fmt.Errorf("job %q: re-decoding merged definition: %w", name, err)
+			return extWarnings, fmt.Errorf("job %q: re-decoding merged definition: %w", name, err)
 		}
 		j.Name = name
+		// Preserve source location — File/Line are not part of the YAML map
+		// and are lost during the encode/decode round-trip.
+		orig := p.Jobs[name]
+		j.File = orig.File
+		j.Line = orig.Line
 		p.Jobs[name] = j
 	}
 
-	return nil
+	return extWarnings, nil
 }
 
 // parseExtends normalises the extends field (string or []any) into []string.

internal/resolver/includes.go

@@ -2,18 +2,33 @@ package resolver
 
 import (
 	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
 	"strings"
 
 	"git.k3nny.fr/glint/internal/fetcher"
 	"git.k3nny.fr/glint/internal/model"
 )
 
-// IncludeWarning describes a remote include entry that could not be resolved.
+// maxIncludeDepth is the maximum nesting level for include: chains.
+// This matches GitLab's own documented limit and also guards against
+// include cycles that slip past the visited-key deduplication.
+const maxIncludeDepth = 100
+
+// inputPlaceholderRe matches GitLab CI component input references:
+//
+//	$[[ inputs.KEY ]]
+//	$[[ inputs.KEY | default('value') ]]
+//	$[[ inputs.KEY | default(true) ]]
+//	$[[ inputs.KEY | default(123) ]]
+var inputPlaceholderRe = regexp.MustCompile(
+	`\$\[\[\s*inputs\.(\w+)(?:\s*\|\s*default\(([^)]*)\))?\s*\]\]`)
+
+// IncludeWarning describes an include entry that could not be resolved.
 // These are surfaced to the user as [WARNING] lines before the lint findings.
 type IncludeWarning struct {
-	// Label is a short human-readable identifier shown in the warning message,
-	// e.g. "project my-group/templates:/ci.yml@main" or
-	// "component gitlab.com/components/golang/build@v1.0".
+	// Label is a short human-readable identifier shown in the warning message.
 	Label   string
 	Err     error // nil when Skipped is true
 	Skipped bool  // no token available — skipped without attempting a network call
@@ -30,46 +45,163 @@ func (w IncludeWarning) String() string {
 		w.Label, w.Err)
 }
 
+// ExtendWarning describes an extends: reference whose base job could not be
+// found. This typically means the base is in a remote include that was not
+// fetched (e.g. no token). The job's extends chain is skipped; the job itself
+// is still linted with whatever fields it directly defines.
+type ExtendWarning struct {
+	Job  string // job that declares the extends
+	Base string // the unknown base job name
+}
+
 // ResolveIncludes processes the pipeline's include: block.
 //
-// Project includes (include: project: ...) require authentication and are
-// skipped with a warning when no token is configured.
+// rootDir is the repository root directory used to resolve local: includes.
+// In practice this is the directory of the top-level pipeline file being linted.
 //
-// Component includes (include: component: ...) attempt the fetch
-// unauthenticated first, so public CI/CD catalog components work without a
-// token. A warning is emitted when the fetch fails.
+// Local includes are read from disk and merged recursively.
+// Project includes require authentication and are skipped with a warning when
+// no token is configured. Component includes are attempted unauthenticated.
+// Remote and template includes are silently skipped (resolved by GitLab at runtime).
 //
-// Non-resolvable include forms (local, remote, template) are silently skipped.
-func ResolveIncludes(p *model.Pipeline, cfg fetcher.GitLabConfig) []IncludeWarning {
+// The second return value carries extends warnings discovered while recursively
+// processing included files (forwarded from resolver.Resolve calls).
+func ResolveIncludes(p *model.Pipeline, cfg fetcher.GitLabConfig, rootDir string) ([]IncludeWarning, []ExtendWarning) {
+	visited := map[string]bool{}
+	return resolveIncludes(p, p.Include, cfg, rootDir, visited, 0)
+}
+
+// resolveIncludes is the recursive core of ResolveIncludes.
+func resolveIncludes(p *model.Pipeline, includes []any, cfg fetcher.GitLabConfig, rootDir string, visited map[string]bool, depth int) ([]IncludeWarning, []ExtendWarning) {
+	if depth > maxIncludeDepth {
+		return []IncludeWarning{{
+			Label: "includes",
+			Err:   fmt.Errorf("include nesting depth exceeded (%d levels) — possible include cycle detected", maxIncludeDepth),
+		}}, nil
+	}
+
 	var warnings []IncludeWarning
-	for _, inc := range p.Include {
+	var extWarnings []ExtendWarning
+
+	for _, inc := range includes {
 		entry, ok := normaliseInclude(inc)
 		if !ok {
 			continue
 		}
 
 		if project, _ := entry["project"].(string); project != "" {
-			warnings = append(warnings, resolveProjectInclude(p, entry, project, cfg)...)
+			w, ew := resolveProjectInclude(p, entry, project, cfg, rootDir, visited, depth)
+			warnings = append(warnings, w...)
+			extWarnings = append(extWarnings, ew...)
 			continue
 		}
 
 		if compRef, _ := entry["component"].(string); compRef != "" {
-			if w, ok := resolveComponentInclude(p, compRef, cfg); ok {
+			inputs := extractInputs(entry)
+			w, ew, hadErr := resolveComponentInclude(p, compRef, inputs, cfg, rootDir, visited, depth)
+			if hadErr {
 				warnings = append(warnings, w)
 			}
+			extWarnings = append(extWarnings, ew...)
 			continue
 		}
 
-		// local, remote, template — resolved by GitLab at runtime, skip silently.
+		if local, _ := entry["local"].(string); local != "" {
+			w, ew := resolveLocalInclude(p, local, cfg, rootDir, visited, depth)
+			warnings = append(warnings, w...)
+			extWarnings = append(extWarnings, ew...)
+			continue
+		}
+
+		if remote, _ := entry["remote"].(string); remote != "" {
+			w, ew := resolveRemoteInclude(p, remote, cfg, rootDir, visited, depth)
+			warnings = append(warnings, w...)
+			extWarnings = append(extWarnings, ew...)
+			continue
+		}
+
+		// template — resolved by GitLab at runtime, skip silently.
 	}
-	return warnings
+	return warnings, extWarnings
+}
+
+// resolveLocalInclude reads a local file from disk (paths are always relative
+// to the repository root, with or without a leading slash), recursively
+// resolves its own includes, and merges it into p.
+func resolveLocalInclude(p *model.Pipeline, rawPath string, cfg fetcher.GitLabConfig, rootDir string, visited map[string]bool, depth int) ([]IncludeWarning, []ExtendWarning) {
+	relPath := strings.TrimPrefix(rawPath, "/")
+	absPath := filepath.Join(rootDir, relPath)
+	label := "local " + rawPath
+
+	if visited[absPath] {
+		return nil, nil
+	}
+	visited[absPath] = true
+
+	data, err := os.ReadFile(absPath)
+	if err != nil {
+		return []IncludeWarning{{Label: label, Err: err}}, nil
+	}
+
+	included, err := model.ParseBytes(data)
+	if err != nil {
+		return []IncludeWarning{{Label: label, Err: fmt.Errorf("parsing YAML: %w", err)}}, nil
+	}
+	included.SetJobOrigin(absPath)
+
+	// Recursively resolve the included file's own includes first, merging
+	// everything into `included` before we merge it into the parent `p`.
+	var warnings []IncludeWarning
+	var extWarnings []ExtendWarning
+	if len(included.Include) > 0 {
+		w, ew := resolveIncludes(included, included.Include, cfg, rootDir, visited, depth+1)
+		warnings = append(warnings, w...)
+		extWarnings = append(extWarnings, ew...)
+	}
+
+	mergeIncluded(p, included)
+	return warnings, extWarnings
+}
+
+// resolveRemoteInclude fetches a plain HTTPS URL, parses it as CI YAML, and
+// merges it into p. Sub-includes of the fetched file are resolved recursively.
+func resolveRemoteInclude(p *model.Pipeline, rawURL string, cfg fetcher.GitLabConfig, rootDir string, visited map[string]bool, depth int) ([]IncludeWarning, []ExtendWarning) {
+	label := "remote " + rawURL
+
+	if visited[rawURL] {
+		return nil, nil
+	}
+	visited[rawURL] = true
+
+	data, err := cfg.FetchURL(rawURL)
+	if err != nil {
+		return []IncludeWarning{{Label: label, Err: err}}, nil
+	}
+
+	included, err := model.ParseBytes(data)
+	if err != nil {
+		return []IncludeWarning{{Label: label, Err: fmt.Errorf("parsing YAML: %w", err)}}, nil
+	}
+	included.SetJobOrigin(rawURL)
+
+	var warnings []IncludeWarning
+	var extWarnings []ExtendWarning
+	if len(included.Include) > 0 {
+		w, ew := resolveIncludes(included, included.Include, cfg, rootDir, visited, depth+1)
+		warnings = append(warnings, w...)
+		extWarnings = append(extWarnings, ew...)
+	}
+
+	mergeIncluded(p, included)
+	return warnings, extWarnings
 }
 
 // resolveProjectInclude fetches all files listed under a single project: entry
 // and merges them into p.
-func resolveProjectInclude(p *model.Pipeline, entry map[string]any, project string, cfg fetcher.GitLabConfig) []IncludeWarning {
+func resolveProjectInclude(p *model.Pipeline, entry map[string]any, project string, cfg fetcher.GitLabConfig, rootDir string, visited map[string]bool, depth int) ([]IncludeWarning, []ExtendWarning) {
 	ref, _ := entry["ref"].(string)
 	var warnings []IncludeWarning
+	var extWarnings []ExtendWarning
 
 	for _, filePath := range includeFiles(entry) {
 		label := fmt.Sprintf("project %s:%s", project, filePath)
@@ -77,6 +209,12 @@ func resolveProjectInclude(p *model.Pipeline, entry map[string]any, project stri
 			label += "@" + ref
 		}
 
+		visitKey := fmt.Sprintf("project:%s:%s@%s", project, filePath, ref)
+		if visited[visitKey] {
+			continue
+		}
+		visited[visitKey] = true
+
 		if !cfg.HasToken() {
 			warnings = append(warnings, IncludeWarning{Label: label, Skipped: true})
 			continue
@@ -93,57 +231,111 @@ func resolveProjectInclude(p *model.Pipeline, entry map[string]any, project stri
 			warnings = append(warnings, IncludeWarning{Label: label, Err: fmt.Errorf("parsing YAML: %w", err)})
 			continue
 		}
+		included.SetJobOrigin(label)
+
+		if len(included.Include) > 0 {
+			w, ew := resolveIncludes(included, included.Include, cfg, rootDir, visited, depth+1)
+			warnings = append(warnings, w...)
+			extWarnings = append(extWarnings, ew...)
+		}
 
 		mergeIncluded(p, included)
 	}
-	return warnings
+	return warnings, extWarnings
 }
 
-// resolveComponentInclude fetches a CI/CD catalog component and merges it into p.
-// Returns (warning, true) if something went wrong; (zero, false) on success.
-func resolveComponentInclude(p *model.Pipeline, ref string, cfg fetcher.GitLabConfig) (IncludeWarning, bool) {
+// resolveComponentInclude fetches a CI/CD catalog component, substitutes any
+// $[[ inputs.KEY ]] placeholders with values from `inputs` (the include's
+// with: block), and merges the result into p.
+// Returns (warning, extWarnings, true) if something went wrong; (zero, nil, false) on success.
+func resolveComponentInclude(p *model.Pipeline, ref string, inputs map[string]any, cfg fetcher.GitLabConfig, rootDir string, visited map[string]bool, depth int) (IncludeWarning, []ExtendWarning, bool) {
 	label := "component " + ref
 
-	// Variable interpolation (e.g. $CI_SERVER_FQDN) cannot be resolved locally.
 	if strings.ContainsRune(ref, '$') {
 		return IncludeWarning{
 			Label: label,
 			Err:   fmt.Errorf("component reference contains a CI variable that cannot be resolved at lint time"),
-		}, true
+		}, nil, true
 	}
 
+	visitKey := "component:" + ref
+	if visited[visitKey] {
+		return IncludeWarning{}, nil, false
+	}
+	visited[visitKey] = true
+
 	host, project, component, version, err := parseComponentRef(ref)
 	if err != nil {
-		return IncludeWarning{Label: label, Err: err}, true
+		return IncludeWarning{Label: label, Err: err}, nil, true
 	}
 
 	hostCfg := cfg.ForHost(host)
 	data, err := fetchComponentFile(hostCfg, project, component, version)
 	if err != nil {
-		return IncludeWarning{Label: label, Err: err}, true
+		return IncludeWarning{Label: label, Err: err}, nil, true
 	}
 
+	// Substitute $[[ inputs.KEY ]] placeholders with the values from with:.
+	data = substituteInputs(data, inputs)
+
 	included, err := model.ParseBytes(data)
 	if err != nil {
-		return IncludeWarning{Label: label, Err: fmt.Errorf("parsing component YAML: %w", err)}, true
+		return IncludeWarning{Label: label, Err: fmt.Errorf("parsing component YAML: %w", err)}, nil, true
+	}
+	included.SetJobOrigin(label)
+
+	var extWarnings []ExtendWarning
+	if len(included.Include) > 0 {
+		_, ew := resolveIncludes(included, included.Include, cfg, rootDir, visited, depth+1)
+		extWarnings = append(extWarnings, ew...)
 	}
 
 	mergeIncluded(p, included)
-	return IncludeWarning{}, false
+	return IncludeWarning{}, extWarnings, false
+}
+
+// substituteInputs replaces all $[[ inputs.KEY ]] and
+// $[[ inputs.KEY | default('…') ]] placeholders in data with the corresponding
+// values from inputs (the with: block of the component include entry).
+// Missing keys with no default become empty strings.
+// Missing keys with a default use the default value (single/double quotes stripped).
+func substituteInputs(data []byte, inputs map[string]any) []byte {
+	if len(data) == 0 {
+		return data
+	}
+	return inputPlaceholderRe.ReplaceAllFunc(data, func(match []byte) []byte {
+		groups := inputPlaceholderRe.FindSubmatch(match)
+		if len(groups) < 2 {
+			return match
+		}
+		if val, ok := inputs[string(groups[1])]; ok {
+			return []byte(fmt.Sprintf("%v", val))
+		}
+		// Use the default value when the key is absent from inputs.
+		if len(groups) >= 3 && len(groups[2]) > 0 {
+			def := strings.TrimSpace(string(groups[2]))
+			if (strings.HasPrefix(def, "'") && strings.HasSuffix(def, "'")) ||
+				(strings.HasPrefix(def, `"`) && strings.HasSuffix(def, `"`)) {
+				def = def[1 : len(def)-1]
+			}
+			return []byte(def)
+		}
+		return []byte("")
+	})
+}
+
+// extractInputs returns the with: map from a component include entry, or nil.
+func extractInputs(entry map[string]any) map[string]any {
+	with, ok := entry["with"].(map[string]any)
+	if !ok {
+		return nil
+	}
+	return with
 }
 
 // parseComponentRef parses a CI/CD component reference of the form:
 //
 //	<host>/<project-path>/<component-name>@<version>
-//
-// The host is the GitLab instance FQDN. The last path segment before @ is the
-// component name; everything between host and component name is the project path.
-//
-// Examples:
-//
-//	gitlab.com/components/golang/build@v1.0.0
-//	gitlab.example.com/my-org/ci-templates/lint@main
-//	gitlab.com/components/secret-detection/secret-detection@~latest
 func parseComponentRef(ref string) (host, project, component, version string, err error) {
 	atIdx := strings.LastIndex(ref, "@")
 	if atIdx < 0 || atIdx == len(ref)-1 {
@@ -154,7 +346,6 @@ func parseComponentRef(ref string) (host, project, component, version string, er
 	path := ref[:atIdx]
 
 	parts := strings.Split(path, "/")
-	// Minimum: host + at least one project segment + component = 3 parts.
 	if len(parts) < 3 {
 		err = fmt.Errorf("component reference %q must be <host>/<project>/<component>@<version>", ref)
 		return
@@ -167,9 +358,6 @@ func parseComponentRef(ref string) (host, project, component, version string, er
 }
 
 // fetchComponentFile fetches a component's template YAML from a GitLab project.
-// GitLab supports two layouts; both are attempted:
-//   - templates/<component>.yml  (single-file component)
-//   - templates/<component>/template.yml  (directory component)
 func fetchComponentFile(cfg fetcher.GitLabConfig, project, component, version string) ([]byte, error) {
 	primary := "templates/" + component + ".yml"
 	data, err := cfg.FetchFile(project, primary, version)
@@ -180,14 +368,12 @@ func fetchComponentFile(cfg fetcher.GitLabConfig, project, component, version st
 	fallback := "templates/" + component + "/template.yml"
 	data2, err2 := cfg.FetchFile(project, fallback, version)
 	if err2 != nil {
-		// Return the primary error — it refers to the canonical path.
 		return nil, fmt.Errorf("%v (also tried %s: %v)", err, fallback, err2)
 	}
 	return data2, nil
 }
 
 // normaliseInclude converts a raw include: list element to a string-keyed map.
-// An include: value can be a plain string (shorthand local) or a map.
 func normaliseInclude(raw any) (map[string]any, bool) {
 	switch v := raw.(type) {
 	case map[string]any:
@@ -199,7 +385,6 @@ func normaliseInclude(raw any) (map[string]any, bool) {
 }
 
 // includeFiles returns the list of file paths from an include entry.
-// The file: key may be a single string or a list of strings.
 func includeFiles(entry map[string]any) []string {
 	raw, ok := entry["file"]
 	if !ok {
@@ -220,8 +405,9 @@ func includeFiles(entry map[string]any) []string {
 	return nil
 }
 
-// mergeIncluded copies jobs and stages from src into dst.
-// dst (the main pipeline) always wins when a key already exists.
+// mergeIncluded copies jobs, stages, and variables from src into dst.
+// dst (the main pipeline) always wins when a key already exists — this matches
+// GitLab's precedence rule where root-pipeline values override included templates.
 func mergeIncluded(dst, src *model.Pipeline) {
 	stageSet := make(map[string]bool, len(dst.Stages))
 	for _, s := range dst.Stages {
@@ -242,4 +428,16 @@ func mergeIncluded(dst, src *model.Pipeline) {
 			}
 		}
 	}
+
+	// Merge pipeline-level variables: dst wins on conflict (root overrides includes).
+	if len(src.Variables) > 0 {
+		if dst.Variables == nil {
+			dst.Variables = make(map[string]any, len(src.Variables))
+		}
+		for k, v := range src.Variables {
+			if _, exists := dst.Variables[k]; !exists {
+				dst.Variables[k] = v
+			}
+		}
+	}
 }

internal/resolver/includes_test.go

@@ -0,0 +1,90 @@
+package resolver
+
+import (
+	"testing"
+)
+
+func TestSubstituteInputs(t *testing.T) {
+	cases := []struct {
+		name   string
+		data   string
+		inputs map[string]any
+		want   string
+	}{
+		{
+			name:   "simple substitution",
+			data:   `stage: $[[ inputs.STAGE ]]`,
+			inputs: map[string]any{"STAGE": "deploy"},
+			want:   `stage: deploy`,
+		},
+		{
+			name:   "default string used when key absent",
+			data:   `image: $[[ inputs.IMAGE | default('ubuntu:22.04') ]]`,
+			inputs: map[string]any{},
+			want:   `image: ubuntu:22.04`,
+		},
+		{
+			name:   "input overrides default",
+			data:   `image: $[[ inputs.IMAGE | default('ubuntu:22.04') ]]`,
+			inputs: map[string]any{"IMAGE": "alpine:3.18"},
+			want:   `image: alpine:3.18`,
+		},
+		{
+			name:   "integer input",
+			data:   `variables:\n  RETRIES: $[[ inputs.RETRY_COUNT ]]`,
+			inputs: map[string]any{"RETRY_COUNT": 3},
+			want:   `variables:\n  RETRIES: 3`,
+		},
+		{
+			name:   "boolean default",
+			data:   `variables:\n  ENABLED: $[[ inputs.ENABLE | default(true) ]]`,
+			inputs: map[string]any{},
+			want:   `variables:\n  ENABLED: true`,
+		},
+		{
+			name:   "numeric default",
+			data:   `variables:\n  COUNT: $[[ inputs.COUNT | default(5) ]]`,
+			inputs: map[string]any{},
+			want:   `variables:\n  COUNT: 5`,
+		},
+		{
+			name:   "missing key no default becomes empty",
+			data:   `script: $[[ inputs.CMD ]]`,
+			inputs: map[string]any{},
+			want:   `script: `,
+		},
+		{
+			name:   "no placeholders unchanged",
+			data:   `stage: build`,
+			inputs: nil,
+			want:   `stage: build`,
+		},
+		{
+			name:   "multiple placeholders in one document",
+			data:   "stage: $[[ inputs.STAGE ]]\nimage: $[[ inputs.IMAGE | default('alpine') ]]",
+			inputs: map[string]any{"STAGE": "test"},
+			want:   "stage: test\nimage: alpine",
+		},
+		{
+			name:   "double-quoted default",
+			data:   `image: $[[ inputs.IMAGE | default("debian:12") ]]`,
+			inputs: map[string]any{},
+			want:   `image: debian:12`,
+		},
+		{
+			name:   "whitespace inside brackets",
+			data:   `stage: $[[ inputs.STAGE  ]]`,
+			inputs: map[string]any{"STAGE": "build"},
+			want:   `stage: build`,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := string(substituteInputs([]byte(tc.data), tc.inputs))
+			if got != tc.want {
+				t.Errorf("substituteInputs:\n got  %q\n want %q", got, tc.want)
+			}
+		})
+	}
+}

testdata/config_ignored/.gitlab-ci.yml

@@ -0,0 +1,10 @@
+stages:
+  - build
+
+# GL007 (only/except deprecated) would normally fire here, but the .glint.yml
+# in this directory ignores GL007.
+deprecated-job:
+  stage: build
+  only:
+    - main
+  script: echo ok

testdata/config_ignored/.glint.yml

@@ -0,0 +1,2 @@
+ignore:
+  - GL007

testdata/config_severity/.gitlab-ci.yml

@@ -0,0 +1,8 @@
+stages:
+  - build
+
+# GL004 (undefined stage) is demoted to warning by .glint.yml, so the exit
+# code must be 0 even though there is a finding.
+bad-stage-job:
+  stage: nonexistent
+  script: echo hi

testdata/config_severity/.glint.yml

@@ -0,0 +1,2 @@
+severity:
+  GL004: warning

testdata/config_suppress/.gitlab-ci.yml

@@ -0,0 +1,15 @@
+stages:
+  - build
+
+# glint: ignore GL007
+suppressed-job:
+  stage: build
+  only:
+    - main
+  script: echo ok
+
+still-flagged-job:
+  stage: build
+  only:
+    - main
+  script: echo ok

testdata/dead_rules.yml

@@ -0,0 +1,59 @@
+---
+# dead_rules.yml
+# Exercises GL033: rules: block where every rule has when: never.
+# All flagged jobs produce a WARNING (exit 0). Valid jobs must not be flagged.
+
+stages:
+  - build
+  - test
+  - deploy
+
+# ── Jobs that should trigger GL033 ─────────────────────────────────────────
+
+# Single bare catch-all never — job is always excluded.
+disabled-job:
+  stage: build
+  script: echo disabled
+  rules:
+    - when: never
+
+# Multiple rules, all when: never — no branch can activate this job.
+dead-multi:
+  stage: test
+  script: echo dead
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: never
+    - if: '$CI_COMMIT_BRANCH == "develop"'
+      when: never
+    - when: never
+
+# ── Jobs that must NOT trigger GL033 ───────────────────────────────────────
+
+# First rule can activate.
+main-only:
+  stage: build
+  script: echo main
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: on_success
+    - when: never
+
+# Rule with no when: — defaults to on_success, so job is reachable.
+implicit-on-success:
+  stage: test
+  script: echo implicit
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "develop"'
+
+# Manual is not never — job is reachable (just gated).
+manual-gate:
+  stage: deploy
+  script: echo deploy
+  rules:
+    - when: manual
+
+# No rules at all — always active.
+always-active:
+  stage: build
+  script: echo always

testdata/includes_remote.yml

@@ -0,0 +1,14 @@
+---
+# Exercises include: remote: URL fetching and sub-include recursion.
+# The remote file is a real public GitLab CI template; it may contain its own
+# includes which should also be resolved. Exit code is 0 (warnings allowed).
+stages:
+  - test
+
+include:
+  - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Bash.gitlab-ci.yml
+
+local-job:
+  stage: test
+  script:
+    - echo "local job alongside remote include"

testdata/needs.yml

@@ -38,3 +38,12 @@ missing-needs-job:
     - echo "bad"
   needs:
     - nonexistent-job    # ERROR: job doesn't exist
+
+# optional: true — missing dep should be WARNING not ERROR
+optional-needs-job:
+  stage: build
+  script:
+    - echo "I depend on something that may not exist"
+  needs:
+    - job: nonexistent-optional-job
+      optional: true

testdata/new_rules_invalid.yml

@@ -0,0 +1,81 @@
+stages:
+  - build
+  - test
+  - test
+
+variables:
+  DEPLOY_ENV: staging
+
+# GL040: duplicate stage "test" above triggers a warning
+
+# GL034: services map form missing name
+service-no-name:
+  stage: build
+  script: [echo ok]
+  services:
+    - alias: my-svc
+
+# GL034: services map form with invalid alias (contains spaces)
+service-bad-alias:
+  stage: build
+  script: [echo ok]
+  services:
+    - name: redis:latest
+      alias: "my bad alias"
+
+# GL035: rules:changes with absolute path
+absolute-changes:
+  stage: test
+  script: [echo test]
+  rules:
+    - changes:
+        - /src/main.go
+
+# GL035: rules:exists with absolute path
+absolute-exists:
+  stage: test
+  script: [echo test]
+  rules:
+    - exists:
+        - /Dockerfile
+
+# GL036: invalid timeout format
+bad-timeout:
+  stage: build
+  script: [echo build]
+  timeout: forever
+
+# GL037: id_tokens entry missing aud
+bad-token:
+  stage: test
+  script: [echo test]
+  id_tokens:
+    MY_TOKEN:
+      expire: 3600
+
+# GL038: secrets entry missing provider
+bad-secret:
+  stage: test
+  script: [echo test]
+  secrets:
+    DB_PASSWORD:
+      expire: 3600
+
+# GL039: pages keyword but publish dir not in artifacts.paths
+bad-pages:
+  stage: build
+  script: [mkdocs build]
+  pages:
+    publish: dist
+  artifacts:
+    paths:
+      - public
+
+# GL041: cache.key.files contains a glob
+bad-cache-glob:
+  stage: build
+  script: [echo build]
+  cache:
+    key:
+      files:
+        - "*.sum"

testdata/new_rules_valid.yml

@@ -0,0 +1,116 @@
+stages:
+  - build
+  - test
+  - deploy
+
+variables:
+  DEPLOY_ENV: staging
+
+# GL034: services — string form and map form with name are both valid
+service-string:
+  stage: build
+  script: [echo ok]
+  services:
+    - redis:latest
+    - postgres:14
+
+service-map:
+  stage: build
+  script: [echo ok]
+  services:
+    - name: postgres:14
+      alias: db
+    - name: redis:latest
+      alias: cache-svc
+
+# GL035: rules:changes/exists — relative paths are valid
+rules-relative:
+  stage: test
+  script: [echo test]
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      changes:
+        - src/**/*.go
+        - tests/*.go
+    - exists:
+        - Dockerfile
+        - docker-compose.yml
+      when: on_success
+
+# GL036: timeout — valid duration strings
+timeout-short:
+  stage: build
+  script: [echo build]
+  timeout: 30m
+
+timeout-long:
+  stage: build
+  script: [echo build]
+  timeout: 1h 30m
+
+timeout-words:
+  stage: test
+  script: [echo test]
+  timeout: 90 minutes
+
+timeout-combined:
+  stage: deploy
+  script: [echo deploy]
+  timeout: 2 hours 30 minutes
+
+# GL037: id_tokens — entry with valid aud
+token-job:
+  stage: build
+  script: [echo build]
+  id_tokens:
+    VAULT_TOKEN:
+      aud: https://vault.example.com
+    SIGSTORE_TOKEN:
+      aud: sigstore
+
+# GL038: secrets — valid provider keys
+secret-vault:
+  stage: deploy
+  script: [echo deploy]
+  secrets:
+    DB_PASSWORD:
+      vault: production/db/password@ops
+
+secret-gcp:
+  stage: deploy
+  script: [echo deploy]
+  secrets:
+    API_KEY:
+      gcp_secret_manager:
+        name: my-api-key
+        version: latest
+
+# GL039: pages keyword — publish dir present in artifacts.paths
+pages-keyword:
+  stage: deploy
+  script: [mkdocs build]
+  pages:
+    publish: site
+  artifacts:
+    paths:
+      - site
+
+pages-keyword-default:
+  stage: deploy
+  script: [make docs]
+  pages: true
+  artifacts:
+    paths:
+      - public
+
+# GL040: no duplicate stages (unique stages defined above)
+
+# GL041: cache.key.files — list of exact paths
+cache-key-job:
+  stage: build
+  script: [echo build]
+  cache:
+    key:
+      files:
+        - go.sum
+        - go.mod

testdata/rules_if_expr.yml

@@ -0,0 +1,51 @@
+---
+# rules_if_expr.yml
+# Exercises the rules:if: expression evaluator for:
+#   - Multi-line block-scalar expressions (|| on next line)
+#   - ${VAR} curly-brace variable syntax
+#   - Regex flags (/pattern/i case-insensitive)
+#   - Parenthesised compound expressions
+# Expected: exits 0 (lints clean with no context).
+
+stages:
+  - build
+  - deploy
+
+variables:
+  DEPLOY_ENVIRONMENTS:
+    value: "staging"
+    description: "Target deployment environment"
+
+build:
+  stage: build
+  script: make build
+  rules:
+    # Multi-line expression: || on next line
+    - if: |
+        $CI_COMMIT_BRANCH == "main" ||
+        $CI_COMMIT_BRANCH == "develop"
+      when: on_success
+    - when: never
+
+deploy-feature:
+  stage: deploy
+  script: make deploy
+  rules:
+    # ${VAR} curly-brace syntax
+    - if: '${CI_COMMIT_BRANCH} != null && ${CI_COMMIT_TAG} == null'
+      when: manual
+    - when: never
+
+release:
+  stage: deploy
+  script: make release
+  rules:
+    # Case-insensitive regex flag
+    - if: '$CI_COMMIT_BRANCH =~ /^(main|master)$/i'
+      when: on_success
+    # Parenthesised compound with multi-line
+    - if: >-
+        ($CI_COMMIT_TAG != null) &&
+        ($CI_PIPELINE_SOURCE == "push" || $CI_PIPELINE_SOURCE == "web")
+      when: on_success
+    - when: never

testdata/samba/.gitlab-ci-coverage-runners.yml

@@ -0,0 +1,4 @@
+include:
+  - /.gitlab-ci-default-runners.yml
+
+# Currently we're happy with the defaults

testdata/samba/.gitlab-ci-coverage.yml

@@ -0,0 +1,12 @@
+# This is just used for the scheduled pipelines in the
+# https://gitlab.com/samba-team/samba configuration
+#
+
+variables:
+  SAMBA_CI_FLAVOR: "coverage"
+  # "--enable-coverage" or ""
+  SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE: "--enable-coverage"
+
+include:
+  - /.gitlab-ci-coverage-runners.yml
+  - /.gitlab-ci-main.yml

testdata/samba/.gitlab-ci-default-runners.yml

@@ -0,0 +1,30 @@
+# From https://docs.gitlab.com/ee/ci/runners/hosted_runners/linux.html
+#
+#   ...
+#
+#   Runner Tag              vCPUs   Memory   Storage
+#   saas-linux-small-amd64  2       8 GB     25 GB
+#
+# Our current private runner 'docker', 'samba-ci-private', 'shared' and
+# 'ubuntu2204'. It runs with an ubuntu2204 kernel (5.15) and provides an
+# ext4 filesystem, 2 CPU and 4 GB (shared tag) 8G (samba-ci-private tag) RAM.
+#
+
+.shared_runner_build:
+  # We use saas-linux-small-amd64 shared runners by default.
+  # We avoid adding explicit tags for them in order
+  # to work with potential changes in future
+  #
+  # In order to generate valid yaml, we define a dummy variable...
+  variables:
+    SAMBA_SHARED_RUNNER_BUILD_DUMMY_VARIABLE: shared_runner_build
+
+.shared_runner_test:
+  # We use saas-linux-small-amd64 shared runners by default.
+  extends: .shared_runner_build
+
+.private_runner_test:
+  # We use our private runner only for special tests
+  tags:
+    - docker
+    - samba-ci-private

testdata/samba/.gitlab-ci-default.yml

@@ -0,0 +1,10 @@
+variables:
+  SAMBA_CI_FLAVOR: "default"
+  # "--enable-coverage" or ""
+  # See .gitlab-ci-coverage.yml
+  SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE: ""
+  AUTOBUILD_SKIP_SAMBA_O3: "0"
+
+include:
+  - /.gitlab-ci-default-runners.yml
+  - /.gitlab-ci-main.yml

testdata/samba/.gitlab-ci-main.yml

@@ -0,0 +1,688 @@
+# see https://docs.gitlab.com/ce/ci/yaml/README.html for all available options
+
+# Stages explained
+#
+# images: Build the images with the bootstrap script
+# build_first: Build a few things first to find silly errors (fast job)
+#              (don't pay for 35 machines until something compiles)
+# build: The main parallel job
+#              (keep these to 1hour as we are billed per hour)
+# test_only: Tests using the build from prior stages, these typically
+#            have an explicit dependency defined to a specific build job,
+#            which means that start as soon as the build job finished.
+# test_private: Like test_only, but running on private runners
+# report: Code coverage reporting
+
+stages:
+  - images
+  - build_first
+  - build
+  - test_only
+  - test_private
+  - report
+
+variables:
+  # We want to be resilient to runner failures
+  ARTIFACT_DOWNLOAD_ATTEMPTS: "3"
+  EXECUTOR_JOB_SECTION_ATTEMPTS: "3"
+  GET_SOURCES_ATTEMPTS: "3"
+  RESTORE_CACHE_ATTEMPTS: "3"
+  #
+  GIT_STRATEGY: fetch
+  GIT_DEPTH: "3"
+  #
+  # Use GZip by default, it is fast and is good enough.  Other options include --xz
+
+  SAMBA_TESTBASE_TAR_OPTIONS: -z
+
+  #
+  # we run autobuild.py inside a samba CI docker image located on gitlab's registry
+  # overwrite this variable if you want use your own image registry.
+  #
+  # Or better ask for access to the shared development repository, see
+  # https://wiki.samba.org/index.php/Samba_CI_on_gitlab#Getting_Access
+  #
+  SAMBA_CI_CONTAINER_REGISTRY: registry.gitlab.com/samba-team/devel/samba
+  #
+  # Set this to the contents of bootstrap/sha1sum.txt
+  # which is generated by bootstrap/template.py --render
+  #
+  SAMBA_CI_CONTAINER_TAG: e494a8092a6d0e794223f56ddb2ffbaf76402cf6
+  #
+  # We use the ubuntu2204 image as default as
+  # it matches what we have on atb-devel-224
+  #
+  SAMBA_CI_CONTAINER_IMAGE: ubuntu2204
+  #
+  # The following images are available
+  # Please see the samba-o3 sections at the end of this file!
+  # We should run that for each available image
+  #
+  SAMBA_CI_CONTAINER_IMAGE_ubuntu2204: ubuntu2204
+  SAMBA_CI_CONTAINER_IMAGE_ubuntu2404: ubuntu2404
+  SAMBA_CI_CONTAINER_IMAGE_ubuntu2604: ubuntu2604
+  SAMBA_CI_CONTAINER_IMAGE_debian11: debian11
+  SAMBA_CI_CONTAINER_IMAGE_debian11_32bit: debian11-32bit
+  SAMBA_CI_CONTAINER_IMAGE_debian12: debian12
+  SAMBA_CI_CONTAINER_IMAGE_opensuse160: opensuse160
+  SAMBA_CI_CONTAINER_IMAGE_rocky8: rocky8
+  SAMBA_CI_CONTAINER_IMAGE_centos9s: centos9s
+  SAMBA_CI_CONTAINER_IMAGE_fedora43: fedora43
+
+include:
+  # The image creation details are specified in a separate file
+  # See bootstrap/README.md for details
+  - 'bootstrap/.gitlab-ci.yml'
+
+.shared_runner_build_image:
+  extends: .shared_runner_build
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE}
+  image: ${SAMBA_CI_CONTAINER_REGISTRY}/samba-ci-${SAMBA_CI_JOB_IMAGE}:${SAMBA_CI_CONTAINER_TAG}
+
+.shared_template:
+  extends: .shared_runner_build_image
+  # All Samba jobs are interruptible, this avoids burning CPU when a
+  # newer branch is pushed.
+  interruptible: true
+  timeout: 2h
+
+  # Otherwise we run twice, once on push and once on MR
+  # https://forum.gitlab.com/t/new-rules-syntax-and-detached-pipelines/37292
+  rules:
+    - if: $CI_MERGE_REQUEST_ID
+      when: never
+    - when: on_success
+
+  variables:
+    AUTOBUILD_JOB_NAME: $CI_JOB_NAME
+  stage: build
+  cache:
+    key: ccache.${CI_JOB_NAME}.${SAMBA_CI_JOB_IMAGE}.${SAMBA_CI_FLAVOR}
+    paths:
+      - ccache
+
+  # This is overridden in many cases, but ensures none of the other
+  # main jobs start until and unless this build finishes.  However
+  # this also ensures we do not download artifacts from any build
+  # unless we specifically depend on it, saving bandwidth
+
+  needs:
+    - job: samba-def-build
+      artifacts: false
+
+  before_script:
+    - uname -a
+    - ls -l /sys/module/
+    - ls -l /sys/kernel/security/
+    - if [ -e /sys/kernel/security/lsm ]; then cat /sys/kernel/security/lsm ; echo; fi
+    - if [ -e /proc/config.gz ]; then sudo zcat /proc/config.gz; echo; fi
+    - lsb_release -a
+    - cat /etc/os-release
+    - id
+    - cat /proc/self/status
+    - lscpu
+    - cat /proc/cpuinfo
+    - mount
+    - df -h
+    - cat /proc/swaps
+    - free -h
+      # ld will fail if coverage enabled, force link ld to ld.bfd
+    - if [ -n "$SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE" ]; then sudo ln -sf $(which ld.bfd) $(which ld); fi
+      # See bootstrap/.gitlab-ci.yml how to generate a new image
+    - echo "SAMBA_CI_CONTAINER_REGISTRY[${SAMBA_CI_CONTAINER_REGISTRY}]"
+    - echo "SAMBA_CI_CONTAINER_TAG[${SAMBA_CI_CONTAINER_TAG}]"
+    - echo "SAMBA_CI_JOB_IMAGE[${SAMBA_CI_JOB_IMAGE}]"
+    - echo "CI_JOB_IMAGE[${CI_JOB_IMAGE}]"
+    - bootstrap/template.py --sha1sum > /tmp/sha1sum-template.txt
+    - diff -u bootstrap/sha1sum.txt /tmp/sha1sum-template.txt
+    - echo "${SAMBA_CI_CONTAINER_TAG}" > /tmp/sha1sum-tag.txt
+    - diff -u bootstrap/sha1sum.txt /tmp/sha1sum-tag.txt
+    - diff -u bootstrap/sha1sum.txt /sha1sum.txt
+    - echo "${CI_COMMIT_SHA} ${CI_COMMIT_TITLE}" > /tmp/commit.txt
+    - export CCACHE_BASEDIR="${PWD}"
+    - export CCACHE_DIR="${PWD}/ccache" && mkdir -pv "$CCACHE_DIR"
+    - export CC="ccache cc"
+    - export CXX="ccache c++"
+    - ccache -z -M 500M
+    - ccache -s
+      # We are already running .gitlab-ci directives from this repo, remove additional checks that break our CI
+    - git config --global --add safe.directory '*'
+  after_script:
+    - mount
+    - df -h
+    - cat /proc/swaps
+    - free -h
+    - CCACHE_BASEDIR="${PWD}" CCACHE_DIR="${PWD}/ccache" ccache -s -c
+  artifacts:
+    expire_in: 1 week
+    paths:
+      - "*.stdout"
+      - "*.stderr"
+      - "*.info"
+      - public
+      - system-info.txt
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+      - api_failure
+      - runner_unsupported
+      - stale_schedule
+      - archived_failure
+      - scheduler_failure
+      - data_integrity_failure
+
+  script:
+    # gitlab predefines CI_JOB_NAME for each job. The gitlab job usually matches the
+    # autobuild name, which means we can define a default template that runs most autobuild jobs
+    - script/autobuild.py $AUTOBUILD_JOB_NAME $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE  --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase
+
+# Ensure when adding a new job below that you also add it to
+# the dependencies for 'pages' below for the code coverage page
+# generation.
+
+others:
+  extends: .shared_template
+  script:
+    - script/autobuild.py pidl     $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase/pidl
+    - script/autobuild.py replace  $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase/replace
+    - script/autobuild.py talloc   $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase/talloc
+    - script/autobuild.py tdb      $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase/tdb
+    - script/autobuild.py tevent   $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase/tevent
+    - script/autobuild.py samba-xc $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase/samba-xc
+    - script/autobuild.py docs-xml $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase/docs-xml
+    - make -C coverity
+
+.shared_template_build_only:
+  extends: .shared_template
+  timeout: 2h
+  needs:
+  artifacts:
+    expire_in: 1 week
+    paths:
+      - "*.stdout"
+      - "*.stderr"
+      - "*.info"
+      - system-info.txt
+      - samba-testbase.tar
+  script:
+    # gitlab predefines CI_JOB_NAME for each job. The gitlab job usually matches the
+    # autobuild name, which means we can define a default template that runs most autobuild jobs
+    - script/autobuild.py $AUTOBUILD_JOB_NAME $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE  --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase
+    # On success we need to pack everything into an artifacts file
+    # which needs to be in the git checkout.
+    # As tar doesn't handle hardlink of read-only files,
+    # we remember the acls and add write permissions
+    # before creating the archive. The consumer will apply
+    # the acls again.
+    - cp -a /sha1sum.txt /builds/samba-testbase/image-sha1sum.txt
+    - cp -a /tmp/commit.txt /builds/samba-testbase/commit.txt
+    - ln -s /builds/samba-testbase/${AUTOBUILD_JOB_NAME}/ /builds/samba-testbase/build_subdir_link
+    - pushd /builds && getfacl -R samba-testbase > samba-testbase.acl.dump && popd
+    - chmod -R +w /builds/samba-testbase
+    - mv /builds/samba-testbase.acl.dump /builds/samba-testbase/
+    - tar $SAMBA_TESTBASE_TAR_OPTIONS -cf samba-testbase.tar /builds/samba-testbase
+    - ls -la samba-testbase.tar
+    - sha1sum samba-testbase.tar
+
+.shared_template_test_only:
+  extends:
+    - .shared_template
+    - .shared_runner_test
+  stage: test_only
+  script:
+    # Print the Kerberos version to check we ended up with the right one
+    # in the runner. We do not have configure output to recognize it
+    # otherwise.
+    - if [ -x "$(command -v krb5-config)" ]; then krb5-config --version; fi
+    # We unpack the artifacts file created by the .shared_template_build_only
+    # run we depend on
+    - ls -la samba-testbase.tar
+    - sha1sum samba-testbase.tar
+    - tar $SAMBA_TESTBASE_TAR_OPTIONS -xf samba-testbase.tar -C /
+    - diff -u /builds/samba-testbase/image-sha1sum.txt /sha1sum.txt
+    - diff -u /builds/samba-testbase/commit.txt /tmp/commit.txt
+    - mv /builds/samba-testbase/samba-testbase.acl.dump /builds/samba-testbase.acl.dump
+    - pushd /builds && setfacl --restore=/builds/samba-testbase.acl.dump && popd
+    - ls -la /builds/samba-testbase/
+    - ls -la /builds/samba-testbase/build_subdir_link
+    - ls -la /builds/samba-testbase/build_subdir_link/
+    - if [ -n "$SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE" ]; then find /builds/samba-testbase/build_subdir_link/ -type d -printf "'%p'\n" | xargs chmod u+w; fi
+    - ls -la /builds/samba-testbase/build_subdir_link/
+    # gitlab predefines CI_JOB_NAME for each job. The gitlab job usually matches the
+    # autobuild name, which means we can define a default template that runs most autobuild jobs
+    - script/autobuild.py $AUTOBUILD_JOB_NAME $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE --skip-dependencies --verbose --nocleanup --keeplogs --tail --full-testbase /builds/samba-testbase
+
+samba-def-build:
+  extends: .shared_template_build_only
+  stage: build_first
+
+.needs_samba-def-build:
+  extends: .shared_template_test_only
+  needs:
+    - job: samba-def-build
+      artifacts: true
+    - job: samba-codecheck
+
+samba-mit-build:
+  extends: .shared_template_build_only
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_fedora43}
+  stage: build_first
+
+.needs_samba-mit-build:
+  extends: .shared_template_test_only
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_fedora43}
+  needs:
+    - job: samba-mit-build
+      artifacts: true
+    - job: samba-codecheck
+
+samba-h5l-build:
+  extends: .shared_template_build_only
+
+.needs_samba-h5l-build:
+  extends: .shared_template_test_only
+  needs:
+    - job: samba-h5l-build
+      artifacts: true
+
+samba-without-smb1-build:
+  extends: .shared_template_build_only
+
+.needs_samba-without-smb1-build:
+  extends: .shared_template_test_only
+  needs:
+    - job: samba-without-smb1-build
+      artifacts: true
+
+samba-nt4-build:
+  extends: .shared_template_build_only
+
+.needs_samba-nt4-build:
+  extends: .shared_template_test_only
+  needs:
+    - job: samba-nt4-build
+      artifacts: true
+
+samba-no-opath-build:
+  extends: .shared_template_build_only
+
+.needs_samba-no-opath-build:
+  extends: .shared_template_test_only
+  needs:
+    - job: samba-no-opath-build
+      artifacts: true
+
+samba:
+  extends: .shared_template
+
+samba-mitkrb5:
+  extends: .shared_template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_fedora43}
+
+samba-minimal-smbd:
+  extends: .shared_template
+
+samba-nopython:
+  extends: .shared_template
+
+samba-admem:
+  extends: .needs_samba-def-build
+
+samba-ad-dc-2:
+  extends: .needs_samba-def-build
+
+samba-ad-dc-3:
+  extends: .needs_samba-def-build
+
+samba-ad-dc-4a:
+  extends: .needs_samba-def-build
+
+samba-ad-dc-4b:
+  extends: .needs_samba-def-build
+
+samba-ad-dc-5:
+  extends: .needs_samba-def-build
+
+samba-ad-dc-6:
+  extends: .needs_samba-def-build
+
+samba-ad-back1:
+  extends: .needs_samba-def-build
+
+samba-ad-back2:
+  extends: .needs_samba-def-build
+
+samba-schemaupgrade:
+  extends: .needs_samba-def-build
+
+samba-libs:
+  extends: .shared_template
+
+samba-fuzz:
+  extends: .shared_template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_ubuntu2404}
+
+ctdb:
+  extends: .shared_template
+
+samba-ctdb:
+  extends: .shared_template
+
+samba-ad-dc-ntvfs:
+  extends: .needs_samba-def-build
+
+samba-admem-mit:
+  extends: .needs_samba-mit-build
+
+samba-addc-mit-4a:
+  extends: .needs_samba-mit-build
+
+samba-addc-mit-4b:
+  extends: .needs_samba-mit-build
+
+# This task is run first to ensure we compile before we start the
+# main run as it is the fastest full compile of Samba.
+samba-fips:
+  extends: .shared_template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_fedora43}
+
+samba-codecheck:
+  extends: .shared_template
+  needs:
+  stage: build_first
+
+.private_test_only:
+  extends: .private_runner_test
+  stage: test_private
+  rules:
+      # See above, to avoid a duplicate CI on the MR (these rules override the others)
+    - if: $CI_MERGE_REQUEST_ID
+      when: never
+
+      # These jobs are only run if the gitlab repo has private runners available.
+      # To enable private jobs, you must add the following var and value to
+      # your gitlab repo by navigating to:
+      # settings -> CI/CD -> Environment variables
+    - if: $SUPPORT_PRIVATE_TEST == "yes"
+
+.needs_ext4_support:
+  # All runners provide an ext4 filesystem
+  #
+  # Note: we don't use
+  # extends: .shared_template_test_only
+  # as that somehow resets the needs section
+  # and generates problems for something
+  # like this (which is used below)
+  #
+  # .needs_samba-SOME-build-ext4:
+  #   extends:
+  #     - .needs_samba-SOME-build
+  #     - .needs_ext4_support
+  #
+  # So we only set stage again instead...
+  stage: test_only
+
+.needs_5_15_kernel:
+  # Our private runners are based on
+  # ubuntu2204 with a 5.15 kernel.
+  #
+  # And they also provide an ext4 filesystem
+  extends: .private_test_only
+
+.needs_samba-def-build-ext4:
+  extends:
+    - .needs_samba-def-build
+    - .needs_ext4_support
+
+.needs_samba-mit-build-ext4:
+  extends:
+    - .needs_samba-mit-build
+    - .needs_ext4_support
+
+.needs_samba-h5l-build-ext4:
+  extends:
+    - .needs_samba-h5l-build
+    - .needs_ext4_support
+
+.needs_samba-without-smb1-build-5_15:
+  # Currently this doesn't strictly
+  # require a kernel >= 5.15, but only
+  # ext4 support.
+  #
+  # But we want to make sure that
+  # our private runners keep working
+  # and at least do a single job.
+  #
+  # In future we'll be able to run
+  # tests with io_uring in this
+  # setup, which will requires a
+  # 5.15 kernel in order to be useful.
+  extends:
+    - .needs_samba-without-smb1-build
+    - .needs_5_15_kernel
+
+.needs_samba-nt4-build-ext4:
+  extends:
+    - .needs_samba-nt4-build
+    - .needs_ext4_support
+
+.needs_samba-no-opath-build-ext4:
+  extends:
+    - .needs_samba-no-opath-build
+    - .needs_ext4_support
+
+samba-fileserver:
+  extends: .needs_samba-h5l-build-ext4
+
+samba-fileserver-without-smb1:
+  extends: .needs_samba-without-smb1-build
+
+# This is a full build without the AD DC so we test the build with MIT
+# Kerberos from the default system (Ubuntu 22.04 at this stage).
+# Runtime behaviour checked via the ktest (static ccache and keytab)
+# environment
+samba-ktest-mit:
+ extends: .shared_template
+
+samba-ad-dc-1:
+  extends: .needs_samba-def-build-ext4
+
+samba-nt4:
+  extends: .needs_samba-nt4-build-ext4
+
+samba-addc-mit-1:
+  extends: .needs_samba-mit-build-ext4
+
+samba-no-opath1:
+  extends: .needs_samba-no-opath-build-ext4
+
+samba-no-opath2:
+  extends: .needs_samba-no-opath-build-ext4
+
+# 'pages' is a special job which can publish artifacts in `public` dir to gitlab pages
+pages:
+  extends: .shared_runner_build_image
+  stage: report
+  dependencies:  # tell gitlab to download artifacts for these jobs
+    - others
+    - samba
+    - samba-mitkrb5
+    - samba-admem
+    - samba-ad-dc-2
+    - samba-ad-dc-3
+    - samba-ad-dc-4a
+    - samba-ad-dc-4b
+    - samba-ad-dc-5
+    - samba-ad-dc-6
+    - samba-libs
+    - samba-minimal-smbd
+    - samba-nopython
+    - samba-fuzz
+    # - ctdb  # TODO
+    - samba-ctdb
+    - samba-ad-dc-ntvfs
+    - samba-admem-mit
+    - samba-addc-mit-4a
+    - samba-addc-mit-4b
+    - samba-ad-back1
+    - samba-ad-back2
+    - samba-fileserver
+    - samba-fileserver-without-smb1
+    - samba-ad-dc-1
+    - samba-nt4
+    - samba-schemaupgrade
+    - samba-addc-mit-1
+    - samba-fips
+    - samba-no-opath1
+    - samba-no-opath2
+    - ubuntu2204-samba-o3
+  script:
+    - ls -la *.info
+    - ./configure.developer
+    - make -j
+    - ls -la *.info
+    - lcov $(ls *.info | xargs -I{} echo -n "-a {} ") -o all.info
+    - ls -la *.info
+    - genhtml all.info --ignore-errors source --output-directory public --prefix=$(pwd) --title "coverage report for $CI_COMMIT_REF_NAME $CI_COMMIT_SHORT_SHA"
+  artifacts:
+    expire_in: 30 days
+    paths:
+      - public
+  only:
+    variables:
+      - $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE == "--enable-coverage"
+
+# Coverity Scan
+coverity:
+  extends: .shared_runner_build_image
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_opensuse160}
+  stage: build
+  script:
+    - wget https://scan.coverity.com/download/linux64 --post-data "token=$COVERITY_SCAN_TOKEN&project=$COVERITY_SCAN_PROJECT_NAME" -O /tmp/coverity_tool.tgz
+    - tar xf /tmp/coverity_tool.tgz
+    - ./configure.developer --with-cluster-support
+    - cov-analysis-linux64-*/bin/coverity capture --dir cov-int --project-dir ./
+    - tar czf cov-int.tar.gz cov-int
+    - curl
+      --form token=$COVERITY_SCAN_TOKEN
+      --form email=$COVERITY_SCAN_EMAIL
+      --form file=@cov-int.tar.gz
+      --form version="`git describe --tags`"
+      --form description="CI build"
+      https://scan.coverity.com/builds?project=$COVERITY_SCAN_PROJECT_NAME
+  only:
+    refs:
+      - master
+      - schedules
+    variables:
+      - $COVERITY_SCAN_TOKEN != null
+      - $COVERITY_SCAN_PROJECT_NAME != null
+      - $COVERITY_SCAN_EMAIL != null
+  artifacts:
+    expire_in: 1 week
+    when: on_failure
+    paths:
+      - cov-int/*.txt
+
+debian11-samba-32bit:
+  extends: .shared_template
+  variables:
+    AUTOBUILD_JOB_NAME: samba-32bit
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_debian11_32bit}
+
+#
+# We build samba-o3 on all supported distributions
+#
+
+# This job, which matches the main CI, needs to still do coverage so
+# we show the coverage on the "none" environment tests
+#
+# We want --enable-coverage specified here otherwise we will have a
+# different set of build options on the coverage build and can fail
+# when -O3 gets combined with --enable-coverage in the scheduled
+# builds.
+
+ubuntu2204-samba-o3:
+  extends: .shared_template
+  variables:
+    AUTOBUILD_JOB_NAME: samba-o3
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_ubuntu2204}
+    SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE: "--enable-coverage"
+  rules:
+    # See above, to avoid a duplicate CI on the MR (these rules override the others)
+    - if: $CI_MERGE_REQUEST_ID
+      when: never
+    # do not run o3 builds (which run a lot of VMs) if told not to
+    # (this uses the same variable as autobuild.py)
+    - if: $AUTOBUILD_SKIP_SAMBA_O3 == "1"
+      when: never
+    - when: on_success
+
+# All other jobs do not want code coverage.
+.samba-o3-template:
+  extends: .shared_template
+  variables:
+    AUTOBUILD_JOB_NAME: samba-o3
+  rules:
+    # See above, to avoid a duplicate CI on the MR (these rules override the others)
+    - if: $CI_MERGE_REQUEST_ID
+      when: never
+    # do not run o3 builds (which run a lot of VMs) if told not to
+    # (this uses the same variable as autobuild.py)
+    - if: $AUTOBUILD_SKIP_SAMBA_O3 == "1"
+      when: never
+    # do not run o3 for coverage since they are using different images
+    - if: $SAMBA_CI_AUTOBUILD_ENABLE_COVERAGE == ""
+
+ubuntu2404-samba-o3:
+  extends: .samba-o3-template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_ubuntu2404}
+
+ubuntu2604-samba-o3:
+  extends: .samba-o3-template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_ubuntu2604}
+
+debian11-samba-o3:
+  extends: .samba-o3-template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_debian11}
+
+debian12-samba-o3:
+  extends: .samba-o3-template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_debian12}
+
+opensuse160-samba-o3:
+  extends: .samba-o3-template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_opensuse160}
+
+rocky8-samba-o3:
+  extends: .samba-o3-template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_rocky8}
+
+centos9s-samba-o3:
+  extends: .samba-o3-template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_centos9s}
+
+fedora43-samba-o3:
+  extends: .samba-o3-template
+  variables:
+    SAMBA_CI_JOB_IMAGE: ${SAMBA_CI_CONTAINER_IMAGE_fedora43}
+
+#
+# Keep the samba-o3 sections at the end ...
+#

testdata/samba/.gitlab-ci-private.yml

@@ -0,0 +1,5 @@
+# This is just a legacy alias used by the
+# https://gitlab.com/samba-team/devel/samba configuration
+#
+include:
+  - '/.gitlab-ci.yml'

testdata/samba/.gitlab-ci.yml

@@ -0,0 +1,2 @@
+include:
+  - /.gitlab-ci-default.yml

testdata/samba/.gitleaks.toml

@@ -0,0 +1,16 @@
+#
+# GitLeaks Repo Specific Configuration
+#
+# This allowlist is used to help Red Hat ignore false positives during its code
+# scans.
+
+[allowlist]
+  paths = [
+    '''docs-xml/manpages/smbstatus.1.xml''',
+    '''selftests/*''',
+    '''source3/script/tests/*''',
+    '''source4/dsdb/tests/*''',
+    '''source4/torture/*''',
+    '''testprogs/blackbox/*''',
+    '''tests/*''',
+  ]

testdata/samba/bootstrap/.gitlab-ci.yml

@@ -0,0 +1,122 @@
+---
+.build_image_template:
+  image: quay.io/podman/stable:latest
+  stage: images
+  tags:
+    # We need to make sure we only use gitlab.com
+    # runners and not our own runners, as our current runners
+    # don't allow 'docker build ...' to run.
+    - saas-linux-small-amd64
+  variables:
+    SAMBA_CI_IS_BROKEN_IMAGE: "no"
+    SAMBA_CI_TEST_JOB: "samba-o3"
+    SAMBA_CI_PLATFORM: "linux/amd64"
+  before_script:
+    # install prerequisites
+    - dnf install -qy diffutils
+    # Ensure we are generating correct the container
+    - uname -a
+    - cat /etc/os-release
+    - echo "SAMBA_CI_CONTAINER_REGISTRY[${SAMBA_CI_CONTAINER_REGISTRY}]"
+    - echo "SAMBA_CI_CONTAINER_TAG[${SAMBA_CI_CONTAINER_TAG}]"
+    - echo "SAMBA_CI_IS_BROKEN_IMAGE[${SAMBA_CI_IS_BROKEN_IMAGE}]"
+    - echo "SAMBA_CI_REBUILD_IMAGES[${SAMBA_CI_REBUILD_IMAGES}]"
+    - echo "SAMBA_CI_REBUILD_BROKEN_IMAGES[${SAMBA_CI_REBUILD_BROKEN_IMAGES}]"
+    - echo "GITLAB_USER_LOGIN[${GITLAB_USER_LOGIN}]"
+    - echo "${SAMBA_CI_CONTAINER_TAG}" > /tmp/sha1sum-tag.txt
+    - diff -u bootstrap/sha1sum.txt /tmp/sha1sum-tag.txt
+  script: |
+    set -xueo pipefail
+    ci_image_name=samba-ci-${CI_JOB_NAME}
+    podman build --platform ${SAMBA_CI_PLATFORM} --tag ${ci_image_name} --build-arg SHA1SUM=${SAMBA_CI_CONTAINER_TAG} bootstrap/generated-dists/${CI_JOB_NAME}
+    ci_image_path="${SAMBA_CI_CONTAINER_REGISTRY}/${ci_image_name}"
+    timestamp=$(date +%Y%m%d%H%M%S)
+    container_hash=$(podman image inspect --format='{{ .Id }}' ${ci_image_name} | cut -c 1-9)
+    timestamp_tag=${SAMBA_CI_CONTAINER_TAG}-${timestamp}-${GITLAB_USER_LOGIN}-${container_hash}
+    samba_repo_root=/home/samba/samba
+    # Ensure we are generating the correct container that we expect to be in
+    echo "${SAMBA_CI_CONTAINER_TAG}" > /tmp/sha1sum-tag.txt
+    diff -u bootstrap/sha1sum.txt /tmp/sha1sum-tag.txt
+    podman run --volume $(pwd):${samba_repo_root} --workdir ${samba_repo_root} ${ci_image_name} \
+        /bin/bash -c "echo \"${SAMBA_CI_CONTAINER_TAG}\" > /tmp/sha1sum-tag.txt; diff -u bootstrap/sha1sum.txt /tmp/sha1sum-tag.txt"
+    podman run --volume $(pwd):${samba_repo_root} --workdir ${samba_repo_root} ${ci_image_name} \
+        diff -u bootstrap/sha1sum.txt /sha1sum.txt
+    podman run --volume $(pwd):${samba_repo_root} --workdir ${samba_repo_root} ${ci_image_name} \
+        bootstrap/template.py --sha1sum > /tmp/sha1sum-template.txt
+    diff -u bootstrap/sha1sum.txt /tmp/sha1sum-template.txt
+    # run smoke test with samba-o3 or samba-fuzz
+    podman run --volume $(pwd):/src:ro ${ci_image_name} \
+        /bin/bash -c "git config --global --add safe.directory /src/.git && git clone /src samba && cd samba && export PKG_CONFIG_PATH=/usr/lib64/compat-gnutls34/pkgconfig:/usr/lib64/compat-nettle32/pkgconfig && script/autobuild.py ${SAMBA_CI_TEST_JOB} --verbose --nocleanup --keeplogs --tail --testbase /tmp/samba-testbase"
+    podman tag ${ci_image_name} ${ci_image_path}:${SAMBA_CI_CONTAINER_TAG}
+    podman tag ${ci_image_name} ${ci_image_path}:${timestamp_tag}
+    # We build all images, but only upload is it's not marked as broken
+    test x"${SAMBA_CI_IS_BROKEN_IMAGE}" = x"yes" || { \
+        podman login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY; \
+        podman push ${ci_image_path}:${SAMBA_CI_CONTAINER_TAG}; \
+        podman push ${ci_image_path}:${timestamp_tag}; \
+    }
+    echo "Success for ${ci_image_path}:${timestamp_tag}"
+    test x"${SAMBA_CI_IS_BROKEN_IMAGE}" = x"no" || { \
+         echo "The image ${CI_JOB_NAME} is marked as broken and should have failed!"; \
+         echo "Replace .build_image_template_force_broken with .build_image_template!"; \
+         echo "Add a .samba-o3-template section at the end of the main .gitlab-ci.yml!"; \
+         /bin/false; \
+    }
+  only:
+    variables:
+      #
+      # You need a custom pipeline which passes
+      # SAMBA_CI_REBUILD_IMAGES="yes".
+      #
+      # https://gitlab.com/samba-team/devel/samba/pipelines/new
+      #
+      - $SAMBA_CI_REBUILD_IMAGES == "yes"
+
+.build_image_template_force_broken:
+  extends: .build_image_template
+  variables:
+    SAMBA_CI_IS_BROKEN_IMAGE: "yes"
+  only:
+    variables:
+      #
+      # You need a custom pipeline which passes
+      # SAMBA_CI_REBUILD_BROKEN_IMAGES="yes"
+      # in order to build broken images for debugging
+      #
+      # https://gitlab.com/samba-team/devel/samba/pipelines/new
+      #
+      - $SAMBA_CI_REBUILD_BROKEN_IMAGES == "yes"
+
+ubuntu2204:
+  extends: .build_image_template
+
+ubuntu2404:
+  extends: .build_image_template
+
+ubuntu2604:
+  extends: .build_image_template
+
+debian11:
+  extends: .build_image_template
+
+debian12:
+  extends: .build_image_template
+
+fedora43:
+  extends: .build_image_template
+
+debian11-32bit:
+  extends: .build_image_template
+  variables:
+    SAMBA_CI_TEST_JOB: "samba-32bit"
+    SAMBA_CI_PLATFORM: "linux/i386"
+
+rocky8:
+  extends: .build_image_template
+
+centos9s:
+  extends: .build_image_template
+
+opensuse160:
+  extends: .build_image_template
+

testdata/script_multiline.yml

@@ -0,0 +1,87 @@
+---
+# Exercises multi-line script patterns and extended variable declarations.
+# Ref: https://docs.gitlab.com/ci/yaml/script/#split-long-commands
+# Ref: https://docs.gitlab.com/ee/ci/yaml/#variablesdescription
+# All patterns here must parse cleanly (exit 0).
+
+stages:
+  - build
+  - test
+  - deploy
+
+# Pipeline-level variables: plain strings and extended {value, description} map form.
+variables:
+  PLAIN_VAR: "hello"
+  DEPLOY_ENV:
+    value: "staging"
+    description: "The deployment target. Set to staging or production."
+  RETRIES:
+    value: "3"
+    description: "Number of retry attempts."
+    options:
+      - "1"
+      - "3"
+      - "5"
+
+default:
+  # image in map form (name + pull_policy)
+  image:
+    name: alpine:latest
+    pull_policy: if-not-present
+  # before_script as a block scalar (not a list)
+  before_script:
+    - apk add --no-cache curl git
+
+build-literal-block:
+  stage: build
+  # script items using literal block scalar (|)
+  script:
+    - |
+      if [[ "$DEPLOY_ENV" == "production" ]]; then
+        echo "Production build"
+      else
+        echo "Non-production build"
+      fi
+    - echo "Build step done"
+
+build-folded-block:
+  stage: build
+  # script items using folded block scalar (>)
+  script:
+    - >
+      apt-get update -qq &&
+      apt-get install -y curl wget
+    - echo "Packages installed"
+  before_script:
+    - |
+      echo "Job-level before_script"
+      echo "Using literal block scalar"
+
+test-job:
+  stage: test
+  script:
+    - echo "Running tests"
+    - |
+      set -e
+      go test ./...
+      echo "Tests passed"
+  # Job-level variable with extended form
+  variables:
+    TEST_FLAG:
+      value: "true"
+      description: "Enable verbose test output"
+  # rules.changes in map form (GitLab 15.3+)
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        paths:
+          - "**/*.go"
+        compare_to: "main"
+      when: on_success
+    - when: on_success
+
+deploy-job:
+  stage: deploy
+  script:
+    - echo "Deploying to $DEPLOY_ENV"
+  when: manual

testdata/variable_refs.yml

@@ -0,0 +1,51 @@
+---
+# variable_refs.yml
+# Verifies that GL032 does not fire for variables that are declared or predefined.
+# Covers: pipeline variables:, job variables:, workflow:rules:variables:, and CI_* prefixes.
+# Expected: exits 0 (no errors; no GL032 warnings).
+
+stages:
+  - build
+  - deploy
+
+variables:
+  DEPLOY_TARGET: "staging"
+  FEATURE_FLAG: "false"
+
+workflow:
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      variables:
+        DEPLOY_TARGET: "production"
+    - when: always
+
+build:
+  stage: build
+  script: make build
+  rules:
+    # pipeline-level variable — GL032 must not fire
+    - if: '$DEPLOY_TARGET == "staging"'
+      when: on_success
+    # predefined CI variable — GL032 must not fire
+    - if: '$CI_COMMIT_BRANCH =~ /^feat\/.+/'
+      when: manual
+
+deploy:
+  stage: deploy
+  script: make deploy
+  variables:
+    DEPLOY_REGION: "us-east-1"
+  rules:
+    # pipeline-level variable — no warning
+    - if: '$FEATURE_FLAG == "true"'
+      when: never
+    # workflow-rule-injected variable — no warning
+    - if: '$DEPLOY_TARGET == "production"'
+      when: on_success
+    # job-level variable — no warning
+    - if: '$DEPLOY_REGION == "us-east-1"'
+      when: on_success
+    # predefined GITLAB_ variable — no warning
+    - if: '$GITLAB_USER_LOGIN == "bot"'
+      when: never
+    - when: manual

testdata/variable_refs_included.yml

@@ -0,0 +1,25 @@
+---
+# variable_refs_included.yml
+# GL032 must NOT fire for variables declared in an included file.
+# The included file (variable_refs_included_template.yml) declares TEMPLATE_VAR.
+# Expected: exits 0 (no errors; no GL032 warnings).
+
+stages:
+  - build
+
+include:
+  - local: /variable_refs_included_template.yml
+
+build:
+  stage: build
+  script: make build
+  rules:
+    # TEMPLATE_VAR comes from the included file — GL032 must not fire.
+    - if: '$TEMPLATE_VAR == "enabled"'
+      when: on_success
+    # ROOT_VAR is declared in this file — GL032 must not fire.
+    - if: '$ROOT_VAR == "yes"'
+      when: manual
+
+variables:
+  ROOT_VAR: "yes"

testdata/variable_refs_included_template.yml

@@ -0,0 +1,6 @@
+---
+# Included by variable_refs_included.yml — declares a pipeline-level variable
+# that the parent pipeline's jobs reference in rules:if: expressions.
+
+variables:
+  TEMPLATE_VAR: "enabled"

testdata/workflow_escape.yml

@@ -0,0 +1,57 @@
+---
+# workflow_vars.yml
+# Exercises workflow:rules:variables: injection.
+# The matching workflow rule sets DEPLOY_TARGET; job rules use it.
+#
+# Expected behaviour per context:
+#   (no context)       → all jobs active (no context evaluation)
+#   --branch main      → deploy-prod active, deploy-staging skipped
+#   --branch develop   → deploy-prod skipped, deploy-staging active
+#   --branch feat/x    → deploy-prod skipped, deploy-staging skipped (manual)
+
+stages:
+  - build
+  - deploy
+
+variables:
+  DEPLOY_TARGET:
+    value: ""
+    description: "Deployment target — set by workflow rules"
+
+workflow:
+  rules:
+    - if: "
+        $WORKFLOW = 'gitflow' &&
+        $CI_PIPELINE_SOURCE == /(push|web)/ && 
+        $CI_COMMIT_BRANCH =~ /^us\//
+        "
+      variables:
+        DEPLOY_TARGET: production
+        BUILD: true
+        TEST: true        
+    - if: '$CI_COMMIT_BRANCH == "develop"'
+      variables:
+        DEPLOY_TARGET: staging
+    - when: always
+
+build:
+  stage: build
+  script: make build
+  rules:
+    - when: always
+
+deploy-prod:
+  stage: deploy
+  script: make deploy ENV=production
+  rules:
+    - if: '$DEPLOY_TARGET == "production"'
+      when: on_success
+    - when: never
+
+deploy-staging:
+  stage: deploy
+  script: make deploy ENV=staging
+  rules:
+    - if: '$DEPLOY_TARGET == "staging"'
+      when: on_success
+    - when: never

testdata/workflow_vars.yml

@@ -0,0 +1,57 @@
+---
+# workflow_vars.yml
+# Exercises workflow:rules:variables: injection.
+# The matching workflow rule sets DEPLOY_TARGET; job rules use it.
+#
+# Expected behaviour per context:
+#   --branch main             → only build active (no workflow rule matches; WORKFLOW var not set)
+#   --branch develop          → deploy-staging active, deploy-prod skipped
+#   --branch feat/x           → only build active (when: always fallback, no deploy vars)
+#   --var WORKFLOW=gitflow --branch us/feature → deploy-prod + build active
+
+stages:
+  - build
+  - deploy
+
+variables:
+  DEPLOY_TARGET:
+    value: ""
+    description: "Deployment target — set by workflow rules"
+
+workflow:
+  rules:
+    - if: "
+        $WORKFLOW = 'gitflow' &&
+        $CI_PIPELINE_SOURCE == /(push|web)/ && 
+        $CI_COMMIT_BRANCH =~ /^us\//
+        "
+      variables:
+        DEPLOY_TARGET: production
+        DEPLOY: true
+        BUILD: true
+    - if: '$CI_COMMIT_BRANCH == "develop"'
+      variables:
+        DEPLOY_TARGET: staging
+    - when: always
+
+build:
+  stage: build
+  script: make build
+  rules:
+    - when: always
+
+deploy-prod:
+  stage: deploy
+  script: make deploy ENV=production
+  rules:
+    - if: '$DEPLOY_TARGET == "production" && $DEPLOY == "true"'
+      when: on_success
+    - when: never
+
+deploy-staging:
+  stage: deploy
+  script: make deploy ENV=staging
+  rules:
+    - if: '$DEPLOY_TARGET == "staging" '
+      when: on_success
+    - when: never