> 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/components.md). # components * `lunar-config.yml -> components` * Type: `object` * Form: ```yaml components: : : ... ``` Components are the individual units of code that are monitored by Lunar. They represent a complete software deliverable, such as a microservice, binary, or a library. Components can be an entire repository, or a subdirectory within a repository in the case of monorepos. The name of a component is the repository URL or a pattern that matches multiple repositories. For example, `github.com/my-org/my-repo` or `github.com/my-org/*`. Each component automatically receives the special tag `component:`. For example, the component `github.com/my-org/my-repo` will receive the tag `component:github.com/my-org/my-repo`. This tag can be used in [tag matching expressions](/configuration/lunar-config/on.md) to target specific components. Components can be defined here, in the Lunar configuration file, or in a separate file, `lunar.yml`, in the root of the component directory. Both definitions can co-exist, complementing each other (some components can be defined centrally in `lunar-config.yml`, while others can be defined via `lunar.yml`). Example components definition: {% code title="lunar-config.yml" %} ```yaml components: github.com/my-org/my-repo: owner: jane@example.com domain: widget-product.frontend branch: prod tags: [go, backend, pii] github.com/my-org/my-monorepo/*: tags: [tier1] github.com/my-org/my-monorepo/proj1: owner: jacqueline@example.com domain: widget-product.data-processing tags: [java, backend] meta: # 🚧 Coming Soon "pagerduty-escalation-policy": "P1" github.com/my-org/ui-*: tags: [frontend] github.com/my-org/ui-components: owner: jack@example.com domain: ui-common tags: [react, typescript] ``` {% endcode %} ## Component * `lunar-config.yml -> components.` * Type: `object` * Form: ```yaml owner: domain: branch: tags: [, , ...] ciPipelines: [, , ...] description: paths: [, , ...] meta: # 🚧 Coming Soon : : ... ``` A single component is a unit of code that is monitored by Lunar. It represents a complete software deliverable, such as a microservice, binary, or a library. As an alternative to defining components in `lunar-config.yml`, they may also be defined in a separate file, `lunar.yml`, in the root of the component directory. The fields in `lunar.yml` are the same as those in `lunar-config.yml -> components.`. For more information, see the [lunar.yml](/configuration/lunar-yml.md) page. ### `owner` * `lunar-config.yml -> components..owner` * Type: `string` * Optional The email address of the owner of the component. ### `domain` * `lunar-config.yml -> components..domain` * Type: `string` * Optional A component can only belong to one domain. This field specifies the domain that the component belongs to. To associate a component with a subdomain, specify the entire domain path. For example, to associate a component with the domain `bar`, which is under the domain `foo`, use the domain `foo.bar`. If a domain is not specified, the component is placed in the `other` domain. When a component is associated with a domain, it automatically gets the tag `domain:`. See [Tag Matching with `on`](/configuration/lunar-config/on.md) for more details on how to use these tags. ### `branch` * `lunar-config.yml -> components..branch` * Type: `string` * Optional The branch that the component is monitored on. If not specified, the default branch is used. ### `tags` * `lunar-config.yml -> components..tags` * Type: `array` * Optional A list of tags that to apply to the component. Tags can be used to associate collectors and policies to specific components. ### `ciPipelines` * `lunar-config.yml -> components..ciPipelines` * Type: `array` * Optional - defaults to all CI pipelines in the repository A list of CI pipeline names that are associated with the component. The CI pipelines are used to trigger the collection of data for the component. A single CI pipeline may be associated with multiple components at a time. If no CI pipelines are specified, then all CI pipelines within the repository are associated with the component. This setting can be useful in monorepos, when certain CI pipelines might not be relevant to a specific component. The pipeline name in GitHub Actions is the name of the GitHub Actions **workflow** — the `name:` field of the workflow file (exposed as `GITHUB_WORKFLOW`), not an individual job. In Buildkite, it is the name of the Buildkite pipeline. ### `description` * `lunar-config.yml -> components..description` * Type: `string` * Optional A description of the component. ### `paths` * `lunar-config.yml -> components..paths` * Type: `array` * Optional A list of paths within the repository that are associated with the component. This is useful in monorepo setups to specify which subdirectories belong to a given component. Paths are matched against each changed file path. An entry ending in `*` is a **prefix match** — `services/api/*` matches any file at or under `services/api/` — while an entry without a trailing `*` must equal the changed path **exactly** (e.g. `go.mod`). Only a single trailing `*` is honored; full globs such as `**` are **not** supported. A component named after a monorepo subdirectory also gets an implicit `/*` pattern automatically. ### `meta` 🚧 Coming Soon * `lunar-config.yml -> components..meta` * Type: `object` * Optional A key-value store of arbitrary metadata for the component. This metadata is not used by Lunar, but can be used by collectors and policies. ## CI → component attribution When the Lunar CI agent traces a CI run, it attributes the facts it collects to one or more components. In a monorepo, a single repository contains many components, so a CI run usually needs to map to a specific subdirectory component. Attribution is controlled by environment variables set in your CI workflow, together with the [`ciPipelines`](#cipipelines) and [`paths`](#paths) settings above. ### `LUNAR_COMPONENT` Explicitly names the component(s) a CI run belongs to. Use a comma-separated list to attribute a single run to multiple components at once. Each entry is either: * **repo-relative** — the subdirectory path, e.g. `services/api`; or * **absolute** — the full component name, e.g. `github.com/my-org/my-monorepo/services/api`. {% code title=".github/workflows/ci.yml" %} ```yaml jobs: build-api: env: LUNAR_COMPONENT: "services/api,services/worker" ``` {% endcode %} ### `LUNAR_COMPONENT_INFER` {% hint style="warning" %} **Experimental.** Automatic inference is best-effort and has known cases where it can't resolve a component reliably — ambiguous or empty changed-path matches, working directories that don't map cleanly to a single component, and similar. For dependable attribution, prefer explicit `LUNAR_COMPONENT` or [`ciPipelines`](#cipipelines). Behavior may change. {% endhint %} Set to `true` to let the agent infer the component(s) automatically instead of naming them. Inference resolves in this order: 1. **Changed paths** — components whose [`paths`](#paths) intersect the files changed by the commit or pull request. (On pull requests the changed files come from the PR; on pushes, from the commit range.) 2. **Working directory** — if no changed paths match, the component whose subdirectory contains the traced command's working directory. {% code title=".github/workflows/ci.yml" %} ```yaml jobs: build: env: LUNAR_COMPONENT_INFER: "true" ``` {% endcode %} ### Precedence `LUNAR_COMPONENT` (explicit) and [`ciPipelines`](#cipipelines) (workflow-name match) take precedence. `LUNAR_COMPONENT_INFER` is only consulted when neither of those selects a component. If nothing matches, the run is attributed to the repository-level component, when one is defined. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs-lunar.earthly.dev/configuration/lunar-config/components.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.