WIP: Add kargo skills to onboard new components and documentation by flacatus · Pull Request #463 · redhat-appstudio/infra-common-deployments

flacatus · 2026-06-12T15:17:17Z

PR Summary by Qodo

Add Kargo component onboarding docs and per-component promotion tasks
✨ Enhancement 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

Walkthroughs

Description

• Add onboarding guide and Claude skill to scaffold new Kargo pipeline components.
• Rename/wire Kargo promotion tasks under the kargo component kustomization hierarchy.
• Guard PromotionTask execution by freight origin to prevent cross-component step runs.

Diagram

graph TD
  WH[("Warehouse")] --> ST1["Stage: ring-1 (staging)"] --> PT1[["PromotionTask: kargo ring-1"]] --> CFG["GitOps config files"]
  ST1 -->|"soak"| ST2["Stage: ring-2 (production)"] --> PT2[["PromotionTask: kargo ring-2"]] --> CFG
  DOC["Onboarding README"] --> ST1
  SKILL["Claude skill: kargo-onboard"] --> DOC
  subgraph Legend
    direction LR
    _wh[("Warehouse")] ~~~ _st["Stage"] ~~~ _pt[["PromotionTask"]] ~~~ _cfg["Config"]
  end

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep shared promotion tasks under base/

➕ Single place to find all promotion logic
➕ Avoids duplicating directory scaffolding per component
➖ Breaks ownership model (component logic lives outside the component)
➖ Doesn’t scale well as more components are onboarded
➖ Harder to apply per-component conventions (naming, guards, resources)

2. Single parameterized PromotionTask (per ring) for all components

➕ Less YAML to maintain (one task per ring)
➕ Consistent behavior by construction
➖ Requires robust parameter passing and conventions for target paths/keys
➖ More complex to support mixed deployment methods (helm generator vs kustomize images vs git refs)
➖ Harder to reason about blast radius of a task change

Recommendation: The PR’s approach (component-owned warehouse + promotiontasks, with standardized naming and a freight-origin guard) is the best fit for onboarding many components while keeping promotion logic localized. The freight-origin guard using ctx.targetFreight.origin.name is also a safer execution model than passing a component var through stages/tasks.

File Changes

Refactor (2)

kargo-promote-ring-1.yaml Rename ring-1 PromotionTask and guard by freight origin +2/-3
Rename ring-1 PromotionTask and guard by freight origin
• Renames the PromotionTask to kargo-promote-ring-1 and removes the component var. Switches the step execution guard to ctx.targetFreight.origin.name == "kargo" to ensure the task only runs for kargo-origin freight.
components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kargo-promote-ring-1.yaml

kargo-promote-ring-2.yaml Rename ring-2 PromotionTask and guard by freight origin +2/-3
Rename ring-2 PromotionTask and guard by freight origin
• Renames the PromotionTask to kargo-promote-ring-2 and removes the component var. Switches the step execution guard to ctx.targetFreight.origin.name == "kargo" to prevent accidental execution for other components’ freight.
components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kargo-promote-ring-2.yaml

Documentation (2)

SKILL.md Add Claude skill to scaffold new Kargo component onboarding +188/-0
Add Claude skill to scaffold new Kargo component onboarding
• Introduces a step-by-step interactive skill for collecting component details and generating the standard Kargo warehouse/promotion task/kustomization files. Documents the required patches to top-level kustomization and stage manifests, plus validation steps.
.claude/skills/kargo-onboard/SKILL.md

README.md Add comprehensive onboarding guide for Kargo promotion components +347/-0
Add comprehensive onboarding guide for Kargo promotion components
• Adds a full onboarding README describing the warehouse → stage → promotion task flow, directory layout conventions, and per-deployment-method update patterns. Includes concrete examples, checklists, and validation commands for building/applying manifests.
components/kargo/internal-production/projects/kargo-infra-common/README.md

Other (5)

