Skip to content

Commit d352da1

Browse files
nickboldtcursoragent
authored and
johnmcollier
committed
docs(konflux-tekton-updates): document unified and 1.9 midstream layouts
Merge guidance from rhdh-1-rhel-9, rhdh-1.9-rhel-9, and rhdh-1.10-rhel-9 Konflux bump workflows: variant detection, shared build-pipeline migrations, regenerate steps, and local-commit-without-push workflow. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent fa73d32 commit d352da1

2 files changed

Lines changed: 127 additions & 27 deletions

File tree

‎skills/konflux-tekton-updates/SKILL.md‎

Lines changed: 31 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,10 @@ After a **minor** Konflux task tag bump, update `.tekton` pipelines and generato
3636
| Marker in repo | Read |
3737
|----------------|------|
3838
| `.tekton/generatePipelineRunsForPlugins.sh` | [references/plugin-catalog.md](references/plugin-catalog.md) |
39-
| `.tekton-templates/rhdh-pipeline.yaml` | [references/rhdh-midstream.md](references/rhdh-midstream.md) |
39+
| `.tekton-templates/rhdh-pipeline.yaml` | [references/rhdh-midstream.md](references/rhdh-midstream.md) — **variant A** (unified) |
40+
| `.tekton-templates/rhdh-hub.yaml` (no `rhdh-pipeline.yaml`) | [references/rhdh-midstream.md](references/rhdh-midstream.md) — **variant B** (1.9 shared build-pipeline) |
4041

41-
If both exist, apply changes for the repo you are working in.
42+
If both plugin-catalog and midstream markers exist, apply changes only for the repo/branch you are on.
4243

4344
## Workflow
4445

