How to handle stage specific application configuration changes over Kargo

[rklonner]

I understand the concept of using Kargo to promote changes of a "base" configuration through stages.

However, I am not sure how to cleanly do this within Kargo for bringing stage specific changes in. I know that this is not happening regularly but as the rendered manifests are saved on branches created by Kargo I think it should be managed in a visible way over Kargo.

Let's use the kargo-demo example and assume we want to change the configmap in the uat stage
https://github.com/akuity/kargo-demo/blob/main/stages/uat/configmap.yaml

This change will only come in when running the steps in the PromotionTask for the uat stage and kustomize build is executed and committed to the uat branch.

Reapplying the same freight that is already on uat feels not right as I bring in this changes "only" implicitly.

Would I have to create warehouses for every stage to "subscribe" to this configuration for changes?

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  annotations:
    kargo.akuity.io/refresh: "2025-12-24T13:45:41Z"
  name: staging-config
  namespace: kargo-demo
spec:
  freightCreationPolicy: Automatic
  interval: 5m0s
  subscriptions:
  - git:
      branch: main
      commitSelectionStrategy: NewestFromBranch
      discoveryLimit: 20
      includePaths:
      - stages/uat/
      repoURL: https://github.com/akuity/kargo-demo.git

and make it a direct source for the uat stage along with the other requsted freight that will come from the upstream stage like so:

spec:
  promotionTemplate:
    spec:
      steps:
      - task:
          name: promote
  requestedFreight:
  - origin:
      kind: Warehouse
      name: kargo-demo
    sources:
      stages:
      - dev
  - origin:
      kind: Warehouse
      name: staging-config
    sources:
      direct: true

For only staging this would conceptionally look like this - an additional warehouse attached per stage (image is taken from a different experiment but shows what I mean)

It also feels like a bit of an overhead, especially if one does have a lot of stages and multiple different prod stages.

I wanted to ask if the community is implementing it that way or if I am missing something.

Many thanks in advance.