docs(docs): update CHANGELOG, README, ROADMAP, Formula, and INSTALL for v0.4.0

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

CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [0.4.0] - 2026-06-26
+
+### Added
+
+- **Git branch auto-detection** — `glint check` and `glint graph` now run `git rev-parse --abbrev-ref HEAD` in the pipeline file's directory to determine the current branch when no `--branch`/`--tag`/`--source`/`--var` flags are given. Falls back to `main` when not inside a git repository or in detached-HEAD state (e.g. CI runners).
+
+- **GitLab predefined variable injection** — two categories of predefined variables are now present in the simulation context automatically:
+  - `CI=true` and `GITLAB_CI=true` are injected for every non-empty context, so expressions like `$CI == "true"` evaluate correctly without `--var`.
+  - MR-specific variables (`CI_MERGE_REQUEST_IID`, `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`, `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`, and four others) are injected as placeholders when `--source merge_request_event` is given. `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` is derived from `--branch` when provided. All injected defaults can be overridden with `--var`.
+
+- **Multi-platform release binaries** — `task build-release` now builds for all five platforms at once: Linux amd64, Linux arm64, macOS Intel, macOS Apple Silicon, Windows x86-64. Individual targets: `task build-linux-amd64`, `task build-linux-arm64`, `task build-darwin-amd64`, `task build-darwin-arm64`, `task build-windows`.
+
+- **Homebrew formula** — `Formula/glint.rb` is a source-build Homebrew formula. Set up a tap at `k3nny/homebrew-glint` on GitHub, then install with `brew tap k3nny/glint https://github.com/k3nny/homebrew-glint && brew install glint`.
+
+- **`INSTALL.md`** — installation guide covering pre-built binary download for all platforms, Homebrew tap, `go install`, and build-from-source with `/usr/local/bin` placement.
+
 ## [0.3.1] - 2026-06-26
 
 ### Changed

Formula/glint.rb

@@ -0,0 +1,29 @@
+class Glint < Formula
+  desc "Local linter and validator for .gitlab-ci.yml pipelines"
+  homepage "https://git.k3nny.fr/k3nny/glint"
+  url "https://git.k3nny.fr/k3nny/glint/archive/v0.4.0.tar.gz"
+  # Update sha256 on each release: sha256sum glint-vX.Y.Z.tar.gz
+  sha256 ""
+  license "Apache-2.0"
+  head "https://git.k3nny.fr/k3nny/glint.git", branch: "main"
+
+  depends_on "go" => :build
+
+  def install
+    system "go", "build",
+           "-ldflags", "-X main.version=#{version}",
+           "-o", bin/"glint",
+           "./cmd/glint/..."
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/glint --version")
+    (testpath/".gitlab-ci.yml").write <<~YAML
+      stages: [build]
+      build-job:
+        stage: build
+        script: echo ok
+    YAML
+    system bin/"glint", "check", ".gitlab-ci.yml"
+  end
+end

INSTALL.md

