rules_gitlab

bazel_dep(name = "rules_gitlab", version = "0.3.4")

load("@rules_gitlab//gitlab:defs.bzl", "gitlab_ci", "gitlab_job", "gitlab_reference")

gitlab_ci(
    name = "ci",
    stages = ["build", "test"],
    variables = {"GREETING": "hello"},
    jobs = {
        ".setup": gitlab_job(before_script = ["echo setting up"]),
        "build": gitlab_job(
            stage = "build",
            before_script = gitlab_reference(".setup", "before_script"),
            script = ['echo "$GREETING from build"'],
        ),
        "test": gitlab_job(stage = "test", script = ["pytest"], coverage = "/^TOTAL/"),
    },
    write_to = ".gitlab-ci.yml",  # `bazel run :ci.update` writes it back
)

# MODULE.bazel
bazel_dep(name = "rules_gitlab", version = "0.1.0")

# (rules_gitlab auto-registers a PATH-based default `glab` toolchain
#  for gitlab_ci_lint; override by registering your own if you
#  want a hermetic glab binary.)

# BUILD.bazel
load("@rules_gitlab//gitlab:defs.bzl", "gitlab_ci_validate", "gitlab_ci_lint")

gitlab_ci_validate(
    name = "ci_validate",
    src = ".gitlab-ci.yml",
)

gitlab_ci_lint(
    name = "ci_lint",
    src = ".gitlab-ci.yml",
    repo = "https://gitlab.com/my-group/my-project",
)

bazel build :ci_validate    # hermetic schema check
bazel run   :ci_lint        # network-bound full lint

gitlab/
├── defs.bzl                # public rules: gitlab_ci_validate, gitlab_ci_lint
├── extensions.bzl          # http_file pin for the GitLab JSON Schema
├── glab/                   # toolchain abstraction over the `glab` CLI
│   ├── defs.bzl            # glab_toolchain rule
│   ├── system_glab.sh      # default toolchain: shells out to system `glab`
│   └── toolchain_type.bzl
└── private/
    ├── BUILD.bazel
    └── validate_main.py    # check-jsonschema wrapper invoked by the validate rule

tooling/
├── pyproject.toml          # check-jsonschema dep
└── uv.lock                 # resolved by `rules_uv`'s pip.parse

curl -fL "https://gitlab.com/gitlab-org/gitlab-foss/-/raw/master/app/assets/javascripts/editor/schema/ci.json" -o /tmp/ci.json
shasum -a 256 /tmp/ci.json
# paste the digest into _CI_SCHEMA_SHA256

Real usage, taken from the module’s examples/.

examples/generate/BUILD.bazel

load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("//gitlab:defs.bzl", "gitlab_ci", "gitlab_job", "gitlab_pages_job", "gitlab_reference")

package(default_visibility = ["//visibility:public"])

# Smoke: assemble a small pipeline from typed Starlark, emit it as YAML,
# schema-validate the result, and gate the bytes against a committed
# golden. `bazel run //examples/generate:pipeline.update` regenerates the
# golden; `bazel test //examples/generate:...` checks it's current + valid.
gitlab_ci(
    name = "pipeline",
    stages = ["build", "test", "pages"],
    variables = {"GREETING": "hello"},
    jobs = {
        # Hidden template job + a `!reference` to it (round-trip test).
        ".setup": gitlab_job(
            before_script = ["echo setting up"],
        ),
        "build": gitlab_job(
            stage = "build",
            before_script = gitlab_reference(".setup", "before_script"),
            script = ['echo "$GREETING from build"'],
        ),
        "test": gitlab_job(
            stage = "test",
            script = ['echo "$GREETING from test"'],
            coverage = "/^TOTAL\\s+\\d+/",
        ),
        # The generic static-site → GitLab Pages job.
        "pages": gitlab_pages_job(
            site = "//docs:site",
            site_artifact = "bazel-bin/docs/site.tar.gz",
        ),
    },
    write_to = "golden/.gitlab-ci.yml",
)

diff_test(
    name = "pipeline_golden_test",
    file1 = ":pipeline",
    file2 = "golden/.gitlab-ci.yml",
)

examples/smoke/BUILD.bazel

