DEV Community: JosephCheng

Designing a Maintainable GitOps Repo Structure: Managing Multi-Service and Multi-Env with Argo CD + Kro

JosephCheng — Wed, 14 May 2025 11:10:32 +0000

From Namespace to ApplicationSet — a Clean, Trackable Setup with instance.yaml

📘 This is Part 3 of the “Building a Real and Traceable GitOps Architecture” series.

👉 Part 1: Why Argo CD Wasn't Enough

👉 Part 2: From Kro RGD to Full GitOps: How I Built a Clean Deployment Flow with Argo CD

👉 Part 4: GitOps Promotion with Kargo: Image Tag → Git Commit → Argo Sync

👉 Part 5: Implementing a Modular Kargo Promotion Workflow: Extracting PromotionTask from Stage for Maintainability

👉 Part 6: How I Scaled My GitOps Promotion Flow into a Maintainable Architecture

In Part 1, I explained why Argo CD wasn’t enough for my workflow. In Part 2, I shared how I used Kro to produce clean, declarative Deployments.

In this post, I want to take a step back — because even with the right tools, your GitOps setup can still collapse if the Git repo structure isn’t well-designed.

Here’s how I organize my repo using ApplicationSet to manage multiple environments and services in a clean, scalable, and maintainable way.

🧨 When My GitOps Repo Became a Mess

At first, I managed all the YAML manifests manually. We only had a few services, so I thought it was fine — until it wasn’t.

YAMLs were added to the root directory. Someone created a deploy-prod/ folder. Someone else copied dev manifests into production and made changes directly.

There were no naming conventions or directory rules. Every change started with the same question:

“Wait… which file are we actually deploying?”

One day, a small update accidentally got deployed to two environments at once. I spent the entire afternoon rolling back.

That’s when I realized I needed a Git structure that could survive real-world GitOps.

⚙️ My Setup and What I Wanted to Achieve

This setup runs on a self-managed MicroK8s cluster, and integrates:

Kro: to render clean Deployments, Services, and ConfigMaps
Argo CD: to sync manifests from Git into the cluster
Kargo: to promote image updates into Git commits

I had three goals:

Clearly separate development and production environments
Allow each service to update independently
Make every deployment traceable to a Git commit

📦 Why I Switched to Argo CD ApplicationSet

Originally, I created every Argo CD Application manually. It worked — but as the number of services grew, so did the pain:

I had to open the UI and duplicate settings every time
A single typo could break an entire sync
There was no consistent pattern to follow

Then I switched to ApplicationSet. Everything became more consistent and maintainable:

One ApplicationSet per namespace
Automatically generate Applications based on folder structure
Use annotations to link each service to the correct Kargo Stage

This brought three major benefits:

I no longer needed to create Applications manually
I could pair instance.yaml + Kro for automatic deployment
I could bind each service to its promotion logic via annotation (more on this in Part 4)

The annotation also links it directly to the correct Kargo Stage — zero manual setup required.

While ApplicationSet supports generating apps from multiple Git repos, I chose to keep everything in a single monorepo for easier traceability and promotion logic.

🗂 How I Structure My Git Repo

Here’s the directory layout I use in the repo:

project/
├── argo-applications/
│   ├── develop-applicationset.yaml
│   └── production-applicationset.yaml
├── develop/
│   ├── frontend/
│   │   └── instance.yaml
│   └── backend/
│       └── instance.yaml
└── production/
    └── frontend/
        └── instance.yaml

argo-applications/: holds one ApplicationSet config per environment
develop/ and production/: each service has its own folder with instance.yaml
❗ The ResourceGraphDefinition (RGD) isn’t checked into Git — it’s managed on the platform side to keep schema logic separate from environment-specific configuration.

This structure makes it easy to map services, environments, and deployments — and keeps everything traceable.

✍️ A Real ApplicationSet Example

