# Trigger Manifests

LLMS index: [llms.txt](https://hummingbird-project.io/llms.txt) | Full content: [llms-full.txt](https://hummingbird-project.io/llms-full.txt)

---

Trigger manifests are declarative JSON files committed alongside each
Hummingbird source repo. They map changed file paths to the Konflux build
PipelineRuns expected to fire, and list the IntegrationTestScenario CRs
expected to run after a successful build. The
[workqueue service](https://hummingbird-project.io/l/workqueue-service)
reads them to compute build and test expectations for open MRs; any other
tooling that needs expectations can read the same files.

The same manifest concept is generated by the containers, tools, and rpms
repos.

## Location

Each repo carries two manifests:

- `.tekton/trigger-manifest-pull-request.json` — PR (pre-merge) event
- `.tekton/trigger-manifest-push.json` — push (post-merge) event

Both are kept committed and regenerated by the repo's own generator:

- **tools** — `ci/internal/render_template.py` (`make all`)
- **containers** — `ci/internal/generate_pac_resources.sh`
  (`make global-resources`, which is also a prerequisite of `make all-host`)
- **rpms** — `ci/generate_resources.py` (`make generate-host`, or
  `make generate` to run inside the build container)

The `tree_status` CI job enforces that the committed files match the
generator output on every pipeline, so the files are always fresh.

## Schema

Both manifests share the same top-level structure:

```json
{
  "type": "push",
  "excludes": [],
  "applications": { ... },
  "integration_test_scenarios": { ... }
}
```

### `type`

String. Either `"push"` or `"pull_request"`. Identifies which event class
the manifest covers.

### `excludes`

Array of path regex strings. Any changed path matching one of these
patterns suppresses triggering entirely, regardless of the `applications`
section. Tools and rpms carry an empty array; containers carries exclusion
patterns for image-documentation files (e.g. `README.md.j2`, `report.yml`,
`Containerfile.j2`, `properties.yml`) that do not affect builds.

### `applications`

Object keyed by Konflux application name. Each value is an object keyed by
component name, whose value is an array of path regex strings:

```json
"applications": {
  "tools": {
    "workqueue-service--tools": ["^workqueue-service/"],
    "hummingbird-agent--tools": [
      "^hummingbird-agent/",
      "^hummingbird-ai/",
      "^hummingbird-sandbox/"
    ]
  }
}
```

A component is considered _affected_ by a commit when at least one of its
trigger regexes matches at least one changed path. An application with no
affected components produces no build expectations for that commit.

### `integration_test_scenarios`

Object keyed by application name. Present in a manifest only when the repo
has integration-test scenarios applicable to that event type; an absent key
is treated as "no test expectations" by consumers (backward-compatible with
old SHAs before scenarios were added).

Concretely: the push manifest carries `integration_test_scenarios` only
when the repo has `component`-context scenarios (they fire on individual
component snapshots post-merge). Tools defines one such scenario
(`conforma`), so its push manifest includes the section. Rpms defines
scenarios but all are `pull_request`-context, so its push manifest has no
`integration_test_scenarios` key. Containers currently defines no
scenarios, so neither manifest includes the section.

The shape differs between the two manifests:

**PR manifest** (`.tekton/trigger-manifest-pull-request.json`):

```json
"integration_test_scenarios": {
  "tools": [
    { "name": "tools-conforma", "group": false },
    { "name": "tools-k8s-test", "group": true }
  ]
}
```

**Push manifest** (`.tekton/trigger-manifest-push.json`):

```json
"integration_test_scenarios": {
  "tools": [{ "name": "tools-conforma" }]
}
```

Each entry:

| Field   | Type    | Present in     | Meaning                                                                                                                                                          |
| ------- | ------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`  | string  | both manifests | The IntegrationTestScenario CR name. Matches the `test.appstudio.openshift.io/scenario` label on test PipelineRuns.                                              |
| `group` | boolean | PR only        | `true` for `pull_request`-context scenarios, which also trigger a group-snapshot run when ≥2 components are affected. `false` for `component`-context scenarios. |

Scenarios marked `optional: true` in `konflux-templates/scenarios.yml` are
excluded from both manifests. `component`-context scenarios appear in both
manifests (they fire on individual component snapshots). `pull_request`-context
scenarios appear only in the PR manifest (no group snapshots exist
post-merge).

## Consumer semantics

For each application with ≥1 affected component, every listed scenario must
have ≥1 observed test PipelineRun and all observed runs must be green. For
`group: true` entries, an additional group-snapshot run is required when
the application has ≥2 affected components. Scenario names are matched
against the `test.appstudio.openshift.io/scenario` labels on test
PipelineRuns.

See the [workqueue service documentation](https://hummingbird-project.io/l/workqueue-service) for the
full consumer-side implementation.

## Generation

### `scenarios.yml` schema

Each repo that owns IntegrationTestScenario CRs carries a
`konflux-templates/scenarios.yml` matrix file. This is the canonical schema
documentation — the file itself carries no inline comments (it is
machine-managed via PyYAML round-trip; this page is the schema reference).

```yaml
applications:
  <application>:
    - template: <type>
      suffix: <name>
      triggers:
        - pull_request
        - component
      optional: true
      vars:
        KEY: value
```

Entry fields:

| Field      | Required | Description                                                                                                                                                      |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template` | yes      | Scenario type. Maps to `scenarios/<template>.yml.j2` and becomes the CR name suffix: `<application>-<template>`.                                                 |
| `suffix`   | no       | CR-name override. When set, CR name = `<application>-<suffix>` instead of `<application>-<template>`.                                                            |
| `triggers` | yes\*    | Konflux trigger context names (`pull_request`, `component`). Unknown or empty values on non-optional entries fail the generator. \*Optional entries may omit it. |
| `optional` | no       | If `true`, the scenario is excluded from both trigger manifests.                                                                                                 |
| `vars`     | no       | Per-instance param overrides passed to the template, rendered after the template's default params.                                                               |

All CR content — `params`, `resolverRef`, Renovate markers, timeout
annotations — lives in the per-type template file
(`konflux-templates/scenarios/<template>.yml.j2`). The matrix holds only
the instantiation relationships: application × template × triggers ×
overrides. Unknown or empty triggers on non-optional entries cause the
generator to fail hard, so the manifests are always consistent with the
deployed IntegrationTestScenario CRs.

### Component-to-path mappings

The component-to-path mappings in the `applications` section are derived
differently per repo:

- **tools** — each component's `Containerfile` location, with an optional
  `.build-context` override file for extra trigger paths.
- **containers** — `images/*/properties.yml` files aggregated with shared
  configuration from `images/variables.yml` (distros, variants, hermetic
  settings).
- **rpms** — `rpms/<package>/` directories, with PR-time additions from
  `test/rpms/<package>.yml` per-package test specs.

To regenerate both manifests after editing `scenarios.yml` or adding a
component:

```shell
make all
```