load("@bazel_skylib//rules:build_test.bzl", "build_test")
load("@rules_gitlab//gitlab:defs.bzl", "gitlab_ci_lint", "gitlab_ci_validate")

package(default_visibility = ["//visibility:public"])

# Smoke test: a minimal valid .gitlab-ci.yml fixture must pass
# schema validation. Failure of this target in CI signals either
# a schema-pin drift (upstream broke compatibility) or a bug in
# the rule wiring.
gitlab_ci_validate(
    name = "valid_smoke",
    src = "valid.gitlab-ci.yml",
)

# Lint variant exercises the launcher-script generation +
# toolchain resolution; `bazel build` is enough to verify the
# launcher is produced. Running it requires `glab auth login`,
# so we don't gate CI on actually running it.
gitlab_ci_lint(
    name = "valid_smoke_lint",
    src = "valid.gitlab-ci.yml",
    # Empty repo — under `bazel run` glab will fall back to the
    # cwd's git remote (gitlab.com if nothing matches). Real
    # consumers should set this; the fixture leaves it blank
    # because we only `bazel build` here.
)

# Surface the validate + lint smoke targets under `bazel test` so
# rules_gitlab's GitHub Actions CI gates them. The lint target's
# output is just the generated launcher script (no network call
# happens during build), so this stays hermetic.
build_test(
    name = "smoke_build_test",
    targets = [
        ":valid_smoke",
        ":valid_smoke_lint",
    ],
)

from docs/defs.md

Public Bazel rules for working with GitLab CI configuration.

Today (v0.1.0):

• gitlab_ci_validate(name, src) — build-action rule. Validates a .gitlab-ci.yml against the official GitLab JSON Schema pinned by sha via the gitlab_schemas module extension. Hermetic; no network, no auth.
• gitlab_ci_lint(name, src, host, repo) — bazel run-able target. Wraps glab ci lint <src> via the glab toolchain. Hits the GitLab API for full pipeline validation (semantic checks beyond pure schema + include: resolution). Requires glab auth login to the target instance.

Future surface:

• gitlab_ci_lint_remote(name, src, project) — call /api/v4/projects/:id/ci/lint directly (no glab CLI indirection), bake the project context.
• Deploy + registry helpers, schema-derived typed Starlark rules for authoring .gitlab-ci.yml from Bazel (mirroring the rules_jsonschema + rules_cloudformation pattern).

Limitations of gitlab_ci_validate:

• Does not follow include: directives. A .gitlab-ci.yml that imports another project’s snippets is validated only at its own leaf level; chain validations on the included files by registering each as a separate gitlab_ci_validate target. gitlab_ci_lint handles includes server-side.

gitlab_ci_lint

load("@rules_gitlab//gitlab:defs.bzl", "gitlab_ci_lint")

gitlab_ci_lint(name, src, host, repo)

bazel run-able target that lints a .gitlab-ci.yml via glab ci lint. Network-bound: hits the GitLab API, requires the user to be glab auth login-ed to the target instance. For hermetic schema-only validation, use gitlab_ci_validate instead.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
src	Label of the .gitlab-ci.yml (or fragment) to lint.	Label	required
host	GitLab host (e.g. gitlab.savvifi.com). Used to anchor glab’s API target when the runfiles cwd doesn’t have a gitlab remote. Ignored if repo is set (which carries host).	String	optional	""
repo	OWNER/REPO or full URL passed as glab -R. Strongly recommended — lets glab pick the right GitLab instance + project context without inspecting the sandbox’s git state.	String	optional	""

gitlab_ci_validate

load("@rules_gitlab//gitlab:defs.bzl", "gitlab_ci_validate")

gitlab_ci_validate(name, src)

Validate a .gitlab-ci.yml against the official GitLab JSON Schema (pinned by sha256 via the gitlab_schemas module extension). Output: a stamp file Bazel checks for caching; on schema violation the build fails with check-jsonschema’s diagnostic on stderr.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
src	Label of the .gitlab-ci.yml (or sibling fragment) to validate.	Label	required

gitlab_ci

load("@rules_gitlab//gitlab:defs.bzl", "gitlab_ci")

gitlab_ci(name, stages, variables, default, image, include, workflow, jobs, extra, out, write_to,
          validate, **kwargs)

