# collectors * `lunar-config.yml -> collectors` * Type: `array` * Form: ```yaml collectors: - - - ... ``` Collectors are used to collect live information from various sources to associate with individual components. Example collectors definition: {% code title="lunar-config.yml" %} ```yaml collectors: - uses: github://third-party/some-collector@v1 on: [auth, frontend] hook: type: ci-before-command pattern: ^go build.* - uses: ./my-collector on: ["domain:my-domain"] hook: type: ci-before-job pattern: .* - uses: ./my-collector on: ["domain:foo-product"] hook: type: code - uses: ./another-collector on: [go] hook: type: cron schedule: "0 2 * * *" - name: Hello world collector runBash: lunar collect '.hello' world on: [java] hook: type: ci-after-command pattern: ^mvn install.* - name: Example script collector mainBash: ./my-script.sh on: [python] hook: type: cron schedule: "0 2 * * *" ``` {% endcode %} ## Collector * `lunar-config.yml -> collectors.` * Type: `object` * Forms * Uses form (use an external collector plugin): ```yaml name: description: uses: include: exclude: with: : ... on: runs_on: image: ``` * Run form (define a collector inline): ```yaml name: description: run: on: runs_on: image: hook: hooks: - - - ... ``` * Main form (define a collector inline with a main file): ```yaml name: description: main: on: runs_on: image: hook: hooks: - - - ... ``` Collectors are used to collect live information from various sources to associate with individual components. Collectors can be used to instrument CI/CD pipelines, run cron jobs, or execute arbitrary logic when code changes. Collectors can either be imported (Uses form), defined as an inline command (Run form), or defined as a script to run (Main form). When a collector is defined inline (Run and Main forms), a hook must be specified to determine when the collector should run. ### `name` * `lunar-config.yml -> collectors..name` * Type: `string` * Required for Run and Main collector forms, Optional for Uses collector form The `name` field is used to specify the name of the collector. If a name is not provided in the case of a collector plugin, the name from the collector plugin is used. The name must be unique within the configuration. ### `description` * `lunar-config.yml -> collectors..description` * Type: `string` * Optional A description of the collector. This is used to describe the purpose of the collector in the Lunar UI and logs. ### `uses` * `lunar-config.yml -> collectors..uses` * Type: `string` * Forms * GitHub form: `github:///@` * Local form: `./` * Required in Uses collector form The `uses` field specifies an external (plugin) collector to use. The collector can be a third-party collector, or a local collector defined in a subdirectory. Browse the [30+ available integrations](https://earthly.dev/lunar/integrations/) to find collectors for your tools. ### `with` * `lunar-config.yml -> collectors..with` * Type: `object` * Optional The `with` field specifies the inputs to pass to the collector plugin. The inputs are defined in the collector's configuration file. Input values are available to collector scripts as `LUNAR_VAR_*` environment variables. Plugin authors can also reference inputs in their plugin YAML definitions using the `${{ inputs.NAME }}` syntax. This allows plugins to expose configurable fields -- such as hook parameters -- as explicit settings. See [collector plugins](/plugin-sdks/plugins/collector-plugins.md#inputs) for details. ### `include` * `lunar-config.yml -> collectors..include` * Type: `array` * Optional The `include` field specifies which subcollectors to include from an imported collector plugin. When a collector is imported via `uses`, it may define (or import) multiple subcollectors. Use `include` to control which of those subcollectors are used. If neither `include` nor `exclude` is specified, all subcollectors are included by default. ### `exclude` * `lunar-config.yml -> collectors..exclude` * Type: `array` * Optional The `exclude` field specifies which subcollectors to exclude from an imported collector plugin. Use `exclude` when you want to include most subcollectors but skip a few specific ones. If neither `include` nor `exclude` is specified, all subcollectors are included by default. For example, if a collector called `go` includes subcollectors named `version`, `dependencies`, and `build-info`: {% code title="lunar-config.yml" %} ```yaml collectors: # Include only the version subcollector - uses: ./dir/go include: [version] # Include all except version - uses: ./dir/go exclude: [version] # Include version and dependencies only - uses: ./dir/go include: [version, dependencies] ``` {% endcode %} ### `run` * `lunar-config.yml -> collectors..run` * Type: `string` * Required in Run collector form Defines the command to execute when the collector is invoked. Only `Bash` and `Python` are supported. So `runBash` and `runPython` are the only valid fields. Running Bash supports [installing dependencies](/plugin-sdks/bash-sdk/dependencies.md). #### `runBash` * `lunar-config.yml -> collectors..runBash` * Type: `string` The `runBash` field specifies the bash collector script to run. #### `runPython` * `lunar-config.yml -> collectors..runPython` * Type: `string` The `runPython` field specifies the python collector script to run. Running Python supports [installing dependencies](/plugin-sdks/python-sdk/dependencies.md). ### `main` * `lunar-config.yml -> collectors..main` * Type: `string` * Required in Main collector form Defines the main file path used to execute when the collector is invoked. Only `Bash` and `Python` are supported. So `mainBash` and `mainPython` are the only valid fields. The file path is relative to the root of the Lunar configuration repository. In the case of an external plugin definition, the path is relative to the plugin directory. Running Bash supports [installing dependencies](/plugin-sdks/bash-sdk/dependencies.md). #### `mainBash` * `lunar-config.yml -> collectors..mainBash` * Type: `string` The `mainBash` field specifies the path to the bash main file to run. #### `mainPython` * `lunar-config.yml -> collectors..mainPython` * Type: `string` The `mainPython` field specifies the path to the python main file to run. Running Python supports [installing dependencies](/plugin-sdks/python-sdk/dependencies.md). ### `on` * `lunar-config.yml -> collectors..on` * Type: `array` * Required The `on` field specifies the tags that the collector should be associated with. The collector will only run when the component has one or more of the specified tags. For detailed documentation on tag matching syntax, including domain/component targeting, expressions, and cross-references to other collectors or policies, see [Tag Matching with `on`](/configuration/lunar-config/on.md). ### `runs_on` * `lunar-config.yml -> collectors..runs_on` * Type: `array` * Optional * Default: `[prs, default-branch]` Specifies the contexts in which the collector should run. The available values are: * `prs` - the collector will run on pull requests * `default-branch` - the collector will run on the default branch By default, collectors run in both contexts. To restrict a collector to only run on pull requests, use `runs_on: [prs]`. To restrict a collector to only run on the default branch, use `runs_on: [default-branch]`. ### `hook` * `lunar-config.yml -> collectors..hook` * Type: `object` * One of `hook` or `hooks` is required in Run collector form Using `hook` is equivalent to using a single hook in the `hooks` field. The `hook` field specifies when the collector should run. For more information about hook definitions see the [hooks configuration page](/configuration/lunar-config/collector-hooks.md). ### `hooks` * `lunar-config.yml -> collectors..hooks` * Type: `array` * One of `hook` or `hooks` is required in Run collector form The `hooks` field specifies when the collector should run. For more information about hook definitions see the [hooks configuration page](/configuration/lunar-config/collector-hooks.md). ### `image` * `lunar-config.yml -> collectors..image` * Type: `string` * Optional The `image` field specifies the Docker image to use when running the collector. When set, the collector runs inside a container instead of natively on the host. Use the special value `native` to explicitly run the collector without a container, even when a default image has been configured. Example: {% code title="lunar-config.yml" %} ```yaml collectors: # Run in a container - runBash: lunar collect .file-count "$(find . | wc -l)" image: earthly/lunar-scripts:1.0.0 hook: type: code on: [my-tag] # Run natively (override any default image) - runBash: lunar collect .ci-info "$CI_JOB_ID" image: native hook: type: ci-before-command pattern: ^.* on: [my-tag] ``` {% endcode %} For more information about default images and container execution, see [Images](/configuration/lunar-config/images.md). --- # Agent Instructions: 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: ``` GET https://docs-lunar.earthly.dev/configuration/lunar-config/collectors.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.