> 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 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 by commenting `/lunar bypass: ` on a blocked pull or 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. For `source = 'ci'`, the actor from the OIDC token the job's Git platform signed; for a logged-in user or a Git platform comment, the authenticated login; with the Hub service token, unverified caller input. See Notes | | `verified_role` | `TEXT` | The role that was verified when the bypass was created, provider-qualified: e.g. `gitlab:maintainer` or `github:admin`. Set on comment break-glass bypasses and on CLI bypasses created by a logged-in user; `NULL` when the bypass was created with the Hub service token or by a CI job. A value suffixed with a repository, e.g. `github:maintain@github.com/acme/lunar-config`, was verified on the configuration repository rather than on the component: the actor administers Lunar as a Maintainer of the configuration repository and may hold no role on the component itself. `ci@` that repository is its own pipeline, which holds no role | | `source` | `TEXT` | The surface or authenticated principal that created the bypass. One of `cli` (Hub service token or logged-in user), `ci` (CI OIDC identity signed by the Git platform), `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. See Notes for the four ways a bypass stops being active | | `self_bypass` | `BOOLEAN` | Whether a request's own author bypassed their own change. Allowed, but recorded | | `superseded` | `BOOLEAN` | Whether the bypass is pinned to a commit that is no longer its pull request's head. Always `false` on the release gate, and on a bypass with no `sha` or no `pr` | | `pr_closed` | `BOOLEAN` | Whether the bypass's pull request has merged or closed. Always `false` on the release gate, and on a bypass with no `pr` | ## Notes * A bypass stops being `active` in four ways: it is revoked, its `expires_at` passes, its pull request moves to a new head commit (`superseded`), or its pull request merges or closes (`pr_closed`). The last two apply to the PR gate only. A `NULL` `expires_at` never lapses on the clock, so a commit-bound bypass leaves `active` through `superseded` or `pr_closed` instead. When Lunar cannot resolve a pull request's head or state, the row is left active rather than retired. * `lunar policy bypass-ls --active` is narrower than this column: it filters on revocation and the clock only, so a superseded or merged bypass still lists there while reading `active = false` here. * The `actor` column is not always authenticated. A bypass created with the Hub service token records whatever actor the caller supplied, unverified. One created by a CI job records the actor asserted by the OIDC token its Git platform signed, under `source = 'ci'`. The `verified_role` column is set only when the bypass was created through a surface that checked a real role: the comment break-glass on both platforms (the commenter's GitLab access level or GitHub repository role), and the CLI when run by a user signed in with `lunar login` (the role the Hub verified on the component, or on the configuration repository for its Maintainers, in which case the value names that repository). A CI job leaves it `NULL`, except the configuration repository's own pipeline, which records `ci@` that repository. Use `source` alongside it when auditing: `verified_role IS NULL` on its own lumps signed CI actors in with wholly unverified service-token rows. * 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.