@@ -0,0 +1,139 @@
+# Installing glint
+
+## Requirements
+
+- Go 1.21 or later (for building from source)
+- Any 64-bit Linux, macOS, or Windows system (for pre-built binaries)
+
+---
+
+## Option 1 — Build from source
+
+```bash
+git clone https://git.k3nny.fr/k3nny/glint
+cd glint
+go build -o glint ./cmd/glint/...
+sudo mv glint /usr/local/bin/
+```
+
+Or with [Task](https://taskfile.dev):
+
+```bash
+task build
+sudo mv glint /usr/local/bin/
+```
+
+---
+
+## Option 2 — Download a pre-built binary
+
+Pre-built binaries are attached to each [release](https://git.k3nny.fr/k3nny/glint/releases).
+
+| Platform | File |
+|----------|------|
+| Linux x86-64 | `glint-vX.Y.Z-linux-amd64` |
+| Linux ARM64 | `glint-vX.Y.Z-linux-arm64` |
+| macOS Intel | `glint-vX.Y.Z-darwin-amd64` |
+| macOS Apple Silicon | `glint-vX.Y.Z-darwin-arm64` |
+| Windows x86-64 | `glint-vX.Y.Z-windows-amd64.exe` |
+
+### Linux (amd64)
+
+```bash
+VERSION=v0.4.0
+curl -Lo glint https://git.k3nny.fr/k3nny/glint/releases/download/${VERSION}/glint-${VERSION}-linux-amd64
+chmod +x glint
+sudo mv glint /usr/local/bin/
+```
+
+### Linux (ARM64 — Raspberry Pi 4, AWS Graviton, …)
+
+```bash
+VERSION=v0.4.0
+curl -Lo glint https://git.k3nny.fr/k3nny/glint/releases/download/${VERSION}/glint-${VERSION}-linux-arm64
+chmod +x glint
+sudo mv glint /usr/local/bin/
+```
+
+### macOS (Apple Silicon — M1/M2/M3)
+
+```bash
+VERSION=v0.4.0
+curl -Lo glint https://git.k3nny.fr/k3nny/glint/releases/download/${VERSION}/glint-${VERSION}-darwin-arm64
+chmod +x glint
+sudo mv glint /usr/local/bin/
+```
+
+### macOS (Intel)
+
+```bash
+VERSION=v0.4.0
+curl -Lo glint https://git.k3nny.fr/k3nny/glint/releases/download/${VERSION}/glint-${VERSION}-darwin-amd64
+chmod +x glint
+sudo mv glint /usr/local/bin/
+```
+
+### Verify the installation
+
+```bash
+glint --version
+```
+
+---
+
+## Option 3 — Homebrew (macOS and Linux)
+
+A Homebrew tap is available at `k3nny/glint`.
+
+> **First-time setup:** create a GitHub repository named `homebrew-glint`
+> under your account and copy [`Formula/glint.rb`](Formula/glint.rb) into it.
+> Users then install via the tap as shown below.
+
+```bash
+brew tap k3nny/glint https://github.com/k3nny/homebrew-glint
+brew install glint
+```
+
+To upgrade:
+
+```bash
+brew upgrade glint
+```
+
+The formula builds glint from source using Go, which Homebrew provides
+automatically as a build dependency. No pre-built binary download is needed.
+
+### Updating the formula on a new release
+
+After tagging a new release, update `Formula/glint.rb`:
+
+1. Compute the tarball checksum:
+   ```bash
+   curl -sL https://git.k3nny.fr/k3nny/glint/archive/vX.Y.Z.tar.gz | sha256sum
+   ```
+2. Update `url` and `sha256` in the formula.
+3. Commit and push to `homebrew-glint`.
+
+---
+
+## Option 4 — Go install
+
+If you already have Go 1.21+:
+
+```bash
+go install git.k3nny.fr/k3nny/glint/cmd/glint@latest
+```
+
+The binary is placed in `$(go env GOPATH)/bin/`. Add that directory to your
+`PATH` if it is not already there:
+
+```bash
+export PATH="$PATH:$(go env GOPATH)/bin"
+```
+
+---
+
+## Integrations
+
+For editor and CI integrations (pre-commit hook, GitLab CI component, GitHub
+Actions, VS Code extension) see [README.md](README.md#integrations).

README.md

@@ -6,7 +6,7 @@
 
 <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.3.1-blue.svg" alt="Release"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/release-v0.4.0-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.
@@ -27,25 +27,30 @@ A local tool to validate and lint `.gitlab-ci.yml` pipelines without needing a G
 
 See [FEATURES.md](FEATURES.md) for the complete feature reference and lint rules table, and [ROADMAP.md](ROADMAP.md) for planned improvements.
 
-## Requirements
-
-- Go 1.21 or later
-- [Task](https://taskfile.dev) (optional, for development tasks)
-
 ## Installation
 
+See [INSTALL.md](INSTALL.md) for all options: pre-built binaries (Linux amd64/arm64, macOS Intel/Apple Silicon, Windows), Homebrew tap, and building from source.
+
+Quick start (Linux/macOS, building from source):
+
 ```bash
 git clone https://git.k3nny.fr/k3nny/glint
 cd glint
 go build -o glint ./cmd/glint/...
+sudo mv glint /usr/local/bin/
 ```
 
-Or with Task:
+Homebrew:
 
 ```bash
-task build
+brew tap k3nny/glint https://github.com/k3nny/homebrew-glint
+brew install glint
 ```
 
+## Requirements
+
+Go 1.21 or later (when building from source). Pre-built binaries have no runtime dependencies.
+
 ## Usage
 
 ```
@@ -148,8 +153,12 @@ task changelog-next  # preview unreleased section (dry-run, no file written)
 task ext-install     # install VS Code extension npm dependencies
 task ext-compile     # compile the VS Code extension TypeScript source
 task ext-package     # package the VS Code extension as a .vsix
-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 build-linux-amd64   # cross-compile for Linux x86-64 (requires a tagged commit)
+task build-linux-arm64   # cross-compile for Linux ARM64 (requires a tagged commit)
+task build-darwin-amd64  # cross-compile for macOS Intel (requires a tagged commit)
+task build-darwin-arm64  # cross-compile for macOS Apple Silicon (requires a tagged commit)
+task build-windows       # cross-compile for Windows x86-64 (requires a tagged commit)
+task build-release       # build all platform binaries at once (requires a tagged commit)
 task clean        # remove build artifacts
 ```
 

ROADMAP.md

@@ -135,3 +135,8 @@ The SVG renderer and terminal tree cover the basic layout. These would bring it
 - [x] **Fuzz testing** — shipped v0.2.27; `FuzzParseBytes` and `FuzzSanitizeYAMLEscapes` in `internal/model/fuzz_test.go`; seeds run as regular tests in CI; `task fuzz` runs them continuously (default 30 s)
 - [x] **`glint check --no-warn`** — shipped v0.3.0; discards all warning findings before output and exit-code calculation; mixed pipelines (errors + warnings) still exit 2 but only errors are printed; warnings-only pipelines exit 0
 - [x] **Exit codes 2 / 10** *(breaking)* — shipped v0.3.0; `glint check` exits `2` when errors are present (previously `1`) and `10` when findings contain only warnings; exit `0` for clean
+- [x] **Git branch auto-detection** — shipped v0.4.0; when no context flags are given, `glint check` and `glint graph` run `git rev-parse --abbrev-ref HEAD` in the pipeline file's directory and use the result as the default branch (falls back to `main`)
+- [x] **GitLab predefined variable injection** — shipped v0.4.0; `CI=true` and `GITLAB_CI=true` always present in a non-empty context; MR-specific variables injected as placeholders when `--source merge_request_event`; all overridable via `--var`
+- [x] **Multi-platform release binaries** — shipped v0.4.0; `task build-release` builds Linux amd64/arm64, macOS Intel/Apple Silicon, and Windows amd64 in one shot
+- [x] **Homebrew formula** — shipped v0.4.0; `Formula/glint.rb` source-build formula; tap at `k3nny/homebrew-glint`
+- [x] **`INSTALL.md`** — shipped v0.4.0; installation guide for all platforms and methods

Taskfile.yml

@@ -145,30 +145,15 @@ tasks:
       - task: build
       - task: validate
 
-  build-windows:
-    desc: Build the glint binary for Windows x64 (requires a tagged commit)
+  build-linux-amd64:
+    desc: Build the glint binary for Linux x86-64 (requires a tagged commit)
+    aliases: [build-linux]
     vars:
       TAG:
         sh: git describe --tags --exact-match
     preconditions:
       - 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 -ldflags \"-X main.version={{.TAG}}\" -o {{.BINARY}}-{{.TAG}}.exe ./cmd/glint/..."
-    sources:
-      - "**/*.go"
-      - go.mod
-    generates:
-      - "{{.BINARY}}-{{.TAG}}.exe"
-
-  build-linux:
-    desc: Build the glint binary for Linux x64 (requires a tagged commit)
-    vars:
-      TAG:
-        sh: git describe --tags --exact-match
-    preconditions:
-      - sh: git describe --tags --exact-match
-        msg: "Current commit is not tagged — Linux build requires a git tag"
+        msg: "Current commit is not tagged — release build requires a git tag"
     cmds:
       - "GOOS=linux GOARCH=amd64 {{.GO}} build -ldflags \"-X main.version={{.TAG}}\" -o {{.BINARY}}-{{.TAG}}-linux-amd64 ./cmd/glint/..."
     sources:
@@ -177,6 +162,79 @@ tasks:
     generates:
       - "{{.BINARY}}-{{.TAG}}-linux-amd64"
 
+  build-linux-arm64:
+    desc: Build the glint binary for Linux ARM64 (requires a tagged commit)
+    vars:
+      TAG:
+        sh: git describe --tags --exact-match
+    preconditions:
+      - sh: git describe --tags --exact-match
+        msg: "Current commit is not tagged — release build requires a git tag"
+    cmds:
+      - "GOOS=linux GOARCH=arm64 {{.GO}} build -ldflags \"-X main.version={{.TAG}}\" -o {{.BINARY}}-{{.TAG}}-linux-arm64 ./cmd/glint/..."
+    sources:
+      - "**/*.go"
+      - go.mod
+    generates:
+      - "{{.BINARY}}-{{.TAG}}-linux-arm64"
+
+  build-darwin-amd64:
+    desc: Build the glint binary for macOS Intel (requires a tagged commit)
+    vars:
+      TAG:
+        sh: git describe --tags --exact-match
+    preconditions:
+      - sh: git describe --tags --exact-match
+        msg: "Current commit is not tagged — release build requires a git tag"
+    cmds:
+      - "GOOS=darwin GOARCH=amd64 {{.GO}} build -ldflags \"-X main.version={{.TAG}}\" -o {{.BINARY}}-{{.TAG}}-darwin-amd64 ./cmd/glint/..."
+    sources:
+      - "**/*.go"
+      - go.mod
+    generates:
+      - "{{.BINARY}}-{{.TAG}}-darwin-amd64"
+
+  build-darwin-arm64:
+    desc: Build the glint binary for macOS Apple Silicon (requires a tagged commit)
+    vars:
+      TAG:
+        sh: git describe --tags --exact-match
+    preconditions:
+      - sh: git describe --tags --exact-match
+        msg: "Current commit is not tagged — release build requires a git tag"
+    cmds:
+      - "GOOS=darwin GOARCH=arm64 {{.GO}} build -ldflags \"-X main.version={{.TAG}}\" -o {{.BINARY}}-{{.TAG}}-darwin-arm64 ./cmd/glint/..."
+    sources:
+      - "**/*.go"
+      - go.mod
+    generates:
+      - "{{.BINARY}}-{{.TAG}}-darwin-arm64"
+
+  build-windows:
+    desc: Build the glint binary for Windows x86-64 (requires a tagged commit)
+    vars:
+      TAG:
+        sh: git describe --tags --exact-match
+    preconditions:
+      - sh: git describe --tags --exact-match
+        msg: "Current commit is not tagged — release build requires a git tag"
+    cmds:
+      - "GOOS=windows GOARCH=amd64 {{.GO}} build -ldflags \"-X main.version={{.TAG}}\" -o {{.BINARY}}-{{.TAG}}-windows-amd64.exe ./cmd/glint/..."
+    sources:
+      - "**/*.go"
+      - go.mod
+    generates:
+      - "{{.BINARY}}-{{.TAG}}-windows-amd64.exe"
+
+  build-release:
+    desc: Build release binaries for all supported platforms (requires a tagged commit)
+    cmds:
+      - task: build-linux-amd64
+      - task: build-linux-arm64
+      - task: build-darwin-amd64
+      - task: build-darwin-arm64
+      - task: build-windows
+
   fuzz:
     desc: "Run all fuzz targets (set FUZZ_TIME=60s to control per-target duration, default 30s)"
     cmds:

cmd/glint/main.go

@@ -44,6 +44,29 @@ var execCommandOutput = func(name string, args ...string) ([]byte, error) {
 	return exec.Command(name, args...).Output()
 }
 
+// gitBranchInDir is a variable so tests can mock branch detection.
+var gitBranchInDir = func(dir string) ([]byte, error) {
+	cmd := exec.Command("git", "rev-parse", "--abbrev-ref", "HEAD")
+	cmd.Dir = dir
+	return cmd.Output()
+}
+
+// detectGitBranch returns the current git branch name by running
+// "git rev-parse --abbrev-ref HEAD" in dir. Returns "" when dir is not
+// inside a git repository, when the repo is in detached-HEAD state, or
+// when git is not available.
+func detectGitBranch(dir string) string {
+	out, err := gitBranchInDir(dir)
+	if err != nil {
+		return ""
+	}
+	b := strings.TrimSpace(string(out))
+	if b == "" || b == "HEAD" {
+		return ""
+	}
+	return b
+}
+
 // gitDiffFiles runs "git diff --name-only <ref>" and returns the list of changed
 // file paths. Returns nil + error when the command fails (e.g. not in a git repo
 // or the ref doesn't exist).
@@ -232,8 +255,13 @@ Options:
           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.
+detects the current git branch automatically and uses it as the default
+(falling back to 'main' when not inside a git repository or in detached-HEAD
+state). --source defaults to 'push' so that rules:if: expressions are always
+evaluated. GitLab's always-available predefined variables (CI=true,
+GITLAB_CI=true) are injected automatically; MR-specific variables
+(CI_MERGE_REQUEST_IID, CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, …) are injected
+when --source merge_request_event is given. Override any with --var.
 
 Examples:
   glint check .gitlab-ci.yml
@@ -244,6 +272,8 @@ Examples:
   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 --source merge_request_event --branch feature/my-branch .gitlab-ci.yml
+  glint check --source merge_request_event --var CI_MERGE_REQUEST_IID=42 .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
@@ -260,12 +290,6 @@ Examples:
 	}
 	_ = fs.Parse(args)
 
-	// Apply implicit defaults only in single-context mode when no flags are given.
-	if len(contexts) == 0 && *branch == "" && *tag == "" && *source == "" && len(vars) == 0 {
-		*branch = "main"
-		*source = "push"
-	}
-
 	validFormats := map[string]bool{
 		"text": true, "json": true, "sarif": true, "junit": true, "github": true,
 	}
@@ -283,6 +307,17 @@ Examples:
 	path := fs.Arg(0)
 	rootDir := filepath.Dir(filepath.Clean(path))
 
+	// Apply implicit defaults only in single-context mode when no flags are given.
+	// Prefer the actual git branch of the repository; fall back to "main".
+	if len(contexts) == 0 && *branch == "" && *tag == "" && *source == "" && len(vars) == 0 {
+		if detected := detectGitBranch(rootDir); detected != "" {
+			*branch = detected
+		} else {
+			*branch = "main"
+		}
+		*source = "push"
+	}
+
 	// Load project config (.glint.yml), searching from the pipeline directory
 	// up to the git root.
 	glintCfg, cfgErr := config.Load(rootDir)
@@ -586,8 +621,13 @@ Options:
           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.
+detects the current git branch automatically and uses it as the default
+(falling back to 'main' when not inside a git repository or in detached-HEAD
+state). --source defaults to 'push' so that rules:if: expressions are always
+evaluated. GitLab's always-available predefined variables (CI=true,
+GITLAB_CI=true) are injected automatically; MR-specific variables
+(CI_MERGE_REQUEST_IID, CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, …) are injected
+when --source merge_request_event is given. Override any with --var.
 
 Examples:
   glint graph .gitlab-ci.yml
@@ -618,12 +658,6 @@ Examples:
 	changesFrom := fs.String("changes-from", "", "git ref to diff against for rules:changes: evaluation (e.g. HEAD~1, origin/main)")
 	_ = 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()
 		exit(2)
@@ -632,6 +666,17 @@ Examples:
 	path := fs.Arg(0)
 	rootDir := filepath.Dir(filepath.Clean(path))
 
+	// Apply implicit defaults when no context flag is given at all.
+	// Prefer the actual git branch of the repository; fall back to "main".
+	if *branch == "" && *tag == "" && *source == "" && len(vars) == 0 {
+		if detected := detectGitBranch(rootDir); detected != "" {
+			*branch = detected
+		} else {
+			*branch = "main"
+		}
+		*source = "push"
+	}
+
 	glintCfg, cfgErr := config.Load(rootDir)
 	if cfgErr != nil {
 		fmt.Fprintf(os.Stderr, "%s: [warning] %s: %v\n", path, config.Filename, cfgErr)

cmd/glint/main_test.go

@@ -1250,3 +1250,31 @@ func TestIsSuppressed(t *testing.T) {
 	if !isSuppressed("all-job", "GL042", suppressions) { t.Error("wildcard should suppress") }
 	if isSuppressed("unknown-job", "GL001", suppressions) { t.Error("unknown job: not suppressed") }
 }
+
+func TestDetectGitBranch(t *testing.T) {
+	orig := gitBranchInDir
+	t.Cleanup(func() { gitBranchInDir = orig })
+
+	tests := []struct {
+		name    string
+		output  string
+		err     error
+		want    string
+	}{
+		{"normal branch", "main\n", nil, "main"},
+		{"branch with trailing newline", "feature/my-branch\n", nil, "feature/my-branch"},
+		{"detached HEAD", "HEAD\n", nil, ""},
+		{"git error (not a repo)", "", errors.New("exit 128"), ""},
+		{"empty output", "\n", nil, ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gitBranchInDir = func(_ string) ([]byte, error) {
+				return []byte(tt.output), tt.err
+			}
+			if got := detectGitBranch("."); got != tt.want {
+				t.Errorf("detectGitBranch() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}

internal/cicontext/context.go

@@ -14,6 +14,32 @@ type Context struct {
 	changedFiles []string        // nil = not provided (permissive); non-nil = known set of changed files
 }
 
+// gitlabAlwaysVars are GitLab predefined variables that are constant across
+// every pipeline, instance, and project. Injected at the lowest priority so
+// that pipeline variables: blocks and --var overrides can still win.
+var gitlabAlwaysVars = map[string]string{
+	"CI":        "true",
+	"GITLAB_CI": "true",
+}
+
+// gitlabMRVars are predefined variables GitLab injects only for
+// CI_PIPELINE_SOURCE=merge_request_event pipelines. Placeholder values are
+// used so that rules:if: expressions that gate on MR context evaluate
+// correctly. All can be overridden with --var.
+//
+// CI_MERGE_REQUEST_SOURCE_BRANCH_NAME is left empty here and filled from
+// CI_COMMIT_BRANCH (the --branch flag) when available.
+var gitlabMRVars = map[string]string{
+	"CI_MERGE_REQUEST_ID":                  "1",
+	"CI_MERGE_REQUEST_IID":                 "1",
+	"CI_MERGE_REQUEST_SOURCE_BRANCH_NAME":  "",
+	"CI_MERGE_REQUEST_TARGET_BRANCH_NAME":  "main",
+	"CI_MERGE_REQUEST_PROJECT_PATH":        "namespace/project",
+	"CI_MERGE_REQUEST_TITLE":               "Draft: placeholder",
+	"CI_MERGE_REQUEST_LABELS":              "",
+	"CI_OPEN_MERGE_REQUESTS":               "namespace/project!1",
+}
+
 // New builds a Context from high-level shortcut values and optional KEY=VALUE
 // overrides. Predefined CI variables are derived from the shortcuts so callers
 // do not need to know their exact names.
@@ -21,15 +47,18 @@ type Context struct {
 // Returns an empty Context (IsEmpty() == true) when all inputs are zero values,
 // 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).
+// Override priority (highest wins): extraVars > branch/tag/source shortcuts >
+// pipeline variables (via Inject) > GitLab predefined defaults.
 func New(branch, tag, source string, extraVars []string) *Context {
 	if branch == "" && tag == "" && source == "" && len(extraVars) == 0 {
 		return &Context{}
 	}
 
-	vars := make(map[string]string)
+	// Seed with always-available GitLab predefined variables at lowest priority.
+	vars := make(map[string]string, len(gitlabAlwaysVars)+8)
+	for k, v := range gitlabAlwaysVars {
+		vars[k] = v
+	}
 	pinned := make(map[string]bool)
 
 	pin := func(k, v string) {
@@ -62,6 +91,22 @@ func New(branch, tag, source string, extraVars []string) *Context {
 		vars["CI_DEFAULT_BRANCH"] = "main"
 	}
 
+	// For MR pipelines, inject placeholder values for the predefined MR
+	// variables so that rules:if: expressions like '$CI_MERGE_REQUEST_IID'
+	// evaluate as non-empty (truthy). These are non-pinned so --var overrides
+	// them and pipeline variables: can also override via Inject.
+	if source == "merge_request_event" {
+		for k, v := range gitlabMRVars {
+			if !pinned[k] {
+				vars[k] = v
+			}
+		}
+		// Derive source branch from --branch when available.
+		if branch != "" && vars["CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"] == "" {
+			vars["CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"] = branch
+		}
+	}
+
 	// KEY=VALUE overrides win over shortcuts and everything else.
 	for _, kv := range extraVars {
 		k, v, ok := strings.Cut(kv, "=")

internal/cicontext/context_test.go

@@ -78,6 +78,66 @@ func TestNew_DefaultBranch(t *testing.T) {
 	}
 }
 
+func TestNew_PredefinedAlwaysVars(t *testing.T) {
+	ctx := New("main", "", "", nil)
+	if ctx.Get("CI") != "true" {
+		t.Errorf("CI should be 'true', got %q", ctx.Get("CI"))
+	}
+	if ctx.Get("GITLAB_CI") != "true" {
+		t.Errorf("GITLAB_CI should be 'true', got %q", ctx.Get("GITLAB_CI"))
+	}
+}
+
+func TestNew_PredefinedAlwaysVars_EmptyContext(t *testing.T) {
+	// Always-vars must NOT be injected when the context is empty (no flags).
+	ctx := New("", "", "", nil)
+	if ctx.Get("CI") != "" {
+		t.Errorf("CI should be empty in empty context, got %q", ctx.Get("CI"))
+	}
+}
+
+func TestNew_PredefinedAlwaysVars_OverridableByVar(t *testing.T) {
+	ctx := New("main", "", "", []string{"CI=false"})
+	if ctx.Get("CI") != "false" {
+		t.Errorf("--var should override CI, got %q", ctx.Get("CI"))
+	}
+}
+
+func TestNew_PredefinedAlwaysVars_OverridableByInject(t *testing.T) {
+	ctx := New("main", "", "", nil)
+	ctx.Inject("CI", "custom")
+	if ctx.Get("CI") != "custom" {
+		t.Errorf("Inject should override non-pinned CI, got %q", ctx.Get("CI"))
+	}
+}
+
+func TestNew_MRVars(t *testing.T) {
+	ctx := New("feature/my-branch", "", "merge_request_event", nil)
+	if ctx.Get("CI_MERGE_REQUEST_IID") != "1" {
+		t.Errorf("CI_MERGE_REQUEST_IID should be '1', got %q", ctx.Get("CI_MERGE_REQUEST_IID"))
+	}
+	if ctx.Get("CI_MERGE_REQUEST_SOURCE_BRANCH_NAME") != "feature/my-branch" {
+		t.Errorf("source branch should match --branch, got %q", ctx.Get("CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"))
+	}
+	if ctx.Get("CI_MERGE_REQUEST_TARGET_BRANCH_NAME") != "main" {
+		t.Errorf("target branch should be 'main', got %q", ctx.Get("CI_MERGE_REQUEST_TARGET_BRANCH_NAME"))
+	}
+}
+
+func TestNew_MRVars_NotInjectedForNonMR(t *testing.T) {
+	ctx := New("main", "", "push", nil)
+	if ctx.Get("CI_MERGE_REQUEST_IID") != "" {
+		t.Errorf("CI_MERGE_REQUEST_IID should be empty for push pipeline, got %q", ctx.Get("CI_MERGE_REQUEST_IID"))
+	}
+}
+
+func TestNew_MRVars_OverridableByVar(t *testing.T) {
+	ctx := New("", "", "merge_request_event", []string{"CI_MERGE_REQUEST_IID=42"})
+	if ctx.Get("CI_MERGE_REQUEST_IID") != "42" {
+		t.Errorf("--var should override CI_MERGE_REQUEST_IID, got %q", ctx.Get("CI_MERGE_REQUEST_IID"))
+	}
+}
+
 func TestInject(t *testing.T) {
 	ctx := New("main", "", "", nil)
 	// pinned var should not be overwritten