GitLab Collector
Collect GitLab project settings, protected-branch and approval rules, access permissions, and merge-request metadata. Populates the same .vcs.* schema as the GitHub collector so VCS and ticket policies work on GitLab-hosted repositories.
gitlab to your lunar-config.yml:uses: github://earthly/lunar-lib/collectors/gitlab@v1.0.5
What This Integration Collects
This integration includes 4 collectors that gather metadata from your systems.
merge-request
Fetches merge-request metadata from the GitLab API for the MR being evaluated and writes it under .vcs.pr — title, description, source and target branch, author, labels, draft flag, state, URL, and number. This is the GitLab source of .vcs.pr.* that the ticket collectors (jira, linear) and change-management / change-to-ticket checks read. Runs only in merge-request context.
repository
Fetches basic project settings from the GitLab API including visibility (public/internal/private), default branch, topics, and the configured merge method (merge commit, rebase, fast-forward) plus squash options. Writes to .vcs.provider, .vcs.visibility, .vcs.default_branch, .vcs.topics, and .vcs.merge_strategies.
branch-protection
Fetches protected-branch config, MR approval rules, external status checks, and push rules for the default branch from the GitLab API, normalizing them into the shared .vcs.branch_protection shape with a .source field of "gitlab". Collects required approvals (from approval rules), code-owner approval, reset-on-push (dismiss stale reviews), required status checks (pipeline-success and/or external status checks, with their names in required_checks), signed-commit and linear-history enforcement, allowed force push, and push/merge access levels. Licensed- only signals degrade gracefully to their safe defaults on CE/unlicensed.
access-permissions
Fetches project access permissions from the GitLab API with pagination. Collects direct project members (username, access level, type) and shared groups (path, name, access level). Does not expand group memberships. Writes to .vcs.access.collaborators and .vcs.access.teams.
How Collectors Fit into Lunar
Lunar watches your code and CI/CD systems to collect SDLC data from config files, test results, IaC, deployment configurations, security scans, and more.
Collectors are the automatic data-gathering layer. They extract structured metadata from your repositories and pipelines, feeding it into Lunar's centralized database where guardrails evaluate it to enforce your engineering standards.
Learn How Lunar Works →Example Collected Data
This collector writes structured metadata to the Component JSON. Here's an example of the data it produces:
{
"vcs": {
"provider": "gitlab",
"default_branch": "main",
"visibility": "private",
"topics": ["backend", "api", "microservice"],
"merge_strategies": {
"allow_merge_commit": false,
"allow_squash_merge": true,
"allow_rebase_merge": true
},
"pr": {
"number": 42,
"title": "[ENG-123] Add rate limiting to the auth service",
"description": "Implements a token-bucket limiter. Closes ENG-123.",
"url": "https://gitlab.com/acme/auth-service/-/merge_requests/42",
"source_branch": "eng-123-rate-limiting",
"target_branch": "main",
"author": "alice",
"labels": ["backend", "security"],
"draft": false,
"state": "open"
},
"branch_protection": {
"enabled": true,
"source": "gitlab",
"branch": "main",
"require_pr": true,
"required_approvals": 2,
"require_codeowner_review": true,
"dismiss_stale_reviews": true,
"require_status_checks": true,
"required_checks": ["security-gate"],
"require_signed_commits": false,
"require_linear_history": false,
"allow_force_push": false,
"allow_deletions": false,
"restrictions": {
"push_access_level": "maintainer",
"merge_access_level": "developer"
}
},
"access": {
"collaborators": [
{"username": "alice", "permission": "owner", "type": "User"},
{"username": "deploy-bot", "permission": "developer", "type": "Bot"}
],
"teams": [
{"slug": "platform", "name": "Platform Team", "permission": "maintainer"}
]
}
}
}Configuration
Configure this collector in your lunar-config.yml.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
gitlab_host
|
Optional |
gitlab.com
|
GitLab host for self-managed instances (e.g. gitlab.example.com) |
Secrets
This collector requires the following secrets to be configured in Lunar:
| Secret | Description |
|---|---|
GL_TOKEN
|
GitLab personal or project access token with `read_api` scope for API authentication |
Documentation
View on GitHubGitLab Collector
Collects GitLab project settings, protected-branch rules, access permissions, and merge-request metadata via the GitLab API.
Overview
This collector is the GitLab equivalent of the github collector. It queries the GitLab API to gather version control system (VCS) configuration — project visibility, default branch, topics, merge method, protected-branch and approval rules, and access permissions — and, in merge-request context, the metadata of the MR being evaluated. It writes to the same .vcs.* schema as the GitHub collector so the shared vcs policy and the ticket collectors (jira, linear) work on GitLab-hosted repositories. It requires the LUNAR_SECRET_GL_TOKEN environment variable for API authentication, and takes an optional gitlab_host input (default gitlab.com) for self-managed instances.
Collected Data
This collector writes to the following Component JSON paths:
| Path | Type | Description |
|---|---|---|
.vcs.provider |
string | VCS provider name (always "gitlab") |
.vcs.default_branch |
string | Default branch name (e.g., "main", "master") |
.vcs.visibility |
string | Project visibility (public, internal, private) |
.vcs.topics |
array | Project topics/tags |
.vcs.merge_strategies |
object | Allowed merge strategies, mapped from the GitLab merge method |
.vcs.branch_protection |
object | Protected-branch and approval rules (source: "gitlab") |
.vcs.access |
object | Project members and shared groups |
.vcs.pr |
object | Merge-request metadata (populated only in MR context) |
Merge-request fields (.vcs.pr)
| Path | Type | Description |
|---|---|---|
.vcs.pr.number |
number | Merge-request IID |
.vcs.pr.title |
string | MR title (source for ticket-ID extraction) |
.vcs.pr.description |
string | MR description |
.vcs.pr.url |
string | Web URL of the merge request |
.vcs.pr.source_branch |
string | Source branch name |
.vcs.pr.target_branch |
string | Target branch name |
.vcs.pr.author |
string | Author username |
.vcs.pr.labels |
array | MR label names |
.vcs.pr.draft |
boolean | Whether the MR is a draft |
.vcs.pr.state |
string | MR state, normalized to the shared vocabulary (open, closed, merged) |
Collectors
This integration provides the following collectors (use include to select a subset):
| Collector | Description |
|---|---|
merge-request |
Populates .vcs.pr.* with the metadata of the MR being evaluated (title, description, branches, author, labels, draft, state, URL). Runs only in merge-request context. This is the GitLab source of .vcs.pr.* that the ticket and change-management policies consume. |
repository |
Collects basic project settings including visibility, default branch, topics, and the merge method mapped onto .vcs.merge_strategies. |
branch-protection |
Collects protected-branch config, MR approval rules, external status checks, and push rules for the default branch, normalized into .vcs.branch_protection with source: "gitlab". |
access-permissions |
Collects project members and shared groups (does not expand group memberships). |
Installation
Add to your lunar-config.yml:
collectors:
- uses: github://earthly/lunar-lib/collectors/gitlab@v1.0.0
on: ["domain:your-domain"] # Or use tags like [backend, kubernetes]
with:
gitlab_host: gitlab.com # Set to your self-managed host if applicable
secrets:
GL_TOKEN: ${{ secrets.GL_TOKEN }}
GL_TOKEN
A GitLab personal or project access token with read_api scope. Used for all GitLab API calls (project settings, protected branches, approval rules, members, and merge-request metadata).
Why .vcs.pr.* matters
The jira and linear ticket collectors extract a ticket ID from the merge/pull-request title to populate .vcs.pr.ticket.*, which the ticket and change-management (e.g. change→ticket) policies enforce. The github and gitlab collectors are the source of .vcs.pr.*: on GitLab, this collector's merge-request sub-collector supplies it; on GitHub, the github collector's pull-request sub-collector does. The ticket collectors' after-json variant (e.g. jira's ticket-from-json) then reads .vcs.pr.title from Component JSON — no SCM API call, provider-agnostic.
Self-managed instances and nested namespaces
Set the gitlab_host input to your instance host; the API base is derived from the host prefix of the component ID. GitLab projects can live under nested groups (group/subgroup/project), so the full project path is URL-encoded for the API and multi-segment namespaces are handled.
Merge-method mapping
GitLab exposes a single merge_method (merge, rebase_merge, ff) plus squash options rather than GitHub's three independent booleans. These are normalized onto .vcs.merge_strategies.allow_merge_commit / allow_rebase_merge / allow_squash_merge so the shared vcs policy applies unchanged.
Branch-protection field mapping
.vcs.branch_protection is normalized so the shared vcs policy checks evaluate GitLab the same as GitHub:
.vcs.branch_protection field |
GitLab source |
|---|---|
required_approvals |
sum of approval_rules[].approvals_required for the default branch; falls back to the deprecated approvals_before_merge |
require_status_checks / required_checks |
only_allow_merge_if_pipeline_succeeds, and configured External Status Checks (their names populate required_checks) |
require_codeowner_review |
protected branch code_owner_approval_required |
dismiss_stale_reviews |
MR approval setting reset_approvals_on_push |
require_signed_commits |
push rule reject_unsigned_commits |
require_linear_history |
merge_method == "ff" (fast-forward merges enforce linear history) |
Approval rules, external status checks, and push rules are GitLab premium/Ultimate features; on CE/unlicensed instances those endpoints return 403 and the corresponding fields degrade to their safe defaults (0 / false). GitHub's require_branches_up_to_date has no GitLab equivalent and is left unset (the require-branches-up-to-date check is GitHub-specific).
Open Source
This collector is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore guardrails that use data from GitLab Collector.
Ready to Automate Your Standards?
See how Lunar can turn your AGENTS.md, engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 200+ built-in guardrails.
AI agent rules & prompt files
Post-mortem action items
Security & compliance policies
Testing & quality requirements