glint/README.md

glint

Disclaimer: This tool was built through iterative AI-assisted development with Claude. 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.

A local tool to validate and lint .gitlab-ci.yml pipelines without needing a GitLab server.

What it does

• Lints — 43 rules covering pipeline structure, keyword constraints, needs:/dependencies: graphs, expression reachability, and deprecations (GL001–GL043); run glint explain <ID> for any rule
• Resolves includes — local files, HTTPS URLs, GitLab project templates, and CI/CD Catalog components, with offline cache support
• Simulates context — --branch, --tag, --source flags evaluate rules:if: and only/except to show which jobs would be active, manual, or skipped; --context branch=main --context branch=develop prints a multi-column comparison table across multiple contexts in one run
• Multiple output formats — --format text (default, ruff-style), json, sarif (GitHub Code Scanning / GitLab SAST), junit, github (PR annotations)
• Project config — .glint.yml for rule suppression, severity overrides, token/URL defaults; # glint: ignore RULE for per-job inline suppression
• Graph visualization — glint graph prints a terminal job tree; glint graph pipeline renders a GitLab CI-style SVG/PNG; --format mermaid emits a Mermaid flowchart; --format html produces a self-contained HTML file with pan/zoom and a job-detail sidebar; context flags grey out skipped jobs

See FEATURES.md for the complete feature reference and lint rules table, and ROADMAP.md for planned improvements.

Requirements

• Go 1.21 or later
• Task (optional, for development tasks)

Installation

git clone https://git.k3nny.fr/glint
cd glint
go build -o glint ./cmd/glint/...

Or with Task:

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
  explain  Print description and fix for a lint rule

Run glint <command> --help for all flags. See USAGE.md for full examples covering output formats, context simulation, remote includes, cache, graph modes, and project configuration.

Development

This project uses Task as a task runner.

task              # list available tasks
task build        # compile the binary
task test         # run Go unit tests
task lint-go      # run go vet
task validate     # run the binary against all testdata fixtures
task ci           # full check: vet → test → build → validate
task fuzz         # run fuzz tests for the YAML parser (Ctrl-C to stop; FUZZ_TIME=60s to set duration)
task changelog    # regenerate CHANGELOG.md from git history via git-cliff
task changelog-next  # preview unreleased section (dry-run, no file written)
task build-windows  # cross-compile for Windows x64 (requires a tagged commit → glint-<tag>.exe)
task build-linux    # cross-compile for Linux x64 (requires a tagged commit → glint-<tag>-linux-amd64)
task clean        # remove build artifacts

Optional tools:

• git-cliff — changelog generator used by task changelog. Install with brew install git-cliff or cargo install git-cliff.

Project structure

.
├── cmd/glint/     # CLI entrypoint
├── internal/
│   ├── cicontext/      # CI variable context, rules:if: evaluator, job reachability
│   ├── fetcher/        # GitLab API client (project include fetching)
│   ├── graph/          # Mermaid and SVG/PNG graph generators
│   ├── linter/         # lint rules and findings
│   ├── model/          # pipeline data structures and YAML parser
│   └── resolver/       # extends: resolution and project include merging
├── testdata/           # sample pipelines used for manual validation
├── Taskfile.yml
└── go.mod