# Earthly Lunar ## Earthly Lunar - [Introduction](https://docs-lunar.earthly.dev/readme.md): Earthly Lunar is a guardrails platform for monitoring and enforcing engineering practices across your software development lifecycle. - [Install Lunar](https://docs-lunar.earthly.dev/install.md): Overview of Lunar installation, covering Hub, CLI, CI Tracer for self-hosted and managed runners, and AI skills for building plugins. - [Lunar CLI](https://docs-lunar.earthly.dev/install/cli.md): Install the Lunar CLI for managing configurations, inspecting components, running collectors, and testing policies locally. - [Lunar Hub](https://docs-lunar.earthly.dev/install/lunar-hub.md): Install and configure Lunar Hub, the central service that stores metadata, evaluates policies, and provides visibility into engineering health. - [Self hosted](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted.md): Run Lunar Hub yourself on Kubernetes — the overview, prerequisites, install walkthrough, config sync, and day-2 operations, in the order you need them. - [Overview](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/overview.md) - [Prerequisites](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/prerequisites.md) - [Install Walkthrough](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/install-walkthrough.md) - [Sync Config](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/sync-config.md): Keep Lunar Hub's copy of your config repo current on every push — with the sync-config GitHub Action, or a GitLab CI job. - [Day-2 Operations](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/day-2-operations.md) - [Lunar Dedicated](https://docs-lunar.earthly.dev/install/lunar-hub/dedicated.md): Lunar Dedicated is a single-tenant Lunar install that Earthly provisions, operates, and upgrades for you — the overview, what your team does to bring one up, and the private paths in and out of it. - [Overview](https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/overview.md): How a Lunar Dedicated install works — a single-tenant install that Earthly provisions, operates, and upgrades end-to-end in a dedicated AWS account, reachable over private networking or the internet. - [Setup](https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/setup.md): What your team does to bring up a Lunar Dedicated install, covering connectivity, the depositor account, your Git platform credential, and the secret deposit. - [PrivateLink to Your Hub](https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/privatelink-inbound.md): Reach your Lunar Dedicated hub, UI, and optional SQL and monitoring endpoints over AWS PrivateLink from your own VPC. - [PrivateLink to Your Systems](https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/privatelink-outbound.md): Give your Lunar Dedicated install a private path to internal systems (an internal Git server, registry, or API) by publishing them as an AWS PrivateLink endpoint service. - [Git Platforms](https://docs-lunar.earthly.dev/install/git-platforms.md): What Lunar supports on GitHub and GitLab — identity, webhooks, policy results, merge gating, and CI — and where the setup instructions for each Git platform live. - [GitHub](https://docs-lunar.earthly.dev/install/git-platforms/github.md): Set up GitHub for Lunar, including the Hub's GitHub App, user sign-in, multi-organization access, and merge blocking. - [GitLab](https://docs-lunar.earthly.dev/install/git-platforms/gitlab.md): Set up GitLab for Lunar, including the Hub service account, user sign-in, result reporting, and merge blocking. - [Lunar CI Tracer](https://docs-lunar.earthly.dev/install/ci-tracer.md): Which CI platforms the Lunar CI Tracer can trace (GitHub Actions, Buildkite, and GitLab CI), and where the setup instructions for each live. - [GitHub Actions (Self-Hosted)](https://docs-lunar.earthly.dev/install/ci-tracer/github-actions-self-hosted.md): Install the Lunar CI Tracer on self-hosted runners to instrument CI/CD pipelines and collect metadata during builds, tests, scans, and deploys. - [GitHub Actions (Managed)](https://docs-lunar.earthly.dev/install/ci-tracer/github-actions-managed.md): Use the Lunar CI Tracer action to instrument GitHub-hosted and self-hosted GitHub Actions runners with the Lunar CI Tracer. - [Buildkite](https://docs-lunar.earthly.dev/install/ci-tracer/buildkite.md): Run Lunar on Buildkite — trace builds with a Buildkite agent command hook and deliver build status to Lunar Hub with a Notification Service webhook. - [GitLab CI](https://docs-lunar.earthly.dev/install/ci-tracer/gitlab-ci.md): GitLab CI tracing support in Lunar is coming soon. - [Configuration Reference](https://docs-lunar.earthly.dev/install/ci-tracer/configuration-reference.md): Reference for all environment variables that configure the Lunar CI Tracer, including required settings, Docker options, and state directories. - [Systemd](https://docs-lunar.earthly.dev/install/ci-tracer/systemd.md): Run Lunar as a systemd service on Linux hosts with a sample unit file for reliable startup, restarts, and environment configuration. - [AI Skills](https://docs-lunar.earthly.dev/install/skills.md): Install AI agent skills for Claude Code, Codex, Cursor, and 50+ other agents to help build Lunar collectors, policies, and SQL queries. - [Learn the basics](https://docs-lunar.earthly.dev/basics.md): Walk through your first Lunar setup — populating components, defining policies, and running checks against your repositories. - [Key concepts](https://docs-lunar.earthly.dev/docs/key-concepts.md): Overview of Lunar's core concepts — domains, components, collectors, catalogers, policies, and checks — and how they fit together. - [Guides](https://docs-lunar.earthly.dev/docs/guides.md): Opinionated guides for rolling out Lunar in a large engineering organization, beyond the reference documentation. - [Cataloging Strategy](https://docs-lunar.earthly.dev/docs/guides/cataloging-strategy.md): How to build a complete, trustworthy software catalog in Lunar — achieving full coverage, cleaning up inconsistent existing catalog data, handling monorepos, and enforcing catalog quality with guardra - [Component JSON](https://docs-lunar.earthly.dev/docs/component-json.md): How the Component JSON aggregates SDLC metadata deltas from collectors into a single object that policies evaluate against. - [Catalog JSON](https://docs-lunar.earthly.dev/docs/catalog-json.md): Structure and precedence rules for the Catalog JSON, which merges domains and components from catalogers, lunar.yml, and lunar-config.yml. - [Authorization](https://docs-lunar.earthly.dev/docs/authorization.md): How Lunar Hub identifies callers and decides which operations each credential may perform. - [CI Job Identity](https://docs-lunar.earthly.dev/docs/authorization/ci-identity.md): Authenticate CI jobs to Lunar Hub with the OIDC token their CI platform issues, on GitHub Actions and GitLab CI. - [Lunar CLI Reference](https://docs-lunar.earthly.dev/docs/lunar-cli.md): Complete reference for every Lunar CLI command, subcommand, flag, and environment variable across collectors, catalogers, policies, and Hub operations. - [PR/MR Comments Reference](https://docs-lunar.earthly.dev/docs/pr-comments.md): Reference for the /lunar commands Lunar accepts as comments on pull requests and merge requests, and what each one does to the merge gate. - [lunar-config.yml](https://docs-lunar.earthly.dev/configuration/lunar-config.md): Reference for lunar-config.yml — the central configuration file defining hub connection, catalogers, domains, components, collectors, initiatives, and policies. - [About images](https://docs-lunar.earthly.dev/configuration/lunar-config/images.md): Configure default container images for collectors, policies, and catalogers in lunar-config.yml, with override precedence rules. - [catalogers](https://docs-lunar.earthly.dev/configuration/lunar-config/catalogers.md): Define the catalogers section of lunar-config.yml — scripts that synchronize domain and component metadata from external systems. - [catalogers/hooks](https://docs-lunar.earthly.dev/configuration/lunar-config/cataloger-hooks.md): Configure cataloger hooks in lunar-config.yml — triggers like cron schedules or repository events that determine when catalogers run. - [customization](https://docs-lunar.earthly.dev/configuration/lunar-config/customization.md): Customize Lunar's presentation and behavior. - [domains](https://docs-lunar.earthly.dev/configuration/lunar-config/domains.md): Define the domains section of lunar-config.yml — hierarchical groupings that organize related components for ownership and policy targeting. - [components](https://docs-lunar.earthly.dev/configuration/lunar-config/components.md): Define the components section of lunar-config.yml — repositories or monorepo subdirectories that Lunar monitors with metadata and tags. - [collectors](https://docs-lunar.earthly.dev/configuration/lunar-config/collectors.md): Define the collectors section of lunar-config.yml — scripts that run on CI, code, or cron triggers to gather component metadata. - [collectors/hooks](https://docs-lunar.earthly.dev/configuration/lunar-config/collector-hooks.md): Configure collector hooks in lunar-config.yml — triggers like CI commands, code events, or cron schedules that determine when collectors run. - [initiatives](https://docs-lunar.earthly.dev/configuration/lunar-config/initiatives.md): Define the initiatives section of lunar-config.yml — groupings of policies around shared goals or compliance requirements. - [policies](https://docs-lunar.earthly.dev/configuration/lunar-config/policies.md): Define the policies section of lunar-config.yml — rules that Lunar evaluates against components to enforce standards and check health. - [on (tag matching)](https://docs-lunar.earthly.dev/configuration/lunar-config/on.md): Reference for the on field in lunar-config.yml — tag-matching expressions used by collectors, policies, and initiatives to target components. - [uiPanels](https://docs-lunar.earthly.dev/configuration/lunar-config/uipanels.md): Configure SQL-backed tabs for Lunar dashboard extension points through the uiPanels section of lunar-config.yml. - [Validating your config](https://docs-lunar.earthly.dev/configuration/lunar-config/validation.md): Validate lunar-config.yml at commit/PR time — before merge — with a Hub-less dry run that runs the same checks the Hub does, plus a generated JSON Schema. - [lunar.yml](https://docs-lunar.earthly.dev/configuration/lunar-yml.md): Reference for lunar.yml, the optional per-repository file that configures a single component's owner, domain, branch, tags, and CI pipelines. - [Hub configuration](https://docs-lunar.earthly.dev/configuration/hub-configuration.md) - [Data Retention](https://docs-lunar.earthly.dev/configuration/hub-configuration/data-retention.md): What a Lunar Hub install deletes on its own, what it keeps for the life of the install, and the environment variables that change either. - [Plugins configuration](https://docs-lunar.earthly.dev/plugin-sdks/plugins.md): Overview of the three Lunar plugin types — catalogers, collectors, and policies — that extend the platform's capabilities. - [lunar-cataloger.yml](https://docs-lunar.earthly.dev/plugin-sdks/plugins/cataloger-plugins.md): Reference for lunar-cataloger.yml, the manifest that defines a cataloger plugin used to sync software catalog information from external systems. - [lunar-collector.yml](https://docs-lunar.earthly.dev/plugin-sdks/plugins/collector-plugins.md): Reference for lunar-collector.yml, the manifest that defines a collector plugin used to gather live information about components from various sources. - [lunar-policy.yml](https://docs-lunar.earthly.dev/plugin-sdks/plugins/policy-plugins.md): Reference for lunar-policy.yml, the manifest that defines a policy plugin used to evaluate the health of components against rules. - [Bash SDK](https://docs-lunar.earthly.dev/plugin-sdks/bash-sdk.md): Overview of the Lunar Bash SDK for building custom catalogers and collectors with shell scripts. - [Installing dependencies](https://docs-lunar.earthly.dev/plugin-sdks/bash-sdk/dependencies.md): How to install dependencies for Bash collectors and catalogers using a custom Docker image or an install.sh script. - [Cataloger](https://docs-lunar.earthly.dev/plugin-sdks/bash-sdk/cataloger.md): Write Lunar catalogers in Bash — environment variables and the lunar catalog CLI commands for saving catalog data. - [Collector](https://docs-lunar.earthly.dev/plugin-sdks/bash-sdk/collector.md): The lunar collect CLI for collecting SDLC metadata into a component's JSON, and the environment available to Lunar collectors. - [Python SDK](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk.md): Overview of Lunar's Python SDK for writing custom Lunar policies (with collector support coming soon). - [Installing dependencies](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk/dependencies.md): How to install Python dependencies for Lunar policies, using a custom Docker image or native runtime execution. - [Collector](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk/collector.md): Placeholder for the upcoming Python Collector SDK used to gather component metadata in Lunar. - [Policy](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk/policy.md): Write Lunar policies in Python with the lunar\_policy package — load component metadata, make assertions, and handle pending data. - [Check](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk/policy/check.md): Reference for the Check class in Lunar's Python Policy SDK — the fluent API for asserting on component metadata and tracking results. - [CheckStatus](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk/policy/check-status.md): Reference for the CheckStatus enum used to mark Lunar policy outcomes as PASS, FAIL, PENDING, ERROR, or SKIPPED. - [Node](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk/policy/node.md): Reference for the Node class in Lunar's Python Policy SDK — used to navigate, query, and iterate over component JSON data. - [NoDataError](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk/policy/no-data-error.md): Reference for the NoDataError exception that signals required component data is not yet collected, marking a Lunar check as pending. - [SkippedError](https://docs-lunar.earthly.dev/plugin-sdks/python-sdk/policy/skipped-error.md): Reference for the SkippedError exception used to skip a Lunar check when it does not apply to the current component. - [Overview](https://docs-lunar.earthly.dev/sql-api/sql-api.md): Connect to Lunar's read-only SQL API, manage personal credentials, and query its component, policy, and audit views. - [Views](https://docs-lunar.earthly.dev/sql-api/views.md) - [domains](https://docs-lunar.earthly.dev/sql-api/views/domains.md): Schema reference for the domains SQL view — one row per domain with its description, owner, and metadata for grouping components. - [components](https://docs-lunar.earthly.dev/sql-api/views/components.md): Schema reference for the components and components\_latest SQL views — time series of tracked components with merged collector metadata per commit. - [component\_deltas](https://docs-lunar.earthly.dev/sql-api/views/component-deltas.md): Schema reference for the component\_deltas SQL views — per-collector metadata deltas that merge into each component's full JSON over time. - [initiatives](https://docs-lunar.earthly.dev/sql-api/views/initiatives.md): Schema reference for the initiatives SQL view — one row per initiative grouping policies around a shared goal or compliance requirement. - [policies](https://docs-lunar.earthly.dev/sql-api/views/policies.md): Schema reference for the policies SQL view — one row per policy with its enforcement level and parent initiative. - [checks](https://docs-lunar.earthly.dev/sql-api/views/checks.md): Schema reference for the checks and checks\_latest SQL views — every policy check evaluation with status, enforcement, component, and PR context. - [prs](https://docs-lunar.earthly.dev/sql-api/views/prs.md): Schema reference for the prs SQL view — pull request and merge request metadata including author, status, and latest commit details. - [catalog](https://docs-lunar.earthly.dev/sql-api/views/catalog.md): Schema reference for the catalog and catalog\_latest SQL views — full catalog JSON snapshots produced by catalogers, with history over time. - [bypasses](https://docs-lunar.earthly.dev/sql-api/views/bypasses.md): Schema reference for the bypasses SQL view — one row per policy bypass, with its scope, actor, reason, and expiry. - [bypassed\_checks](https://docs-lunar.earthly.dev/sql-api/views/bypassed-checks.md): Schema reference for the bypassed\_checks SQL view, an append-only log with one row per occasion a bypass let a failing or pending check through. - [component\_webhooks](https://docs-lunar.earthly.dev/sql-api/views/component-webhooks.md): Schema reference for the component\_webhooks SQL view. One row per component, saying whether Lunar could install its repository webhook and, if not, why. - [Product](https://docs-lunar.earthly.dev/release-notes/product.md) - [2026](https://docs-lunar.earthly.dev/release-notes/product/2026.md) - [2025](https://docs-lunar.earthly.dev/release-notes/product/2025.md) - [Self-hosted](https://docs-lunar.earthly.dev/release-notes/self-hosted.md) - [2026](https://docs-lunar.earthly.dev/release-notes/self-hosted/2026.md) - [CLI and CI/CD Tracer](https://docs-lunar.earthly.dev/release-notes/cli.md) - [2026](https://docs-lunar.earthly.dev/release-notes/cli/2026.md) - [2025](https://docs-lunar.earthly.dev/release-notes/cli/2025.md) - [Policy Python SDK](https://docs-lunar.earthly.dev/release-notes/python-sdk.md) - [2026](https://docs-lunar.earthly.dev/release-notes/python-sdk/2026.md) - [2025](https://docs-lunar.earthly.dev/release-notes/python-sdk/2025.md) --- # 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 This site has an agentic ask interface you may use to query the documentation dynamically 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/index.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.