kustomization.yaml Stop referencing shared base promotiontasks from kustomization +0/-1
Stop referencing shared base promotiontasks from kustomization
• Removes the base-level promotiontasks resource from the project base kustomization, aligning with the per-component promotiontasks ownership model.
components/kargo/internal-production/projects/kargo-infra-common/base/kustomization.yaml

stage-ring-1-staging.yaml Update staging stage to call renamed kargo promotion task +2/-2
Update staging stage to call renamed kargo promotion task
• Replaces the task reference from the generic ring-1-promote to kargo-promote-ring-1 and updates the step alias to kargo-promote to match naming conventions.
components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-1-staging.yaml

stage-ring-2-production.yaml Update production stage to call renamed kargo promotion task +2/-2
Update production stage to call renamed kargo promotion task
• Replaces the task reference from ring-2-promote to kargo-promote-ring-2 and updates the step alias to kargo-promote for consistency with staging and the new file naming scheme.
components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-2-production.yaml

kustomization.yaml Include kargo promotiontasks in component kustomization +1/-0
Include kargo promotiontasks in component kustomization
• Adds the promotiontasks directory as a resource so the renamed PromotionTask manifests are included when building the kargo component resources.
components/kargo/internal-production/projects/kargo-infra-common/kargo/kustomization.yaml

kustomization.yaml Update promotiontasks kustomization to new task filenames +2/-2
Update promotiontasks kustomization to new task filenames
• Updates resources to reference kargo-promote-ring-1.yaml and kargo-promote-ring-2.yaml instead of the previous ring-*-promote.yaml names.
components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kustomization.yaml

Move promotiontasks from base/ into kargo/promotiontasks/ so each component owns its warehouse and promotion logic. Add if condition using ctx.targetFreight.origin.name to guard step execution per component origin.

Rename promotion task files to follow <component>-promote-ring-N convention and add comprehensive README with onboarding guide for new components. Include Claude Code skill for interactive scaffolding.

openshift-ci · 2026-06-12T15:17:24Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: flacatus
Once this PR has been reviewed and has the lgtm label, please assign manish-jangra for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

qodo-for-redhat-appstudio · 2026-06-12T15:17:28Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (2)

Context used

✅ Compliance rules (platform): 5 rules

1. stage-ring-1-staging.yaml misnamed 📘 Rule violation ⚙ Maintainability

Description

These modified manifests contain kind: Stage, but their filename bases (stage-ring-1-staging and
stage-ring-2-production) do not exactly match the lowercase kind (stage). This violates the
required Kubernetes manifest naming convention and can break tooling that relies on kind-based
filenames.

Code

components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-1-staging.yaml[R31-32]
+            name: kargo-promote-ring-1
+          as: kargo-promote

Relevance

