rules_gitlab

API reference, generated from the module’s .bzl docstrings (stardoc).

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_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

Keyboard shortcuts

fastverk

rules_gitlab

gitlab_ci_lint

gitlab_ci_validate

gitlab_ci

gitlab_job

gitlab_reference