> 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/configuration/lunar-config.md). # lunar-config.yml Reference for lunar-config.yml — the central configuration file defining hub connection, catalogers, domains, components, collectors, initiatives, and policies. * `lunar-config.yml` * Type: YAML file * Form: ```yaml version: 0 default_image: default_image_ci_collectors: default_image_non_ci_collectors: default_image_policies: default_image_catalogers: image_replace: - from_pattern: to: - ... hub: host: grpcPort: httpPort: insecure: bypass: max_duration: require_reason: authorization: permissions: : github_role: gitlab_role: ... customization: bypass_template: bypass_revocation_template: checks_template: ok_release_template: pr_comments: mode: bypass_hint: pr: release: catalogers: - - - ... domains: : : ... components: : : ... collectors: - - - ... initiatives: - - - ... policies: - - - ... uiPanels: : ... ``` The file `lunar-config.yml` is used to configure the behavior of Lunar. {% hint style="info" %} It is recommended that you create a new code repository for all Lunar configuration and place this file in the root of it. {% endhint %} At a high-level, the file contains information about how the Lunar primitives are configured, ranging from how information is collected from the SDLC via collectors, to how components are organized into domains, and how the health of components is evaluated via policies. ## Splitting the configuration A single `lunar-config.yml` works well and is the typical setup. If you'd prefer to spread a larger configuration across several files — for example, one per team — you can: any `*.yml` / `*.yaml` files placed in a `lunar-config.d/` directory next to `lunar-config.yml` are merged into it, in lexical filename order. ``` lunar-config.yml # version, hub, default images lunar-config.d/ collectors.yml team-frontend.yml team-backend.yml ``` The fragment directory is named after the entry point, with the extension replaced by `.d` — so a [non-default entry point](/docs/lunar-cli.md#repo) such as `lunar-config.dev.yml` reads `lunar-config.dev.d/`, and never the default's fragments. `lunar-config.yml` stays the entry point and holds the singleton fields (`version`, `hub`, `bypass`, `authorization`, `customization`, `default_image*`, `image_replace`); each fragment contributes additional sections. List sections (`collectors`, `policies`, …) are concatenated; map sections (`domains`, `components`, `uiPanels`) are unioned by key, and a key defined in more than one place is an error rather than a silent override. ## `version` * `lunar-config.yml -> version` * Type: `string` * Required The version field is used to specify the version of the configuration file. The current version is `0`. ## Default Images * `lunar-config.yml -> default_image*` * Optional These fields configure the default Docker images used to run collectors, policies, and catalogers. When set, scripts will run inside containers instead of natively on the host. A common configuration is: {% code title="lunar-config.yml" %} ```yaml default_image: earthly/lunar-scripts:1.0.0 default_image_ci_collectors: native ``` {% endcode %} This runs most scripts in containers while keeping CI collectors native for direct access to CI environments. For detailed documentation on default images, image resolution order, and the official `earthly/lunar-scripts` image, see [Images](/configuration/lunar-config/images.md). ## `image_replace` * `lunar-config.yml -> image_replace` * Type: `list` * Optional Find/replace rules applied to image references after they are resolved, for pointing images at an internal registry mirror: {% code title="lunar-config.yml" %} ```yaml image_replace: - from_pattern: ^earthly/ to: 111122223333.dkr.ecr.us-east-1.amazonaws.com/docker.io/earthly/ ``` {% endcode %} See [Images](/configuration/lunar-config/images.md#rewriting-image-references) for the matching rules and caveats. ## `hub` * `lunar-config.yml -> hub` * Type: `object` * Required The `hub` object contains configuration for the Lunar Hub server. ### `host` * `lunar-config.yml -> hub.host` * Type: `string` * Required The host field is used to specify the host of the Lunar Hub server. E.g. `hub.example.com`. ### `grpcPort` * `lunar-config.yml -> hub.grpcPort` * Type: `integer` * Required The grpcPort field is used to specify the port of the Lunar Hub server for GRPC connections. ### `httpPort` * `lunar-config.yml -> hub.httpPort` * Type: `integer` * Required The httpPort field is used to specify the port of the Lunar Hub server for HTTP connections. ### `insecure` * `lunar-config.yml -> hub.insecure` * Type: `boolean` * Optional * Default: `false` The insecure field is used to specify whether to use insecure HTTP connections to the Lunar Hub server. ## `bypass` * `lunar-config.yml -> bypass` * Type: `object` * Optional The `bypass` object bounds the [`lunar policy bypass-pr` / `bypass-release`](/docs/lunar-cli.md#bypassing-a-block) commands. {% code title="lunar-config.yml" %} ```yaml bypass: max_duration: 3d require_reason: true ``` {% endcode %} ### `max_duration` * `lunar-config.yml -> bypass.max_duration` * Type: `string` * Optional * Default: `14d` The longest a single bypass may last. This caps `--for`, and is also what an omitted `--for` resolves to, so no bypass is ever open-ended. Accepts Go's duration grammar extended with `d` (24 hours) and `w` (7 days) units, mixable: `36h`, `3d`, `2w`, `1w2d`. A malformed or non-positive value is rejected when the configuration is loaded, rather than when someone next tries to create a bypass. A `--for` above the cap is rejected. The cap applies to a single bypass, not to a sequence of them: renewing an expired bypass is the intended pattern. ### `require_reason` * `lunar-config.yml -> bypass.require_reason` * Type: `boolean` * Optional * Default: `true` Whether `--reason` is mandatory when creating a bypass. Set it to `false` only if the justification is being recorded somewhere else. ## `authorization` * `lunar-config.yml -> authorization` * Type: `object` * Optional The `authorization` object overrides the Git platform role required by a Hub permission. {% code title="lunar-config.yml" %} ```yaml authorization: permissions: bypasses.manage: { github_role: write, gitlab_role: developer } ``` {% endcode %} Overrides take effect at the next `lunar hub pull`. Inspect them with `lunar hub permissions`. A raise above `maintain` / `Maintainer` still binds [configuration repository administrators](/docs/authorization.md#config-repo-administrators) on the configuration repository itself. `bypasses.manage` also governs the [`/lunar bypass` comment commands](/docs/pr-comments.md#authorization), so one override moves the CLI and the thread together. ### `permissions` * `lunar-config.yml -> authorization.permissions` * Type: `object` * Optional A map from [permission name](/docs/authorization.md#permissions) to `github_role` (`read`, `triage`, `write`, `maintain`, `admin`) and/or `gitlab_role` (`guest`, `reporter`, `developer`, `maintainer`, `owner`). Unknown permissions, unknown roles, and roles below the permission's access floor are rejected. ## `customization` * `lunar-config.yml -> customization` * Type: `object` * Optional The `customization` object controls optional changes to Lunar's presentation and behavior. For available fields, see [customization](/configuration/lunar-config/customization.md). ## `catalogers` * `lunar-config.yml -> catalogers` * Type: `array` * Optional Catalogers are used to synchronize software catalog information (such as domains, and components) with external systems. For information on how to configure catalogers, see [catalogers](/configuration/lunar-config/catalogers.md). ## `domains` * `lunar-config.yml -> domains` * Type: `object` * Optional Domains are used to group related components together. Domains are hierarchical and can contain other domains. For information on how to configure domains, see [domains](/configuration/lunar-config/domains.md). ## `components` * `lunar-config.yml -> components` * Type: `object` * Optional Components are the units of code that Lunar monitors. A component can represent either a code repository, or a subdirectory in the case of a monorepo. Components are associated with domains and can have tags. Through the tagging system, components are associated with collectors, and policies. For information on how to configure components, see [components](/configuration/lunar-config/components.md). ## `collectors` * `lunar-config.yml -> collectors` * Type: `array` * Required Collectors are used to collect live information from various sources to associate with individual components. For information on how to configure collectors, see [collectors](/configuration/lunar-config/collectors.md). ## `initiatives` * `lunar-config.yml -> initiatives` * Type: `array` * Optional Initiatives are used to group components together. Initiatives are associated with domains and can have tags. For information on how to configure initiatives, see [initiatives](/configuration/lunar-config/initiatives.md). ## `policies` * `lunar-config.yml -> policies` * Type: `array` * Required Policies are used to define the rules that Lunar uses to evaluate the health of components. Policies are associated with domains and can be inherited by child domains. For information on how to configure policies, see [policies](/configuration/lunar-config/policies.md). ## `uiPanels` * `lunar-config.yml -> uiPanels` * Type: `object` * Optional UI panels define SQL-backed content for supported dashboard extension points. Each entry maps an extension-point ID to a panel file in the configuration repository. For information on how to configure UI panels, see [uiPanels](/configuration/lunar-config/uipanels.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 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/configuration/lunar-config.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.