Generate a .gitlab-ci.yml from a typed Starlark spec.

Assembles the spec in a fixed top-level order (include, workflow, default, image, stages, variables, jobs sorted by name, extra), emits it deterministically as YAML, and (by default) schema-validates the result. Set write_to (e.g. ".gitlab-ci.yml") to also create <name>.update — bazel run …:<name>.update writes the file into the source tree; bazel test …:<name>.update checks it is up to date.

PARAMETERS

Name	Description	Default Value
name	target name.	none
stages	list of stage names (order preserved).	[]
variables	global CI variables (dict).	{}
default	the default: job-config block (dict).	None
image	top-level default image (str or dict).	None
include	include: entries (list).	None
workflow	the workflow: block (dict).	None
jobs	dict of job-name -> job (a gitlab_job(...) dict or a raw dict).	{}
extra	escape hatch — raw dict merged at the top level last.	{}
out	output filename; defaults to <name>.gitlab-ci.yml.	None
write_to	source-relative path to also create <name>.update.	None
validate	chain gitlab_ci_validate on the generated file (default True).	True
kwargs	forwarded to the underlying rule (visibility, tags, …).	none

gitlab_job

load("@rules_gitlab//gitlab:defs.bzl", "gitlab_job")

gitlab_job(stage, script, image, services, before_script, after_script, rules, needs, artifacts,
           variables, cache, tags, environment, when, allow_failure, interruptible, timeout, retry,
           parallel, coverage, extends, dependencies, extra)

Build one GitLab CI job as a None-stripped, key-ordered dict.

Returns a plain dict (Starlark structs aren’t json.encode-able), so pass the result as a value in gitlab_ci(jobs = {...}). Any key not modeled here can be supplied via extra (a raw dict, merged last).

PARAMETERS

Name	Description	Default Value
stage	-	None
script	-	None
image	-	None
services	-	None
before_script	-	None
after_script	-	None
rules	-	None
needs	-	None
artifacts	-	None
variables	-	None
cache	-	None
tags	-	None
environment	-	None
when	-	None
allow_failure	-	None
interruptible	-	None
timeout	-	None
retry	-	None
parallel	-	None
coverage	-	None
extends	-	None
dependencies	-	None
extra	-	{}

gitlab_pages_job

load("@rules_gitlab//gitlab:defs.bzl", "gitlab_pages_job")

gitlab_pages_job(site, site_artifact, stage, strip_components, only_default_branch, rules, **kwargs)

A GitLab Pages job that publishes a Bazel-built static site.

GitLab Pages serves the public/ artifact of a job named pages. This builds site (a target whose output site_artifact is a .tar.gz of the site root — e.g. an mdbook_book or any pkg_tar of HTML) and unpacks it into public/. The generic “ship this repo’s static site to Pages” job:

gitlab_ci(
    name = "ci",
    stages = ["pages"],
    jobs = {
        "pages": gitlab_pages_job(
            site = "//docs:site",
            site_artifact = "bazel-bin/docs/site.tar.gz",
        ),
    },
)

PARAMETERS

Name	Description	Default Value
site	the Bazel label (string) that builds the static site.	none
site_artifact	workspace-relative path to the built site .tar.gz.	none
stage	the CI stage for the job (default "pages").	"pages"
strip_components	tar --strip-components, for archives with a top-level directory. mdbook’s output is flat, so the default 0 is correct.	0
only_default_branch	when True (default) and rules is unset, restrict the job to the default branch — Pages publishes from a single ref.	True
rules	explicit GitLab rules:; overrides only_default_branch.	None
kwargs	any other gitlab_job field (needs, variables, image, …).	none

RETURNS

A job dict for use as a gitlab_ci(jobs = {...}) value. The job name MUST be "pages" for GitLab to publish it.

gitlab_reference

load("@rules_gitlab//gitlab:defs.bzl", "gitlab_reference")

gitlab_reference(*parts)

Emit a GitLab !reference [job, key, ...] tag value.

Usable as a value anywhere in a spec; survives json.encode as a sentinel the emitter turns back into a real !reference YAML tag.

PARAMETERS

Name	Description	Default Value
parts	-	none