bypasses

Schema reference for the bypasses SQL view — one row per policy bypass, with its scope, actor, reason, and expiry.

bypasses

The bypasses view provides information about policy bypasses: overrides of a PR or release block, created with lunar policy bypass-pr / lunar policy bypass-release, or — on GitLab — by commenting lunar bypass: <reason> on a blocked merge request. Use it to see how often blocks are being bypassed, by whom, and for what reason.

Rows are never deleted. Expired and revoked bypasses remain in the view. The bypassed_checks view records which checks each bypass actually masked.

Schema

Column	Type	Description
id	TEXT	The identifier for the bypass
component_id	TEXT	The identifier for the component the bypass applies to - e.g. github.com/foo/bar/buz
gate	TEXT	The block being bypassed. Can be one of pr or release
sha	TEXT	The Git commit SHA the bypass is limited to. Set to NULL if it applies to every commit
pr	BIGINT	The pull request number the bypass is limited to. Set to NULL if it applies to every pull request
policy	TEXT	The plugin (e.g. sbom) or single check (e.g. sbom.no-critical-vulns) the bypass is limited to. Set to NULL if it applies to every blocking check on the gate
reason	TEXT	The reason given for the bypass
actor	TEXT	Who created the bypass, as reported by the caller. Verified only where verified_role is set. See Notes
verified_role	TEXT	The role that was verified when the bypass was created — e.g. gitlab:maintainer for the MR-comment break-glass. Set to NULL if none was, which is always the case for bypasses created from the CLI
source	TEXT	The surface the bypass was created from. Can be one of cli, gitlab, github, or ui
created_at	TIMESTAMP	The UTC timestamp when the bypass was created
expires_at	TIMESTAMP	The UTC timestamp when the bypass expires. NULL for comment-driven bypasses, whose bound is the commit rather than a clock: they cover a single SHA, and a new push re-arms the gate
revoked_at	TIMESTAMP	The UTC timestamp when the bypass was revoked early. Set to NULL if it was not revoked
revoked_by	TEXT	Who revoked the bypass. Set to NULL if it was not revoked
active	BOOLEAN	Whether the bypass is currently in effect, meaning neither revoked nor expired. A NULL expires_at never expires on the clock
self_bypass	BOOLEAN	Whether a merge request's own author bypassed their own change — allowed, but recorded

Notes

• The actor column is not always authenticated. The CLI is authorized by token and does not verify who is running it, so actor is whatever the caller supplied. The verified_role column is set only when the bypass was created through a surface that checked a real role — the GitLab MR-comment break-glass records the commenter's inherited access level. Filter on verified_role IS NULL to find bypasses created without a verified role.
• CLI-created bypasses always expire. An omitted --for resolves to the bypass.max_duration setting in lunar-config.yml, which also caps any explicit --for. bypass.max_duration itself defaults to two weeks. Comment-driven bypasses carry no expiry: they are bound to a single commit instead, which is the tighter limit.
• A bypass with a NULL policy covers every failing blocking check on its gate, including checks from policies added to the manifest after the bypass was created. Use the bypassed_checks view to see which checks it actually masked.
• Gates are independent. A policy that blocks both the PR and the release gate needs a separate bypass for each, and bypassing the PR gate does not affect the release gate.

Usage examples

Retrieve the bypasses that are currently in effect.

SELECT component_id, gate, policy, actor, reason, expires_at
FROM bypasses
WHERE active
ORDER BY expires_at;

Count the bypasses created for each component over the last 90 days.

SELECT component_id, count(*) AS bypasses, count(DISTINCT actor) AS distinct_actors
FROM bypasses
WHERE created_at > now() - INTERVAL '90 days'
GROUP BY component_id
ORDER BY bypasses DESC;

Retrieve the policies that are bypassed most often.

SELECT COALESCE(policy, '(all blocking checks)') AS policy, count(*) AS times_bypassed
FROM bypasses
GROUP BY policy
ORDER BY times_bypassed DESC;

Retrieve the bypasses that have no verified role, which today is every bypass created from the CLI.

SELECT component_id, gate, actor, reason, created_at
FROM bypasses
WHERE verified_role IS NULL
ORDER BY created_at DESC;

Retrieve the active bypasses with the broadest scope: every blocking check, on every commit and every pull request of a component.

SELECT component_id, gate, actor, reason, expires_at
FROM bypasses
WHERE active AND policy IS NULL AND sha IS NULL AND pr IS NULL
ORDER BY expires_at DESC;

Retrieve the bypasses that were revoked early, and how long each one lasted.

SELECT component_id, actor AS created_by, revoked_by, revoked_at - created_at AS lifetime
FROM bypasses
WHERE revoked_at IS NOT NULL
ORDER BY revoked_at DESC;