> For the complete documentation index, see [llms.txt](https://docs-lunar.earthly.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-lunar.earthly.dev/sql-api/views/bypasses.md). # bypasses ``` 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: ` 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`](/sql-api/views/bypassed-checks.md) 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`](/sql-api/views/bypassed-checks.md) 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. ```sql 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. ```sql 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. ```sql 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. ```sql 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. ```sql 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. ```sql 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; ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs-lunar.earthly.dev/sql-api/views/bypasses.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.