Artefact Enumerator¶

The Artefact Enumerator extension is a cronjob which regularly creates backlog work-items for tracked OCM components. It monitors specified components and versions, creating work for other extensions to process.

Configuration Example¶

artefact_enumerator:
  compliance_snapshot_grace_period: 86400  # 24 hours
  schedule: '*/5 * * * *'                   # every 5 minutes
  successful_jobs_history_limit: 1
  failed_jobs_history_limit: 1
  components:
    - component_name: ocm.software/open-delivery-gear
      version: greatest               # or specific version like '0.1.0'
      max_versions_limit: 1
    - component_name: acme.org/my-component
      version:
        source:
          type: github
          repo: github.com/acme/my-repo
          relpath: [VERSION]
          ref: main
          postprocess: false
      ocm_repo_url: https://my-ocm-repo.example.com
      max_versions_limit: 3

Top-Level Options¶

Option	Type	Default	Description
`compliance_snapshot_grace_period`	int (seconds)	`86400`	Grace period for compliance snapshots before triggering re-evaluation.
`schedule`	string	`/5 * * *`	Cron schedule for running the cronjob (every 5 minutes by default).
`successful_jobs_history_limit`	int	`1`	Number of successful job executions to retain in history.
`failed_jobs_history_limit`	int	`1`	Number of failed job executions to retain in history.
`components`	list	`[]`	List of OCM components to track. See component fields below.

Component Fields¶

Each entry in the components list supports the following fields:

Option	Type	Required	Description
`component_name`	string	yes	Name of the OCM component (e.g., `ocm.software/open-delivery-gear`).
`version`	string or object	yes	Component version. Use `greatest` or `null` for latest, a specific version string, or a source object to read from GitHub.
`ocm_repo_url`	string	no	Override the default OCM repository lookup via `ocm_repo_mappings`.
`max_versions_limit`	int	`1`	Number of versions that should be tracked for this component.

Version Source Fields¶

When version is an object with a source key, it supports:

Option	Type	Required	Description
`source.type`	string	yes	Type of version location. Currently supports `github`.
`source.repo`	string	yes	GitHub repository name (e.g., `github.com/org-name/repo-name`).
`source.relpath`	list	yes	Relative path from repository root to the version file. Can include submodule specifications.
`source.ref`	string	no	Repository reference (branch, tag, or commit hash). Defaults to the default branch.
`source.postprocess`	bool	`false`	If true, appends the current commit SHA to the version (`{version}-{sha}`).

Configuration Details¶

`compliance_snapshot_grace_period`¶

The grace period (in seconds) before a compliance snapshot triggers re-evaluation of components. Default is 86400 seconds (24 hours). This prevents excessive re-processing when compliance status hasn’t meaningfully changed.

`schedule`¶

The cron schedule expression that determines when the Artefact Enumerator cronjob runs. Default is */5 * * * * (every 5 minutes).

Common schedule patterns:

# Every 5 minutes (default)
schedule: '*/5 * * * *'

# Every 10 minutes
schedule: '*/10 * * * *'

# Every hour
schedule: '0 * * * *'

# Every 30 minutes
schedule: '*/30 * * * *'

`successful_jobs_history_limit`¶

Number of successful cronjob executions to retain in Kubernetes history. Default is 1. This controls how many completed job pods are kept for auditing and debugging purposes.

`failed_jobs_history_limit`¶

Number of failed cronjob executions to retain in Kubernetes history. Default is 1. This controls how many failed job pods are kept for troubleshooting purposes.

`components`¶

List of OCM components that ODG should track and process. Each component generates backlog work-items that trigger scans and assessments by other extensions.

Version Specification¶

The version field supports three formats:

Latest version - use greatest or null:
```
version: greatest
```
Specific version - use a version string:
```
version: 0.1.0
```

Dynamic version from GitHub - read version from a file in a GitHub repository:

version:
  source:
    type: github
    repo: github.com/acme/my-repo
    relpath: [VERSION]
    ref: main
    postprocess: false

Version from GitHub with Submodules¶

For repositories with submodules, specify the submodule path in the relpath list:

version:
  source:
    type: github
    repo: github.com/org-name/repo-name
    relpath:
      - type: submodule
        name: path/to/submodule
      - path/to/version-file
    ref: main

`max_versions_limit`¶

Specifies how many historical versions of a component should be tracked and processed. Setting this to a higher value allows tracking findings across multiple component versions, which is useful for understanding trends and ensuring older versions meet compliance requirements.

Examples:

max_versions_limit: 1 - track only the latest version
max_versions_limit: 3 - track the three most recent versions