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

On GitLab, the name includes the full namespace, so nested subgroups become part of it — gitlab.com/my-group/platform/my-project. A monorepo subdirectory is separated from the project path by GitLab's own /-/ marker, which is what keeps the subdirectory distinguishable from another subgroup:

components:
  gitlab.com/my-group/my-project:                     # a project
  gitlab.com/my-group/platform/my-project:            # a project in a subgroup
  gitlab.com/my-group/my-monorepo/-/services/api:     # a subdirectory of a monorepo
  gitlab.com/my-group/ui-*:                           # every project in my-group whose path starts with ui-

A GitLab wildcard matches projects directly inside the named group — it does not descend into subgroups. gitlab.com/my-group/* will not match gitlab.com/my-group/platform/api; name the subgroup explicitly (gitlab.com/my-group/platform/*) to cover it.

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:
      "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:
    <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, including which runs fire its after-ci-pipeline collectors. 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.

For PR readiness, GitHub Actions runs triggered by workflow_dispatch, schedule, or repository_dispatch are ignored unless they supply CI collection data for the component or their workflow name matches ciPipelines. Add a workflow name here if its manual runs should also gate the PR. Runs with an unknown trigger and branch/release readiness retain their existing behavior.

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

• lunar-config.yml -> components.<component-name>.meta
• Type: object
• Optional

A key-value store of arbitrary metadata for the component. Lunar does not interpret these values, but surfaces them to collectors and policies as the LUNAR_COMPONENT_META environment variable (a JSON object, set only when the component has metadata). Metadata can be declared here in lunar-config.yml or emitted by a cataloger.

CI → component attribution

When the Lunar CI Tracer 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. The tracer reads them from the job's own checkout with git, fetching the comparison's other end from origin with the credentials the checkout persisted (the actions/checkout default), so no GitHub token is needed. On pull requests the comparison is the base branch against the merge commit the job checks out; on pushes, the commit range. A step that runs before the checkout exists — or a run with no range to compare, such as a new branch, a tag, or a scheduled run — falls through to the next rule.
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.