@@ -49,9 +50,10 @@ cd .tekton
4950
./updateDigests.sh --minor --no-push
5051
```
5152

52-
- Updates `tag@sha256` in `*.yaml` (and `.tekton-templates/*.yaml` in RHDH midstream).
53+
- Updates `tag@sha256` in `.tekton/*.yaml` and `.tekton-templates/*.yaml` (via `TEMPLATEPATH`).
54+
- On variant B, also updates `.tekton/build-pipeline-rhdh-*.yaml`.
5355
- Tag changes list `MIGRATION.md` URLs under `konflux-ci/build-definitions`.
54-
- Digest-only: `./updateDigests.sh --no-push -q`
56+
- Digest-only (no tag bump): `./updateDigests.sh --no-push -q`
5557

5658
Review `git diff` for `quay.io/konflux-ci/tekton-catalog/task-*` changes.
5759

@@ -60,35 +62,52 @@ Review `git diff` for `quay.io/konflux-ci/tekton-catalog/task-*` changes.
6062
For each URL from `updateDigests.sh` (or from the diff):
6163

6264
1. Read `MIGRATION.md`.
63-
2. Apply **only** documented user actions.
65+
2. Apply **only** documented user actions in templates and shared pipelines (see [references/rhdh-midstream.md](references/rhdh-midstream.md) for per-variant file list).
6466
3. Skip “no action required” sections.
6567

66-
### 3. Regenerate (optional)
68+
If PLRs still contain removed params (e.g. `dev-package-managers`) but templates are fixed, migrations are incomplete until step 3.
6769

68-
After fixing shared pipelines/templates and generator scripts:
70+
### 3. Regenerate PipelineRuns
6971

70-
- **plugin-catalog:** `./generatePipelineRunsForPlugins.sh -v <x.y.z> --nopush`
71-
- **RHDH midstream:** `./generatePipelineRuns.sh -t <x.y>`
72+
**Always run** after template or shared-pipeline migration edits (not optional when params changed):
73+
74+
```bash
75+
cd .tekton
76+
./generatePipelineRuns.sh -t <version>
77+
```
78+
79+
| Branch example | `-t` value | PLR suffix |
80+
|----------------|------------|------------|
81+
| `rhdh-1-rhel-9` | `1` | `rhdh-hub-1-push.yaml` |
82+
| `rhdh-1.9-rhel-9` | `1.9` | `rhdh-hub-1-9-push.yaml` |
83+
| `rhdh-1.10-rhel-9` | `1.10` | `rhdh-hub-1-10-push.yaml` |
84+
85+
- **Variant A:** also patch `rhdh-rag-content-<N>-{push,pull}.yaml` by hand (inline `pipelineSpec`, not generated).
86+
- **Variant B:** hub/operator PLRs regenerate from `rhdh-hub.yaml` / `rhdh-operator.yaml`; `build-pipeline-*.yaml` is edited directly, not by the generator.
87+
88+
Commit migration + regen locally when ready; do not push until human review.
7289

7390
### 4. Human review and push
7491

75-
Human reviews the full diff, then `git push` or opens a PR.
92+
Human reviews the full diff (digest commit plus any migration/regen commits), then `git push` or opens a PR.
7693

7794
## Known migration patterns
7895

7996
Use live `MIGRATION.md` as source of truth. Common cases:
8097

8198
| Task | Action |
8299
|------|--------|
83-
| `prefetch-dependencies-oci-ta` 0.2→0.3 | Remove `dev-package-managers`; add pipeline param `enable-package-registry-proxy` (default `"true"`) and pass to prefetch task |
84-
| `build-image-index` 0.2→0.3 | Remove `COMMIT_SHA` / `IMAGE_EXPIRES_AFTER` from **build-image-index** task only; keep `image-expires-after` on buildah/prefetch |
100+
| `prefetch-dependencies-oci-ta` 0.2→0.3 | Remove `dev-package-managers`; add pipeline param `enable-package-registry-proxy` (default `"true"`) and pass to prefetch task. Variant B: also add param on `build-pipeline-rhdh-{hub,operator}.yaml` tasks `prefetch-dependencies-hub` / `prefetch-dependencies-operator`, and on PLR `spec.params` in `rhdh-hub.yaml` / `rhdh-operator.yaml`. |
101+
| `build-image-index` 0.2→0.3 | Remove `COMMIT_SHA` / `IMAGE_EXPIRES_AFTER` from **build-image-index** task only; keep on buildah (`build-container`) and prefetch |
85102
| `init` 0.3→0.4 | No pipeline changes |
86103
| `init` 0.4.1→0.4.2 | Remove broken auto-added `sast-target-dirs` pipeline param if present |
87104

88105
## Anti-patterns
89106

90107
- Pushing without `--no-push` / `--nopush` and human sign-off.
91108
- Leaving removed task params (`dev-package-managers`, `COMMIT_SHA` on `build-image-index`).
109+
- Skipping `generatePipelineRuns.sh` after fixing templates while PLRs still reference old params.
110+
- Editing only PLRs when templates or `build-pipeline-*.yaml` are the source of truth.
92111
- Adding `verify_*` guards that fail on the next Konflux bump.
93112
- Dropping `image-expires-after` from PLRs only because `build-image-index` no longer uses it.
94113
- Hardcoding `1-` in `generatePipelineRunsForPlugins.sh` Containerfile comments; use `${RHDH_XY_VERSION}` so `1.10.0` becomes `1-10`, not `1`.

‎skills/konflux-tekton-updates/references/rhdh-midstream.md‎

Lines changed: 96 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,33 +2,114 @@
22

33
`updateDigests.sh` also updates `.tekton-templates/*.yaml` via `TEMPLATEPATH`.
44

5-
## Files to update
5+
Detect which variant applies **before** editing (see table below). Edit **templates and shared pipelines first**, then regenerate or patch PLRs.
66

7-
Edit **templates first**, then regenerate or patch PLRs.
7+
## Layout detection
8+
9+
| Marker | Variant | Typical branches |
10+
|--------|---------|------------------|
11+
| `.tekton-templates/rhdh-pipeline.yaml` | **Unified** — one `pipelineSpec` template + `components.yaml` | `rhdh-1-rhel-9`, `rhdh-1.10-rhel-9`, … |
12+
| `.tekton-templates/rhdh-hub.yaml` (no `rhdh-pipeline.yaml`) | **Shared build-pipeline** — PLR wrappers + `build-pipeline-rhdh-*.yaml` | `rhdh-1.9-rhel-9` |
13+
14+
If unsure, run: `ls .tekton-templates/rhdh-pipeline.yaml .tekton-templates/rhdh-hub.yaml 2>/dev/null`
15+
16+
---
17+
18+
## Variant A: Unified pipeline layout
19+
20+
Used on current stable branches. Hub, operator, and must-gather share `rhdh-pipeline.yaml`; operator-bundle uses a separate template.
21+
22+
### Files to update
823

924
| Location | When to edit |
1025
|----------|----------------|
1126
| `.tekton-templates/rhdh-pipeline.yaml` | hub, operator, must-gather |
1227
| `.tekton-templates/rhdh-operator-bundle.yaml` | operator-bundle (different task set) |
13-
| `.tekton-templates/components.yaml` | Metadata for `generatePipelineRuns.sh` |
14-
| `.tekton/rhdh-hub-<N>-{push,pull}.yaml` | From `rhdh-pipeline.yaml` |
15-
| `.tekton/rhdh-operator-<N>-{push,pull}.yaml` | From `rhdh-pipeline.yaml` |
16-
| `.tekton/rhdh-must-gather-<N>-{push,pull}.yaml` | From `rhdh-pipeline.yaml` |
17-
| `.tekton/rhdh-operator-bundle-<N>-{push,pull}.yaml` | From `rhdh-operator-bundle.yaml` |
18-
| `.tekton/rhdh-rag-content-<N>-{push,pull}.yaml` | Inline `pipelineSpec` — edit directly |
19-
| `.tekton/fbc-<version>-push.yaml` | FBC pipelines; often `build-image-index` without prefetch |
28+
| `.tekton-templates/components.yaml` | Metadata for `generatePipelineRuns.sh` only |
29+
| `.tekton/rhdh-hub-<N>-{push,pull}.yaml` | Regenerate from `rhdh-pipeline.yaml` |
30+
| `.tekton/rhdh-operator-<N>-{push,pull}.yaml` | Regenerate from `rhdh-pipeline.yaml` |
31+
| `.tekton/rhdh-must-gather-<N>-{push,pull}.yaml` | Regenerate from `rhdh-pipeline.yaml` |
32+
| `.tekton/rhdh-operator-bundle-<N>-{push,pull}.yaml` | Regenerate from `rhdh-operator-bundle.yaml` |
33+
| `.tekton/rhdh-rag-content-<N>-{push,pull}.yaml` | Inline `pipelineSpec` — **edit directly** (not in `components.yaml`) |
34+
| `.tekton/fbc-<version>-push.yaml` | FBC; `build-image-index` without prefetch |
2035
| `.tekton/images-mirror-set.yaml` | Only if task bundles are referenced |
2136

22-
## Regenerate
37+
### Regenerate
2338

2439
```bash
2540
cd .tekton
26-
./generatePipelineRuns.sh -t <x.y>
41+
./generatePipelineRuns.sh -t <x.y> # e.g. 1, 1.10
2742
```
2843

29-
Updates `rhdh-*-{push,pull}.yaml` and FBC `target_branch` placeholders in `fbc-*-push.yaml`.
44+
- Version `1` → files like `rhdh-hub-1-push.yaml`, branch `rhdh-1-rhel-9`
45+
- Version `1.10` → `rhdh-hub-1-10-push.yaml`, branch `rhdh-1.10-rhel-9`
46+
- Updates component PLRs from templates and FBC `target_branch` in `fbc-*-push.yaml`
47+
48+
### Generator notes
49+
50+
- Migrations: edit `pipelineSpec.params` and task `params` in `rhdh-pipeline.yaml` / `rhdh-operator-bundle.yaml`.
51+
- `components.yaml` only when extending generator placeholders (output image, prefetch, storage, etc.).
52+
- After `updateDigests.sh`, **always** run `generatePipelineRuns.sh` if templates were migrated earlier than PLRs (stale PLRs may still have `dev-package-managers`).
53+
54+
---
55+
56+
## Variant B: Shared build-pipeline layout (1.9)
57+
58+
Older branch layout. Hub and operator PLRs are thin wrappers (`pipelineRef`); Tekton `Pipeline` objects hold the real `pipelineSpec`.
59+
60+
### Files to update
61+
62+
| Location | When to edit |
63+
|----------|----------------|
64+
| `.tekton/build-pipeline-rhdh-hub.yaml` | Shared pipeline (hub + operator-bundle paths when `component-type` matches) |
65+
| `.tekton/build-pipeline-rhdh-operator.yaml` | Shared pipeline for operator (parallel structure to hub file) |
66+
| `.tekton-templates/rhdh-hub.yaml` | PLR wrapper — pass new **pipeline** params in `spec.params` |
67+
| `.tekton-templates/rhdh-operator.yaml` | PLR wrapper — same |
68+
| `.tekton-templates/rhdh-operator-bundle.yaml` | Inline `pipelineSpec` in template (like unified bundle) |
69+
| `.tekton/rhdh-hub-<N>-{push,pull}.yaml` | Regenerate from `rhdh-hub.yaml` |
70+
| `.tekton/rhdh-operator-<N>-{push,pull}.yaml` | Regenerate from `rhdh-operator.yaml` |
71+
| `.tekton/rhdh-operator-bundle-<N>-{push,pull}.yaml` | Regenerate from `rhdh-operator-bundle.yaml` |
72+
| `.tekton/fbc-<version>-push.yaml` | FBC pipelines |
73+
| `.tekton/build-pipeline-rhdh-hub.yaml` | Also updated by `updateDigests.sh` (not a template) |
74+
75+
No `must-gather` or `rag-content` PLRs on this layout.
76+
77+
### Regenerate
78+
79+
```bash
80+
cd .tekton
81+
./generatePipelineRuns.sh -t <x.y> # e.g. 1.9
82+
```
83+
84+
Produces `rhdh-{hub,operator,operator-bundle}-1-9-{push,pull}.yaml` via `sed` on per-component templates; updates FBC `target_branch` to `rhdh-1.9-rhel-9`.
85+
86+
### Migration: `prefetch-dependencies-oci-ta` 0.3
87+
88+
Apply in **three** places:
89+
90+
1. **Pipeline params** on `build-pipeline-rhdh-hub.yaml` and `build-pipeline-rhdh-operator.yaml`:
91+
- Add `enable-package-registry-proxy` (default `"true"`).
92+
2. **Prefetch tasks** `prefetch-dependencies-hub` and `prefetch-dependencies-operator`:
93+
- Remove `dev-package-managers`; pass `enable-package-registry-proxy: $(params.enable-package-registry-proxy)`.
94+
3. **PLR templates** `rhdh-hub.yaml` / `rhdh-operator.yaml`:
95+
- Add `spec.params` entry so the value reaches the shared pipeline.
96+
4. **Operator-bundle template** `rhdh-operator-bundle.yaml`:
97+
- Same as unified layout (inline `pipelineSpec`).
98+
99+
`prefetch-dependencies-bundle` uses non-OCI `task-prefetch-dependencies` — no `enable-package-registry-proxy` change unless MIGRATION.md says so.
100+
101+
### Generator notes
102+
103+
- `generatePipelineRuns.sh` does **not** rewrite `build-pipeline-*.yaml`; edit those files directly for task/digest/migration changes.
104+
- PLR `pipelineRef.name` must match pipeline metadata (`build-pipeline-rhdh-hub` / `build-pipeline-rhdh-operator`) — generated files already do.
105+
106+
---
107+
108+
## Both variants: commit locally, do not push
109+
110+
Typical outcome on a branch:
30111

31-
## Generator: template changes
112+
1. `updateDigests.sh --minor --no-push` → **one local commit** (digest bumps).
113+
2. Migration edits + `generatePipelineRuns.sh` → **second commit** (or leave unstaged for human review).
32114

33-
- Edit `pipelineSpec.params` and task `params` in `rhdh-pipeline.yaml` / `rhdh-operator-bundle.yaml`.
34-
- `components.yaml` only if extending `generatePipelineRuns.sh` placeholders for per-component PLR params.
115+
Human reviews the full diff across `.tekton/` and `.tekton-templates/`, then pushes or opens a PR.

0 commit comments

Comments
 (0)