Here’s my actual develop-applicationset.yaml:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: develop-applicationset
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://gitlab.com/your-name/your-repo.git
        revision: HEAD
        directories:
          - path: develop/*
  template:
    metadata:
      name: '{{path.basename}}-dev-app'
      annotations:
        kargo.akuity.io/authorized-stage: develop:{{path.basename}}-dev-stage
    spec:
      project: develop
      source:
        repoURL: https://gitlab.com/your-name/your-repo.git
        targetRevision: HEAD
        path: '{{path}}'
        directory:
          recurse: true
      destination:
        server: https://kubernetes.default.svc
        namespace: develop
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

With this setup, if I add a folder like develop/backend/, a new Argo Application called backend-dev-app is automatically generated.

The annotation also links it directly to the correct Kargo Stage — zero manual setup required.

🌳 How I Handle the Root App

I don’t store the root App in Git.

Instead, I create it once manually in the Argo CD UI. Its only job is to point to the argo-applications/ directory and sync all the ApplicationSets inside.

This gives the UI a single, stable entry point that reflects what’s in Git — easy to reason about and maintain.

🧼 Keeping Environments and Services Isolated

Each Kubernetes namespace maps to:

One Argo CD Project
One ApplicationSet
One Kargo Project

Every instance.yaml lives in an environment-specific path.

The RGD is shared, but each environment has its own values — so develop and production stay completely isolated.

🛠 How This Structure Helps My Day-to-Day

This repo layout doesn’t just keep things “clean” — it makes my daily workflow smoother:

Need to check a config? Open the service’s folder
Want to see what changed in a deployment? Run git log on the instance.yaml
Adding a new service? Just create a folder and add an instance.yaml - that’s it

While I currently maintain most YAML myself, this structure sets a clear standard for future collaboration and handoff.

It builds a shared deployment language that’s easy to extend and hard to mess up.

✅ Why instance.yaml Is My Single Source of Truth

Every service’s instance.yaml is:

Managed in Git
Synced automatically via Argo CD
Updated by Kargo through yaml-update

In other words: when this file changes, the deployment changes.

No more digging into multiple manifests or chasing sync bugs — one file drives the entire state.

That’s how I define control in a GitOps setup.

🧱 This Structure Is the Foundation for Promotion

At first glance, this post might look like it’s just about organizing folders and automating Argo CD.

But in reality, this structure is what makes the entire promotion flow possible.

Here’s how Kargo works:
→ Detect a new image tag
→ Create a Freight
→ Update the instance.yaml
→ Argo CD syncs the commit
→ Kro applies the Deployment

If file paths, annotations, or Application names aren’t consistent, Kargo has no idea what to promote.
That’s why the Git structure is the foundation of a scalable, traceable GitOps workflow.

🔜 Coming Up Next: Promotion with Kargo

With this repo structure in place, I now have:

Clean, declarative Deployments from Kro
Automated syncing from Argo CD
Scalable Application generation via ApplicationSet

But we’re just getting started.

In the next post, I’ll cover:

How promotion flows from image tag → Freight → instance.yaml → Argo CD → Kro
How each service links to its own Kargo Stage
How ApplicationSet annotations enable precise targeting and sync

If you’re designing a GitOps setup or juggling multiple environments and services, I hope this post gives you a solid reference.
If it helped you, feel free to share it or follow the series. And if you’ve built something similar, I’d love to hear how it went.

From Kro RGD to Full GitOps: How I Built a Clean Deployment Flow with Argo CD

JosephCheng — Mon, 12 May 2025 08:25:05 +0000

From scattered YAML files to a fully traceable GitOps pipeline — here’s how I used Kro to build a cleaner, more maintainable deployment process.

📘 This is Part 2 of the “Building a Real and Traceable GitOps Architecture” series.

👉 Part 1: Why Argo CD Wasn't Enough

👉 Part 3: Designing a Maintainable GitOps Repo Structure: Managing Multi-Service and Multi-Env with Argo CD + Kro

👉 Part 4: GitOps Promotion with Kargo: Image Tag → Git Commit → Argo Sync

👉 Part 5: Implementing a Modular Kargo Promotion Workflow: Extracting PromotionTask from Stage for Maintainability

👉 Part 6: How I Scaled My GitOps Promotion Flow into a Maintainable Architecture

🧩 Why I Started with an RGD

In my previous article, I shared how managing multiple YAML files became a real burden. Each time I updated an image tag, I had to patch three different manifests — Deployment, Service, and ConfigMap — just to reflect a simple change.

So I started asking:

What if I could update a single file and have all dependent resources update automatically?

That’s when I found Kro — a declarative GitOps engine that lets me define a service using one ResourceGraphDefinition (RGD) and a matching instance.yaml. From there, it automatically generates and applies all necessary Kubernetes resources.

This post walks through how I implemented that setup, including the actual YAML structure, the pitfalls I hit, and how I connected it with Argo CD and Kargo to build a fully automated GitOps flow.

🧠 What’s Kro, and Why RGD?

Kro is a lightweight GitOps templating engine. It’s designed to:

Render Kubernetes resources from a template + instance
Work declaratively with Git as the source of truth
Cleanly separate schema, templates, and values

It sounds similar to Helm, but here’s how it differs:

No templating syntax
No chart packaging or release abstraction
No values.yaml spaghetti

Instead, Kro is more transparent and tightly aligned with GitOps principles.

At the heart of it is the ResourceGraphDefinition (RGD). Without this file, Kro does nothing. It’s the blueprint that defines which resources are generated and how values flow into them.

🛠 My First RGD: Starting Simple

I decided to start small — a simple frontend web service.

It only needed three resources:

ConfigMap (for API_URL and TIME_ZONE)
Deployment (for image and replica count)
Service (to expose a port)

Here’s the schema I wrote for it:

spec:
  name: string | default=frontend
  namespace: string | default=develop
  values:
    configMap:
      data:
        API_HTTP_URL: string
        TIME_ZONE: string | default="XXX/XXX"
    deployment:
      image: string
      tag: string
      replicas: integer | default=1
    service:
      port: integer | default=3000
      targetPort: integer | default=3000

This schema acts as a contract: every value that an instance provides must follow this structure. It’s simple, explicit, and human-readable.

📄 Template: How Schema Connects to Resources

With the schema in place, I needed to define what it generates.

In Kro, templates are added under the resources: section. Each one has a unique id, which Kro uses for change tracking.

Here’s an excerpt from my Deployment template:

- id: deploy
  template:
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: ${schema.spec.name}
      namespace: ${schema.spec.namespace}
    spec:
      replicas: ${schema.spec.values.deployment.replicas}
      template:
        spec:
          containers:
            - image: ${schema.spec.values.deployment.image}:${schema.spec.values.deployment.tag}

No Helm syntax, no conditional logic — just clean variable references.

This is what I liked most about Kro: the schema-template-instance structure is clear and composable, without any magic.

📦 My `instance.yaml`: The Missing Piece

The schema and template define what can be deployed. But Kro won’t do anything until you provide values via an instance.

Here’s what my instance.yaml looked like:

apiVersion: kro.run/v1alpha1
kind: FrontendAppV2
metadata:
  name: wsp-frontend
  namespace: develop
spec:
  name: wsp-frontend
  namespace: develop
  values:
    configMap:
      data:
        API_HTTP_URL: https://example.com/api
        TIME_ZONE: XXX/XXX
    deployment:
      image: <username>/<your-project>
      tag: "1.0.1"
      replicas: 1
    service:
      port: 3000
      targetPort: 3000

I defined my schema under the FrontendAppV2 API name, so instances can use that kind and Kro knows how to match them.

I store this file in Git (under develop/app/) and sync it using Argo CD.

This way, I can declaratively define the state of my service through Git alone — Kro and Argo CD take care of the rest.

🔁 Full Automation: From Tag → Git → Kro Apply

Here’s how I fully automated the flow using Kargo:

Push a new Docker image to the registry
Kargo detects it via Warehouse, creates a Freight
Stage triggers a yaml-update that modifies instance.yaml
Commit + push to Git
Argo CD detects the change and syncs
Kro sees the updated instance and renders new resources

The key part is the yaml-update step in Kargo:

- key: spec.values.deployment.tag
  value: ${{ quote(imageFrom(vars.imageRepo, warehouse(vars.warehouseName)).Tag) }}

Each change to the image tag automatically flows into Git, then into Kro, and finally into the cluster.

💥 Pitfalls I Ran Into (and How I Fixed Them)

Here are some real-world issues I hit:

1️⃣ Resource didn’t apply, but no error
I had a Service template written correctly — but nothing showed up in the cluster.
Turns out the schema was missing a type, so the value failed to render and Kro skipped the whole resource.

2️⃣ Tag value caused type mismatch
My Kargo yaml-update wrote the tag as a number (1.0.1 → 1), and Kro rejected it.
Fix: wrap the tag in quote() to force it into a string.

3️⃣ Kro skipped update due to unchanged generation
Kro uses generation and delta logic. If the rendered output is identical, it won’t re-apply.
The log says:
Skipping update due to unchanged generation

4️⃣ Debugging requires watching the logs
Kro doesn’t show much in the UI. I rely on controller logs to confirm updates:

Found deltas for resource  
Skipping update due to unchanged generation

🧭 Where Kro Fits in My GitOps Architecture

Kro is now the template engine of my GitOps setup.

It’s not just a Helm alternative. It enables me to:

Separate structure (schema)
Abstract resource definitions (template)
Provide values through Git (instance.yaml)

With Argo CD syncing and Kargo promoting, I now have a full GitOps chain that’s clean, traceable, and reproducible:

Docker tag → Git commit → Argo CD sync → Kro apply

Each deployment is versioned and explainable — no more “mystery state” in the cluster.

🔎 Bonus: My Environment Setup

Currently, I’m using this setup in the develop namespace.
Each environment (dev, staging, prod) gets its own instance.yaml and Argo CD Application.

For production, I plan to use separate Git paths and isolate sync targets.

🔜 Coming Next: Designing a Clean GitOps Repo Structure

In the next part, I’ll show how I organize:

Git repo layout (per service + environment)
ApplicationSet management
How Kro, Argo CD, and Kargo all connect together

If you’re building your own GitOps setup, I hope this post saved you some time — and helped demystify how Kro works behind the scenes.

Why Argo CD Wasn't Enough: Real GitOps Pain and the Tools That Fixed It

JosephCheng — Thu, 08 May 2025 11:02:55 +0000

This is the first post in the "Building a Real-World GitOps Setup" series.

👉 Part 2: From Kro RGD to Full GitOps: How I Built a Clean Deployment Flow with Argo CD

👉 Part 3: Designing a Maintainable GitOps Repo Structure: Managing Multi-Service and Multi-Env with Argo CD + Kro

👉 Part 4: GitOps Promotion with Kargo: Image Tag → Git Commit → Argo Sync

👉 Part 5: Implementing a Modular Kargo Promotion Workflow: Extracting PromotionTask from Stage for Maintainability

👉 Part 6: Designing a Maintainable GitOps Architecture: How I Scaled My Promotion Flow from a Simple Line to a System That Withstands Change

This series isn't about feature overviews or polished diagrams. It's a real journey - how I started with Argo CD, ran into scaling pains, and ended up building a workflow around Kro and Kargo to simplify the chaos.

The Starting Point: Argo CD as Our First GitOps Tool

Our team uses GitLab to manage our projects. Since Argo CD supports Git as a source of truth, it was naturally the first GitOps tool we adopted.
It's stable, visual, and easy to get started with - at least at the beginning.
But as the number of services grew, so did the complexity.

The Problem: Too Many YAML Files, Too Much Maintenance

As we added more services, I started to feel like managing YAML was getting out of hand.
Each service had its own Deployment, Service, and ConfigMap. Updating an image tag or tweaking an environment variable meant editing three different files and submitting three PRs just to change a single port.

That felt wrong.

Isn't there a way to change one file and have everything else update accordingly?

I wanted to stop maintaining three YAML files just to represent "this service is now version X."

What I really needed was:

A single instance.yaml per service
Define tag, port, and env vars in one place
Use that to generate the actual K8s manifests
Let Argo CD keep syncing, while keeping the repo clean

The Solution Appears: Discovering Kro

At this point, I started looking for tools that could turn high-level service definitions into manifests automatically.
That's when I found Kro

Here's what I was trying to simplify:

Before:

frontend/
├── deployment.yaml
├── service.yaml
└── configmap.yaml

backend/
├── deployment.yaml
├── service.yaml
└── configmap.yaml

After:

frontend/
└── instance.yaml → Kro → generated manifests

Example instance.yaml:

spec:
  values:
    deployment:
      tag: 0320.1
      port: 3000
      image: frontend
    config:
      LOG_LEVEL: debug
      API_URL: https://api.example.com

Just editing this one file could trigger all necessary changes.
It felt clean, declarative, and scalable.

Why I Chose Kro Instead of Writing Raw YAML

At this point, I didn’t want to manage dozens of YAML files by hand anymore.

What I really needed was a way to describe the intent of a service — not duplicate the same boilerplate across deployments, services, and configmaps.

I didn’t want to turn my GitOps repo into a config sprawl.

I wanted something:

Declarative, but still readable
Focused on service logic, not YAML mechanics
Easy to compose and integrate with Argo CD
Able to reason about dependencies between resources

That’s when Kro clicked.

With a single instance.yaml per service, I could:

Define tag, port, and config in one place
Use a ResourceGraphDefinition to render full Kubernetes manifests
Let Argo CD do the syncing, while I focused on intent

And one design choice I found especially elegant:

Kro builds a Directed Acyclic Graph (DAG) from your defined resources, which ensures:

All referenced values are valid and resolvable
Dependencies (like Service → Deployment → ConfigMap) follow a safe apply order
There's no cyclic reference that might cause unpredictable state

This structure gave me both clarity and safety — I could think in terms of service logic, while Kro guaranteed a consistent deployment process behind the scenes.

Kro also validates this structure as part of its ResourceGraphDefinition processing — catching circular references, invalid types, and broken dependencies early.

TL;DR - The GitOps Workflow in One Diagram

The full GitOps flow: instance files drive Kro, image tags trigger Kargo, and Argo CD keeps the cluster in sync.
A workflow where instance files define the service setup, and everything else flows from that.

So What's Next?

This post was all about motivation and setup.

Next, I'll show you how I wrote my first ResourceGraphDefinition (RGD)-the template Kro uses to render Deployments, Services, and ConfigMaps. I'll walk through its structure, the pitfalls I encountered, and how I got it to render real, production-ready manifests.

If you've ever patched the same deployment.yaml three times just to bump an image tag, this series is for you.

Follow along as I break down the entire GitOps stack, one layer at a time.
Thanks for reading 🙇

🧠 If you're also trying to simplify GitOps or reduce YAML fatigue, I'd love to hear how you're approaching it.

GitOps Promotion with Kargo: Image Tag Git Commit Argo Sync

JosephCheng — Tue, 06 May 2025 14:10:57 +0000

Designing a GitOps-native promotion pipeline from image tag to deployment — traceable, controllable, and rollback-friendly

📘 This is Part 4 of my GitOps Architecture series.

This series was originally written and published in a linear progression (Part 1 to 6).

On Dev.to, I’m republishing it starting from the final system design (Part 6), then tracing backward to how it was built — from system to source.

👉 Part 1: Why Argo CD Wasn’t Enough

👉 Part 2: From Kro RGD to Full GitOps: How I Built a Clean Deployment Flow with Argo CD

👉 Part 3: Designing a Maintainable GitOps Repo Structure: Managing Multi-Service and Multi-Env with Argo CD + Kro

👉 Part 5: Implementing a Modular Kargo Promotion Workflow: Extracting PromotionTask from Stage for Maintainability

👉 Part 6: How I Scaled My GitOps Promotion Flow into a Maintainable Architecture

In the previous articles, I explained why Argo CD wasn’t enough for my needs, how Kro helped structure my deployment logic, and how I designed the Git repository layout.
Now it’s time to focus on the core of any GitOps workflow — promotion.

How do you go from a new image tag to a Deployment update in a way that’s traceable, controllable, and rollbackable?

🧩 What Do I Mean by “Promotion”?

When a new image tag is pushed, I want that version to be validated, written into Git, and deployed to Kubernetes.
Not triggered by CI scripts. Not patched via webhook.

This is a Git-first, GitOps-native promotion workflow — where everything flows through Git.

1. Why Is Promotion the Most Critical Part of GitOps?

This continues the story from the last three posts:
Argo CD limitations → Kro introduction → GitOps structure emerging

The instance.yaml file we discussed earlier doesn’t yet handle promotion. But promotion is one of the most frequent — and risky — operations in any GitOps flow.

🔁 It happens all the time. And if it’s not designed well, it becomes the first thing to go wrong.

2. What Happens Without a Proper Promotion Process?

At first, I manually edited the tag in instance.yaml and let Argo CD sync it. It worked — but:

Easy to mistype or forget to commit
No version record — rollback relies on memory
No condition control — services might get silently upgraded

I also considered scripting this via CI, but it would spread logic across pipelines. Hard to trace. Harder to revert.

Why Not Use Argo CD Image Updater?
Yes, I looked into Argo CD’s image updater plugin.
It auto-detects new image tags and patches Helm values or manifests.

That’s convenient, but it didn’t meet my GitOps criteria:

✅ Detects new tags
❌ Doesn’t commit back to Git → no history
❌ Doesn’t support conditional promotion (e.g. “only after tests pass”)
❌ Hard to coordinate promotion across services at scale

It’s great for background automation.
But I wanted explicit control, Git history, and safe rollback.

🎯 What I Really Wanted Was:
A clean, observable promotion pipeline:
Image tag → Git commit → Deploy

Everything versioned. Everything traceable. Everything rollbackable.

3. Why I Chose Kargo

I didn’t want promotion logic to live inside CI scripts or webhook handlers — not because it can’t work, but because I preferred a Git-native flow where promotion history lives entirely in Git.

I wanted Git to be the source of truth and the engine for promotion.

Kargo gave me exactly that.

✅ Starts with an image tag → auto-creates a Freight
✅ Defines promotion logic with Stage
✅ Updates Git via yaml-update → git-commit → git-push
✅ Integrates with Argo CD + Kro
✅ Supports SemVer (I use tags like 1.2.3)

And best of all — Kargo updates Git, which then triggers Argo CD, and Kro renders instance.yaml into Kubernetes manifests.

4. Thinking in State Machines

You don’t need to think of promotion as a state machine — but if you do, it’s a surprisingly elegant way to model the logic behind Kargo.

A new image tag is pushed → this acts as an event
Kargo creates a Freight → a signal representing that new version
A Stage receives that Freight → evaluates the promotion logic(current state)
If conditions are satisfied → a transition is triggered
That transition runs a PromotionTask → updates YAML → commits → to Git

And just like a finite state machine, this transition is deterministic — based on input (Freight), current state (Stage), and declared logic (Task).

📌 This replaces scattered CI scripts and conditional logic with a clean, declarative state transition — fully visible in Git history.

🧱 What Are Kargo’s Core Components?
If you’re new to Kargo, here’s a quick breakdown of its three building blocks:

Warehouse：Watches an image repo, emits a Freight when a new tag appears.
Freight：Represents a specific image version with metadata.
Stage：Evaluates Freight and executes the promotion logic.

Together, these power a declarative, Git-driven promotion engine.

5. Promotion Pipeline (Mermaid Diagram)

Here’s the visual flow I used to design this:

 DockerHub->>Kargo Warehouse: New image tag pushed
 Kargo Warehouse->>Freight: Create Freight
 Freight->>Kargo Stage: Trigger promotion
 Kargo Stage->>Git: Update instance.yaml → Commit → Push
 Git->>Argo CD: Git change detected
 Argo CD->>Kro: Pass updated instance.yaml
 Kro->>Cluster: Render manifests and apply

6. How I Configure the Warehouse

Kargo supports various selection strategies — SemVer, Lexical, Newest.

I use SemVer, and each service has its own Warehouse:

Polling Interval: Every 5 minutes
One Warehouse per service → clear separation, no cross-talk

7. How I Define Stage Conditions

Here’s the promotion pipeline I run in each Stage:

git-clone → yaml-parse → yaml-update → git-commit → git-push

All changes target a single file: instance.yaml.

This makes the logic clear, trackable, and easy to debug.

You can go further with:

✅ Promote only if tests pass
✅ Require manual approval
✅ Ensure health check before promotion

The Stage is your promotion control tower.

8. How `yaml-update` Handles Tag Precision

This step made everything cleaner:

yaml-parse: read the original tag → store as oldTag
yaml-update: set the latest tag
git-commit: generate messages like:

Promote image from 1.2.1 to 1.2.2

📌 Example:

- uses: yaml-update
  config:
    path: ./repo/develop/frontend/instance.yaml
    updates:
      - key: spec.values.deployment.tag
        value: ${{ quote(imageFrom(vars.imageRepo, warehouse(vars.warehouseName)

9. Why This Promotion Pipeline Is Reliable

This setup works because:

✅ Every change is committed → observable, reversible
✅ Only one file is updated → minimal blast radius
✅ No YAML desync → rollback = git revert
✅ Service logic is isolated → safe parallel promotion

📌 Rollback Plan
While I haven’t fully implemented rollback yet, the plan is already in place and aligns with the rest of the GitOps flow:

Use previousTag() to fetch the last known version
Write that tag into instance.yaml
Commit → Push → Argo CD syncs

Eventually, I’ll create a **rollback-stage**+ **rollback-task**
to make rollback a native GitOps operation — not a manual fix.

10. What’s Next: Syncing Only the Right App

After promotion, I don’t want to sync the entire namespace.

I just want to sync the one app that changed.

Kargo supports this with argocd-update and ApplicationSet annotations.

In the next post, I’ll share:

How ApplicationSet works with Kargo Stage
How to scope syncs using annotations
How to stop “sync one = sync all”
YAML examples for Warehouse, Stage, Freight

💬 Closing Thoughts: Promotion Can Be Clean

This article isn’t about pasting YAML.

It’s about building a promotion pipeline that is:

✅ Condition-driven
✅ Git-observable
✅ Fully rollbackable

Of course, promotion via CI or webhooks is totally valid — but I found Kargo’s declarative and Git-driven model a better fit for my goals.

If you’re designing a GitOps system and wondering where promotion logic belongs,I hope this gave you a clear, maintainable path forward.

Your turn — how are you handling promotions in GitOps?
Drop a comment, share your approach, or let’s compare notes —
we might be solving the same problem 🚀

Implementing a Modular Kargo Promotion Workflow: Extracting PromotionTask from Stage for Maintainability

JosephCheng — Fri, 02 May 2025 08:34:29 +0000

A fully operational GitOps-native upgrade pipeline, designed for reuse and scalability

This is Part 5 of my GitOps Architecture series.

This series was originally written and published in a linear progression (Part 1 to 6).

On Dev.to, I’m republishing it starting from the final system design (Part 6), then tracing backward to how it was built — from system to source.

🧱 A GitOps-Native Upgrade Pipeline That Scales

This post introduces a fully operational GitOps-native promotion pipeline — designed for long-term reusability, modularity, and automation.

It’s not a concept — it runs in production.

And it became the foundation for my GitOps architecture.

📌 This is Part 5 of the series:

👉 ✅ Part 1: Why Argo CD Wasn't Enough

👉 ✅ Part 2: From Kro RGD to Full GitOps

👉 ✅ Part 3: Designing a Maintainable GitOps Repo

👉 ✅ Part 4: GitOps Promotion with Kargo

👉 ✅ Part 6: Designing a Maintainable GitOps Architecture (Start Here)

🚀 From Flowchart to Real-World Workflow

In the first four parts, I started with the limitations of Argo CD and worked toward a deployment model centered around Kro and instance.yaml.

In Part 4, I introduced a clean, Git-native promotion flow:

Image Tag → Git Commit → Argo Sync

But this post is where the system truly goes live.

This time, I implemented Kargo’s three core components and stitched them into a fully working GitOps flow:

Warehouse: Tracks image updates
Stage: Decides whether to promote
PromotionTask: Executes the update → commit → push → sync pipeline
ApplicationSet + annotation: Targets the correct ArgoCD app

Then I refactored the logic for maintainability by extracting promotion steps into a shared PromotionTask.

🏗 Warehouse — Per-Service Image Tracking

Each service has its own Warehouse to isolate update detection.
This lets each service operate with its own frequency and tag rules:

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: frontend-dev-image
  namespace: develop
spec:
  freightCreationPolicy: Automatic
  interval: 5m0s
  subscriptions:
    - image:
        repoURL: docker.io/zxc204fghasd/wsp-web-server-v2
        imageSelectionStrategy: SemVer
        strictSemvers: true
        discoveryLimit: 20

Stage – From Embedded Logic to Task Delegation

I originally stuffed all promotion steps inside the Stage:

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  annotations:
    kargo.akuity.io/color: lime
  name: frontend-dev-stage
  namespace: develop
spec:
  promotionTemplate:
    spec:
      steps:
      - uses: git-clone
        config:
          checkout:
          - branch: main
            path: ${{ vars.srcPath }}
          repoURL: ${{ vars.gitopsRepo }}
      - uses: yaml-parse
        config:
          outputs:
          - fromExpression: spec.values.deployment.tag
            name: oldTag
          path: ${{ vars.srcPath }}/develop/frontend/wsp-web-instance.yaml
      - as: update-image
        uses: yaml-update
        config:
          path: ${{ vars.srcPath }}/develop/frontend/wsp-web-instance.yaml
          updates:
          - key: spec.values.deployment.tag
            value: ${{ quote(imageFrom(vars.imageRepo, warehouse(vars.warehouseName)).Tag) }}
      - as: commit
        uses: git-commit
        config:
          messageFromSteps:
          - update-image
          path: ${{ vars.outPath }}
      - uses: git-push
        config:
          path: ${{ vars.outPath }}
      - uses: argocd-update
        config:
          apps:
          - name: frontend-dev-app
            sources:
            - desiredRevision: ${{ outputs.commit.commit }}
              repoURL: ${{ vars.gitopsRepo }}
      vars:
      - name: gitopsRepo
        value: https://your.git/repo.git
      - name: imageRepo
        value: <your docker image repo>
      - name: srcPath
        value: ./repo
      - name: outPath
        value: ./repo
      - name: targetBranch
        value: main
      - name: warehouseName
        value: frontend-dev-image
  requestedFreight:
  - origin:
      kind: Warehouse
      name: frontend-dev-image
    sources:
      direct: true
      stages: []

It worked — but maintaining this became a nightmare.
Maintaining this across services became a burden — any logic change meant updating multiple files by hand.

So I refactored.

Stage now focuses only on deciding when to promote , and delegates promotion logic to a reusable PromotionTask:

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: frontend-dev-stage
  namespace: develop
  annotations:
    kargo.akuity.io/color: lime
spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: frontend-dev-image
      sources:
        direct: true
        stages: []
  promotionTemplate:
    spec:
      steps:
        - task:
            name: promote-kro-instance

This wasn’t just for readability.
It was the only way to make promotions modular, reusable, and maintainable.

PromotionTask — The Core of Modular Promotion Logic

PromotionTask contains all the steps needed to perform a promotion.

To make it reusable, I parameterized the task using variables:

gitopsRepo: Git repo URL with token
imageRepo: Docker image registry
instancePath: Path to the service's instance.yaml
warehouseName: Warehouse to track tags
appName: Argo CD app to sync after promotion

Here's the full YAML:

apiVersion: kargo.akuity.io/v1alpha1
kind: PromotionTask
metadata:
  name: promote-image
  namespace: develop
spec:
  vars:
    - name: gitopsRepo
      value: https://your.git/repo.git
    - name: imageRepo
      value: <your docker image repo>
    - name: instancePath
      value: develop/frontend/instance.yaml
    - name: warehouseName
      value: frontend-dev-image
    - name: appName
      value: frontend-dev-app
  steps:
    - uses: git-clone
      config:
        repoURL: ${{ vars.gitopsRepo }}
        checkout:
          - branch: main
            path: ./repo
    - uses: yaml-parse
      config:
        path: ./repo/${{ vars.instancePath }}
        outputs:
          - name: oldTag
            fromExpression: spec.values.deployment.tag
    - uses: yaml-update
      as: update-image
      config:
        path: ./repo/${{ vars.instancePath }}
        updates:
          - key: spec.values.deployment.tag
            value: ${{ quote(imageFrom(vars.imageRepo, warehouse(vars.warehouseName)).Tag) }}
    - uses: git-commit
      as: commit
      config:
        path: ./repo
        message: ${{ task.outputs['update-image'].commitMessage }}
    - uses: git-push
      config:
        path: ./repo
    - uses: argocd-update
      config:
        apps:
          - name: ${{ vars.appName }}
            sources:
              - repoURL: ${{ vars.gitopsRepo }}
                desiredRevision: ${{ task.outputs['commit'].commit }}

Why Break Out Tasks? Because Templates Are the Long-Term Answer

This wasn't about writing cleaner YAML.

It was about making the system scale.

What happens when you have 10 services, all running similar — but slightly different — promotion flows?

If you embed everything inside the Stage, you'll end up copy-pasting YAML everywhere.

When logic changes, you have to update every file manually.

That doesn't work at scale.

✅ The answer is: extract the logic into a reusable, parameterized PromotionTask.

With this design:

Stage handles the decision: should we promote?
Task handles the execution: how do we promote?
The logic lives in one place, and can be reused across services
A single task can power multiple services, just by changing a few variables
If one service needs extra validation, just fork the task — it won’t affect the rest

This is how you make promotion logic modular, maintainable, and scalable — even when things get complicated.

Don’t Forget the Kargo Project — The Key to Automatic Promotion

One often-overlooked piece when working with Kargo is the Project resource.

Even if you’ve defined your Warehouse, Stage, and PromotionTask correctly,nothing will actually run unless you declare a Project.

In my design, every namespace has its own Project.
This separates environments (like develop and production) and scopes promotion logic clearly.

Here’s the Project I defined for the develop namespace:

apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: develop
  namespace: develop
spec:
  promotionPolicies:
    - autoPromotionEnabled: true
      stage: frontend-dev-stage

This setup helped me achieve several things:

Defined a dedicated Project for the develop environment, managing all resources in one place
Enabled autoPromotionEnabled: true, allowing Kargo to automatically push qualifying Freight to the appropriate Stage
Made the entire flow — from image tag → Freight → Stage → Task — fully automated, with zero manual triggers

⚠️ Pitfall
I ran into this myself.
Freight was getting created just fine, but Stage wasn’t promoting.
It turns out — I simply forgot to declare a Project.

Without a Project, Kargo will not run any promotion logic — no matter how well your YAML is structured.

Pitfalls I Hit (and How I Fixed Them)

These weren’t theoretical issues.
These are all real problems I encountered — and fixed.

image.tag unknown
In my early implementation, I used an invalid variable name like image.tag inside yaml-parse, and the whole promotion failed.
✅ Fix: Use values from Freight, or reference pre-defined variables via vars.

Freight was <nil>
This often happened when the Warehouse configuration was wrong — usually a bad repoURL or a tag that couldn’t be parsed properly.
✅ Fix: Make sure your image repo is correct, use SemVer, and always wrap expressions with quote().

YAML file not found
My yaml-parse step couldn’t find the file—not because the file was missing, but because the git-clone path didn’t match.
✅ Fix: Manually clone the repo to confirm the file structure, then double-check that your Stage uses the exact same path.

Git push failed (authentication)
I kept hitting auth errors on git-push. The actual reason? I forgot to include the GitLab token.
✅ Fix: Inject the token directly in the gitopsRepo URL like this: https://@gitlab.com/....

argocd-update unauthorized
Even when promotion completed, the argocd-update step failed. Turned out the Application wasn’t authorized.
✅ Fix: Add the correct kargo.akuity.io/authorized-stage annotation to the Application metadata.

Final Thoughts: From Design to Reality

In this post, I made the promotion pipeline real.

I implemented the full Warehouse → Stage → PromotionTask chain
Designed promotion logic to be reusable and maintainable
Built a system that doesn’t just run once, but runs day after day

This was the shift from “YAML that works” to “a system that survives change.”

I haven’t added validation gates, PR mode, or Slack notifications yet — but I’ve left room for all of that.
My Stage structure supports conditions, and my Tasks are ready to evolve.

If you’ve solved promotion workflows in a different way, I’d love to hear how you approached it.
Or if you’re currently stuck somewhere in your GitOps pipeline — feel free to drop a comment or message.
Maybe we’re solving the same thing from different angles.

The pitfalls I hit?
I hope you don’t have to hit them too.

💬 If this post helped clarify how to modularize Kargo promotion logic, give it a ❤️ or drop a comment.

I'm sharing more GitOps internals — next up is Part 4: the architectural reasoning behind this pipeline.

How I Scaled My GitOps Promotion Flow into a Maintainable Architecture

JosephCheng — Wed, 30 Apr 2025 07:25:09 +0000

A full-stack GitOps promotion flow architecture, designed for traceability, maintainability, and multi-service scalability.

🚀 This is Part 6 — the final chapter — of my “Building a Real and Reliable GitOps Architecture” series.

👉 Part 1: Why Argo CD Wasn't Enough

👉 Part 2: From Kro RGD to Full GitOps: How I Built a Clean Deployment Flow with Argo CD

👉 Part 3: Designing a Maintainable GitOps Repo Structure: Managing Multi-Service and Multi-Env with Argo CD + Kro

👉 Part 4: GitOps Promotion with Kargo: Image Tag → Git Commit → Argo Sync

👉 Part 5: Implementing a Modular Kargo Promotion Workflow: Extracting PromotionTask from Stage for Maintainability

🔔 Since this is the final article, I’ll also wrap up with some reflections — and a glimpse into what’s coming next.

📖 Introduction: From Promotion Flow to GitOps System Architecture

In Part 4, I introduced a basic promotion flow:

image → commit → sync

In Part 5, I implemented it with real components:

Warehouse → Stage → Task

But in Part 6, I want to explore what happens when that flow gets dropped into a real environment—multiple services, long-term operation, growing complexity.

I wasn't just trying to make it work once.

I wanted to design a system—

A system that's traceable, adaptable, resilient, and doesn't break when things change.

In this article, I'll focus on the architectural mindset behind it—how I layered my GitOps design and modularized my promotion logic to build something that doesn't just work, but lasts.

🧱 Architecture Layering: How I Used root-app + ApplicationSet to Manage Multiple Services

Just having a working promotion flow isn't enough.

If you want your system to survive long-term, across services and teams, you need a structure that scales, decouples, and supports independent debugging.

I considered the common approach early on—

Creating a dev-app / prod-app as middle-layer Applications to manage services underneath.

Looks neat in theory. But in practice? It caused two major issues:

Hard to decouple promotion strategies
When services are bundled into one App, a single change (like a hotfix) can affect the whole package.
Overcoupled behavior and risk
One sync failure could block multiple services. Permission scopes get blurry. Separation of concerns becomes a nightmare.

So I went in the opposite direction—

I adopted a 3-layer GitOps architecture:

root-app
  └── application-set (by namespace: develop / production)
        └── application (one per service: frontend-app / backend-app ...)

root-app: Manages overall structure; each namespace maps to an ApplicationSet
ApplicationSets: Scans Git folders to generate Argo CD Application
Application: Deploys and promotes a single service

This structure addresses the three pain points I care about most:

Separation of promotion logic: Each service can define its own release strategy — fully decoupled.
Error isolation: If one app sync fails, others continue working.
Minimal expansion cost: To add a service, just push a new folder. The ApplicationSet auto-generates its Application.

📌 This isn't about having tidy YAML.
It's about building a system that remains stable, transparent, and maintainable as it grows.

And this clear layering enabled me to cleanly separate tool responsibilities and modularize my upgrade logic later on.

⚙️ Responsibility Decoupling: What Kro, Kargo, and Argo CD Actually Do

In this architecture, each tool serves a clear purpose—not because they can't do more, but because separating responsibilities helps boundaries stay stable.

Kro: Declarative Templates + DAG-Defined Infrastructure

Kro isn't just a YAML generator.

It defines DAG-based dependency graphs for each service.

Each ResourceGraphDefinition (RGD) is a complete service blueprint, modeled as a graph of interdependent components: Deployment, Service, ConfigMap, etc.

Kro handles:

Validates the DAG structure to ensure no cycles or misconfigurations.
Generates a CRD (like WebApplication) to manage services as Kubernetes-native resources.
Applies and reconciles manifests in DAG order when instance.yaml changes.

📌 Each service’s infra becomes a versionable, testable graph.
Changes to subcomponents or dependency ordering become safe and composable — no more hand-editing YAML everywhere.

More importantly, this DAG modeling defines the service architecture itself — making refactoring, extending, or validating services much easier and safer.

Kro is not just my templating layer — it’s my system’s graph-based modeling layer, scaling logic without duplicating boilerplate.

Kargo: Promotion Orchestration + Traceability

Kargo orchestrates my upgrade process. Key components:

Warehouse: Tracks image tags and filters them by SemVer or lexical rules.
Stage: Decides whether to promote, based on tag comparison or validations.
PromotionTask: Executes the upgrade (update → commit → push → sync).

📌 Kargo makes promotion stateful, observable, and pluggable.
It turns what would be a static pipeline into a logical graph of upgrade checkpoints.

With Kargo, I can easily insert manual approvals, CI checks, or security scans — without losing traceability or rollback control.

Argo CD: Git → Cluster Synchronization Only

Argo CD’s role is the simplest — and purest.
It syncs manifests (produced by Kro, updated by Kargo) from Git to the cluster.

No decisions.
No tag handling.
No manifest mutation.

📌 Argo CD acts purely as the executor.
It ensures state consistency while remaining easy to debug, scale, and replace.

Why separate them this way?

✅ Decoupling: Each logic layer can evolve independently.
✅ Observability: Every part of the flow is traceable.
✅ Flexibility: Any tool can be swapped (Flux, GitLab CI, etc.) without a full rewrite.

This isn't about stacking tools. It’s about building a system that’s composable, maintainable, and future-proof.

♻️ Promotion Flow Design: From One Line to a Traceable System

Full promotion flow:

Image
  ↓
Warehouse
  ↓
Stage (Decision)
  ↓
PromotionTask (Execution)
  ↓
Git Commit
  ↓
Argo CD Sync

Why each step matters:

Image → Warehouse: I don’t let CI trigger upgrades. Warehouse watches the repo, giving full visibility into “what was published” and “what changed.”
Warehouse → Stage: Stage only decides if something should be promoted — based on SemVer comparison, webhook checks, or YAML diffs. Approval gates or CI validations can plug in here.
Stage → PromotionTask: PromotionTask contains the how, not just the what. Fully reusable and parameterized.
Task → Git commit: No direct applies. Every promotion creates a Git commit — for rollback, history, and reviewability.
Git → Argo CD: Argo CD syncs the commit. It’s the final executor — not part of the promotion decision.

📌 This isn’t just a working flow—it’s a traceable, modular, and extensible promotion lifecycle.

🧩 Modular & Maintainable Design: Making Promotion Logic Reusable

This is the part of the architecture I care most about.

I don’t just want upgrade flows to work.
I want them to be:

Reusable: No need to reimplement for each service.
Composable: Easy to plug in validations, notifications, and more.
Safe to evolve: Changes don’t break everything else.

1️⃣ Stage ≠ Task: Split the Responsibilities

Stage: should we promote?
PromotionTask: how do we promote?

Why this matters: If you pack everything into Stage, you’ll copy-paste logic across every service. Change one line? Touch ten YAML files.

2️⃣ PromotionTask as Template: Parameterized, Reusable Logic

I defined a standard PromotionTask and used variables to customize it per service:

apiVersion: kargo.akuity.io/v1alpha1
kind: PromotionTask
metadata:
  name: promote-image
  namespace: develop
spec:
  vars:
    - name: imageRepo
      value: docker.io/yourname/your-image
    - name: instancePath
      value: develop/your-service/instance.yaml
    - name: appName
      value: your-service-dev-app
  steps:
    - uses: git-clone
    - uses: yaml-parse
    - uses: yaml-update
    - uses: git-commit
    - uses: git-push
    - uses: argocd-update

With this setup:

frontend and backend share the same promotion task — just different vars.
Want to add validation? Copy the task, add a yaml-assert step.

📌 This isn’t just templating.
It’s a modular framework for defining, evolving, and scaling promotion logic.

🧨 What I Broke (and How I Fixed It)

Freight = <nil>: Image tag parsing failed → Switched to SemVer + quote().
Git push failed: Forgot token → Moved token into vars, fully automated.
Argo CD sync error: App missing authorized-stage → Fixed by adding annotation.
Kro instance.yaml missing: Wrong git-clone path → Reorganized repo structure.
Sync chaos →: Multiple services under one App → Split into independent Apps.

📌 These mistakes weren’t bugs to patch.
They were lessons to harden the system’s foundations.

🧭 Why This System Was Worth Building

Not built for a demo.

Built to survive.

Real systems need:

Traceability
Rollback
Validation
Modularity

📌 These are the price of long-term maintenance, not bonuses.

🔚 Final Thoughts: This Isn’t a Toolchain—It’s a System That Survives

It doesn’t just run.

It can be maintained.

It’s not rigid.

It evolves.

It’s not hardcoded.

It’s a modular, auditable system.

It wasn’t enough to make the flow work once.
It had to survive growth, adapt to change, and stay traceable across services and teams.

If you’re designing your own GitOps setup, don’t just pick tools — design for resilience. Build a system that grows with you.

📚 Wrapping Up This Series—See You in the Next One

This marks the final post in my “Designing a Real, Reliable GitOps Architecture” series.

Next up:

A brand-new series on building an MLOps architecture with MicroK8s, MLflow, Kubeflow, and vLLM.

If you're into model versioning, serving, and full-lifecycle MLOps—stay tuned.

👋 See you in the next series.

If you’re also building out your own GitOps system, I’d love to hear what approaches you’re trying.

DEV Community: JosephCheng

Designing a Maintainable GitOps Repo Structure: Managing Multi-Service and Multi-Env with Argo CD + Kro

🧨 When My GitOps Repo Became a Mess

⚙️ My Setup and What I Wanted to Achieve

📦 Why I Switched to Argo CD ApplicationSet

🗂 How I Structure My Git Repo

✍️ A Real ApplicationSet Example

🌳 How I Handle the Root App

🧼 Keeping Environments and Services Isolated

🛠 How This Structure Helps My Day-to-Day

✅ Why instance.yaml Is My Single Source of Truth

🧱 This Structure Is the Foundation for Promotion

🔜 Coming Up Next: Promotion with Kargo

From Kro RGD to Full GitOps: How I Built a Clean Deployment Flow with Argo CD

🧩 Why I Started with an RGD

🧠 What’s Kro, and Why RGD?

🛠 My First RGD: Starting Simple

📄 Template: How Schema Connects to Resources

📦 My instance.yaml: The Missing Piece

🔁 Full Automation: From Tag → Git → Kro Apply

💥 Pitfalls I Ran Into (and How I Fixed Them)

🧭 Where Kro Fits in My GitOps Architecture

🔎 Bonus: My Environment Setup

🔜 Coming Next: Designing a Clean GitOps Repo Structure

Why Argo CD Wasn't Enough: Real GitOps Pain and the Tools That Fixed It

The Starting Point: Argo CD as Our First GitOps Tool

The Problem: Too Many YAML Files, Too Much Maintenance

The Solution Appears: Discovering Kro

Why I Chose Kro Instead of Writing Raw YAML

TL;DR - The GitOps Workflow in One Diagram

So What's Next?

GitOps Promotion with Kargo: Image Tag Git Commit Argo Sync

🧩 What Do I Mean by “Promotion”?

1. Why Is Promotion the Most Critical Part of GitOps?

2. What Happens Without a Proper Promotion Process?

3. Why I Chose Kargo

4. Thinking in State Machines

5. Promotion Pipeline (Mermaid Diagram)

6. How I Configure the Warehouse

7. How I Define Stage Conditions

8. How yaml-update Handles Tag Precision

9. Why This Promotion Pipeline Is Reliable

10. What’s Next: Syncing Only the Right App

💬 Closing Thoughts: Promotion Can Be Clean

Implementing a Modular Kargo Promotion Workflow: Extracting PromotionTask from Stage for Maintainability

🧱 A GitOps-Native Upgrade Pipeline That Scales

🚀 From Flowchart to Real-World Workflow

🏗 Warehouse — Per-Service Image Tracking

Stage – From Embedded Logic to Task Delegation

PromotionTask — The Core of Modular Promotion Logic

Why Break Out Tasks? Because Templates Are the Long-Term Answer

Don’t Forget the Kargo Project — The Key to Automatic Promotion

Pitfalls I Hit (and How I Fixed Them)

Final Thoughts: From Design to Reality

How I Scaled My GitOps Promotion Flow into a Maintainable Architecture

📖 Introduction: From Promotion Flow to GitOps System Architecture

🧱 Architecture Layering: How I Used root-app + ApplicationSet to Manage Multiple Services

⚙️ Responsibility Decoupling: What Kro, Kargo, and Argo CD Actually Do

Kro: Declarative Templates + DAG-Defined Infrastructure

Kargo: Promotion Orchestration + Traceability

Argo CD: Git → Cluster Synchronization Only

♻️ Promotion Flow Design: From One Line to a Traceable System

Full promotion flow:

Why each step matters:

🧩 Modular & Maintainable Design: Making Promotion Logic Reusable

1️⃣ Stage ≠ Task: Split the Responsibilities

2️⃣ PromotionTask as Template: Parameterized, Reusable Logic

🧨 What I Broke (and How I Fixed It)

🧭 Why This System Was Worth Building

🔚 Final Thoughts: This Isn’t a Toolchain—It’s a System That Survives

📚 Wrapping Up This Series—See You in the Next One

📦 My `instance.yaml`: The Missing Piece

8. How `yaml-update` Handles Tag Precision