⭐ Low
Repo already uses Stage manifests named stage-ring-*-*.yaml (e.g., added in PRs #441/#443);
convention not enforced.
PR-#441
PR-#443

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
PR Compliance ID 1100 requires each modified Kubernetes manifest filename (base name) to equal the
lowercase of the manifest kind. In the referenced files, the manifest content shows kind: Stage,
but the modified filenames are stage-ring-1-staging.yaml and stage-ring-2-production.yaml, which
do not match the expected stage.yaml, demonstrating the convention violation.
Rule 1100: Name Kubernetes manifest files after single primary Kind
components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-1-staging.yaml[1-5]
components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-2-production.yaml[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
PR Compliance ID 1100 requires that each modified Kubernetes manifest filename base exactly equals the lowercase of the manifest’s single primary top-level `kind`, with no prefixes or suffixes. Both `components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-1-staging.yaml` and `components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-2-production.yaml` contain `kind: Stage`, so each manifest should be named `stage.yaml` (likely by relocating each into its own directory to avoid name collisions).

## Issue Context
Renaming will likely require placing each Stage manifest into its own directory (to avoid collisions with other Stage manifests) and updating any kustomize `resources:` references that point to the old filenames.

## Fix Focus Areas
- components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-1-staging.yaml[1-5]
- components/kargo/internal-production/projects/kargo-infra-common/base/stage-ring-2-production.yaml[1-5]
- components/kargo/internal-production/projects/kargo-infra-common/base/kustomization.yaml[1-11]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. kargo-promote-ring-1.yaml misnamed 📘 Rule violation ⚙ Maintainability

Description

These modified manifests contain kind: PromotionTask, but their filename bases
(kargo-promote-ring-1 and kargo-promote-ring-2) do not exactly match the required lowercase kind
(promotiontask). This violates the Kubernetes manifest naming convention and can break tooling
that relies on kind-based filenames.

Code

components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kargo-promote-ring-1.yaml[5]
+  name: kargo-promote-ring-1

Relevance

⭐ Low
PromotionTask manifests historically use descriptive filenames (ring-*-promote.yaml, etc.) not
promotiontask.yaml; see PR #441/#443.
PR-#441
PR-#443

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
PR Compliance ID 1100 requires each modified Kubernetes manifest filename base name to equal the
lowercase of the manifest kind. In the referenced files, the manifest content shows `kind:
PromotionTask, but the modified filenames are kargo-promote-ring-1.yaml` and
kargo-promote-ring-2.yaml, neither of which matches promotiontask.yaml, demonstrating the
noncompliance.
Rule 1100: Name Kubernetes manifest files after single primary Kind
components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kargo-promote-ring-1.yaml[1-5]
components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kargo-promote-ring-2.yaml[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Kubernetes manifest filename must match the single primary top-level `kind` (lowercased) with no prefixes/suffixes. The PromotionTask manifests currently named `kargo-promote-ring-1.yaml` and `kargo-promote-ring-2.yaml` contain `kind: PromotionTask`, so each manifest’s filename should be `promotiontask.yaml`.

## Issue Context
Renaming will likely require putting each PromotionTask into its own directory (to avoid collisions with other PromotionTasks) and updating kustomize `resources:` references in `promotiontasks/kustomization.yaml`.

## Fix Focus Areas
- components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kargo-promote-ring-1.yaml[1-12]
- components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kargo-promote-ring-2.yaml[1-12]
- components/kargo/internal-production/projects/kargo-infra-common/kargo/promotiontasks/kustomization.yaml[1-6]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

flacatus · 2026-06-12T15:21:32Z

FYI @PSzabo

flacatus added 2 commits June 12, 2026 16:16

refactor(kargo): move promotion tasks into kargo component directory

c9f9ebb

Move promotiontasks from base/ into kargo/promotiontasks/ so each component owns its warehouse and promotion logic. Add if condition using ctx.targetFreight.origin.name to guard step execution per component origin.

feat(kargo): rename promotion tasks and add onboarding docs

506adb6

Rename promotion task files to follow <component>-promote-ring-N convention and add comprehensive README with onboarding guide for new components. Include Claude Code skill for interactive scaffolding.

flacatus requested review from enkeefe00, gbenhaim and hugares as code owners June 12, 2026 15:17

openshift-ci Bot added the do-not-merge/work-in-progress label Jun 12, 2026

openshift-ci Bot requested a review from p8r-the-gr8 June 12, 2026 15:17

flacatus marked this pull request as draft June 12, 2026 15:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: Add kargo skills to onboard new components and documentation#463

WIP: Add kargo skills to onboard new components and documentation#463
flacatus wants to merge 2 commits into
redhat-appstudio:mainfrom
flacatus:feat/kargo-onboard-devlake

flacatus commented Jun 12, 2026 •

edited by qodo-for-redhat-appstudio Bot

Loading

Uh oh!

openshift-ci Bot commented Jun 12, 2026

Uh oh!

qodo-for-redhat-appstudio Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

flacatus commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

flacatus commented Jun 12, 2026 • edited by qodo-for-redhat-appstudio Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary by Qodo

Walkthroughs

File Changes

Uh oh!

openshift-ci Bot commented Jun 12, 2026

Uh oh!

qodo-for-redhat-appstudio Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

flacatus commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

flacatus commented Jun 12, 2026 •

edited by qodo-for-redhat-appstudio Bot

Loading

qodo-for-redhat-appstudio Bot commented Jun 12, 2026 •

edited

Loading