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 (<host>/<org>/<repo>, 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.

SELECT component_id, reason, detail, failed_at
FROM component_webhooks
WHERE status = 'failed'
ORDER BY failed_at DESC;

Count failures by reason.

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.

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;