> 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/component-webhooks.md). # component\_webhooks Schema reference for the component\_webhooks SQL view. One row per component, saying whether Lunar could install its repository webhook and, if not, why. ``` component_webhooks ``` The `component_webhooks` view reports, for each component, whether the Hub could install the webhook it needs on the component's repository. Without that webhook, pushes and pull requests never reach Lunar, and the component looks like one that simply has no recent activity. Use this view to find the components whose webhook registration failed, and why. There is one row per live component whose name is a repository path (`//`, optionally followed by a subdirectory). A component that is not backed by a repository has no webhook to register, so it has no row. ## Schema | Column | Type | Description | | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `component_id` | `TEXT` | The identifier for the component - e.g. `github.com/foo/bar/buz` | | `status` | `TEXT` | One of `ok` (the webhook is installed), `failed` (registration failed; see `reason` and `detail`) or `pending` (the component was cataloged and its first repository sync has not finished yet) | | `reason` | `TEXT` | Why registration failed, when `status = 'failed'`; `NULL` otherwise. One of `insufficient_role`, `repo_not_found`, `archived`, `hook_cap`, `token_rejected`, `owner_not_configured`, `hook_inactive`, `hook_auto_disabled`, `hook_deleted`, `unknown`. See Notes | | `detail` | `TEXT` | What to do about it, or the Git platform's own message, when `status = 'failed'`; `NULL` otherwise | | `hook_id` | `BIGINT` | The webhook's identifier at the Git platform, once installed. `NULL` before the first successful registration | | `enabled_at` | `TIMESTAMP` | The UTC timestamp of the last successful registration. `NULL` if there has not been one | | `failed_at` | `TIMESTAMP` | The UTC timestamp of the recorded failure, when `status = 'failed'`; `NULL` otherwise | | `last_activity_at` | `TIMESTAMP` | The UTC commit time of the newest commit Lunar has ingested for the component. `NULL` if none has been ingested. An `ok` component with an old `last_activity_at` is quiet rather than broken | ## Notes * `pending` is normal right after a component is cataloged, and for a while after a large catalog change, because registration runs in the background and works through the queue. If a component stays `pending`, its registration keeps failing with an error Lunar could not classify. The last attempt then records it as `failed` with `reason = 'unknown'` and the error text in `detail`. * The reasons: * `insufficient_role`: the credential can read the repository but cannot manage its webhooks. On GitLab the token needs the Maintainer role on the project; on GitHub the App needs the repository webhooks permission. * `repo_not_found`: the Git platform answered that the repository does not exist or is not visible to the credential. * `archived`: the repository is archived, so the Git platform refuses to install a webhook on it. * `hook_cap`: the Git platform refused to add another webhook to the repository. * `token_rejected`: the Git platform rejected the credential itself. * `owner_not_configured`: the Hub has no credential for the repository's host and owner. * `hook_inactive`: the webhook exists, but a repository administrator deactivated it in the repository's settings and Lunar could not reactivate it (GitHub). * `hook_auto_disabled`: the Git platform disabled the webhook after failed deliveries and Lunar could not re-enable it (GitLab). * `hook_deleted`: the Git platform reported the webhook deleted (GitHub). Lunar recreates it on the next repository sync, and the status goes back to `ok`. * `unknown`: an error Lunar could not classify used up all its retries. `detail` carries the error text. * Lunar re-verifies webhooks periodically (every 12 hours by default), so a failure that happens long after cataloging, such as a deleted hook, a downgraded token or an archived repository, shows up here too. Repairs are picked up the same way: fix the cause and the status goes back to `ok` at the next verification. * Rate limits at the Git platform are not reported as failures. Lunar waits and retries. ## Usage examples List the components whose webhook registration failed, with the reason and what to do about it. ```sql SELECT component_id, reason, detail, failed_at FROM component_webhooks WHERE status = 'failed' ORDER BY failed_at DESC; ``` Count failures by reason. ```sql SELECT reason, count(*) AS components FROM component_webhooks WHERE status = 'failed' GROUP BY reason ORDER BY components DESC; ``` List the `ok` components with no commit ingested in the last 30 days. ```sql SELECT component_id, last_activity_at FROM component_webhooks WHERE status = 'ok' AND (last_activity_at IS NULL OR last_activity_at < now() - INTERVAL '30 days') ORDER BY last_activity_at NULLS FIRST; ``` --- # 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/component-webhooks.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.