components

Define the components section of lunar-config.yml — repositories or monorepo subdirectories that Lunar monitors with metadata and tags.

• lunar-config.yml -> components

• Type: object

• Form:

  components:
    <component-name>: <component-object>
    <component-name>: <component-object>
    ...

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:<component-id>. 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 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:

lunar-config.yml

components:
  github.com/my-org/my-repo:
    owner: [e-mail]
    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: [e-mail]
    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: [e-mail]
    domain: ui-common
    tags: [react, typescript]

Component

• lunar-config.yml -> components.<component-name>

• Type: object

• Form:

  owner: <email>
  domain: <domain-path>
  branch: <branch-name>
  tags: [<tag>, <tag>, ...]
  ciPipelines: [<ci-pipeline>, <ci-pipeline>, ...]
  description: <description>
  paths: [<path>, <path>, ...]
  meta:                          # 🚧 Coming Soon
    <meta-key>: <meta-value>
    <meta-key>: <meta-value>
    ...

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.<component-name>. For more information, see the lunar.yml page.

owner

• lunar-config.yml -> components.<component-name>.owner

• Type: string

• Optional

The email address of the owner of the component.

domain

• lunar-config.yml -> components.<component-name>.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:<domain-name>. See Tag Matching with on for more details on how to use these tags.

branch

• lunar-config.yml -> components.<component-name>.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.<component-name>.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.<component-name>.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.<component-name>.description

• Type: string

• Optional

A description of the component.

paths

• lunar-config.yml -> components.<component-name>.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 <subdir>/* pattern automatically.

meta 🚧 Coming Soon

• lunar-config.yml -> components.<component-name>.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 and 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.

.github/workflows/ci.yml

jobs:
  build-api:
    env:
      LUNAR_COMPONENT: "services/api,services/worker"

LUNAR_COMPONENT_INFER

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. Behavior may change.

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 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.

.github/workflows/ci.yml

jobs:
  build:
    env:
      LUNAR_COMPONENT_INFER: "true"

Precedence

LUNAR_COMPONENT (explicit) and 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.