GitOps Workflow Pack

We built this pack so you don't have to reverse-engineer promotion pipelines from GitHub issues or trial-and-error. If you're managing multi-cluster Kubernetes, you know the pain. You push a commit, ArgoCD syncs dev, but promotion to staging requires a manual patch, or worse, a kubectl apply that nobody documented. You end up with a hybrid mess where Git is the source of truth in name only.

The Promotion Trap: Why GitOps Fails at Scale

We've all seen it. The ArgoCD UI shows green, but the production values are stale. You're using Flux, but the HelmRelease drifts because the syncPolicy wasn't propagated correctly across namespaces. The community debate around promotion is real and exhausting. A discussion on the ArgoCD GitHub repo highlights how teams struggle to configure promotion between environments in a truly GitOps fashion, often resorting to imperative workarounds that break when the cluster topology changes ^[1].

When you lack a standardized workflow, you build custom scripts that are brittle. We see teams trying to force a promotion model that fights the tooling. They mix yq patches with direct manifest edits, creating a configuration zoo that only one person understands. That person is on vacation when the incident happens. If you're also wrestling with CI/CD patterns, you might be missing the structural foundation that ties your pipeline to your cluster state [ci-cd-complete-pack].

The Hidden Costs of Manual Syncs and Drift

Ignoring this isn't just annoying; it's expensive. Every manual sync is a potential for human error. You push the wrong value. You forget to update the imageTag. You introduce a configuration drift that takes hours to detect. Production incidents caused by GitOps misconfiguration can drag MTTR well past the 30-minute mark. Best practices warn against common pitfalls like bridging IaC with GitOps incorrectly, which leads to state divergence ^[6].

When you lack automated validation, malformed configs slip through. We've seen countless repos where a simple validator would have caught a missing remediation block before it hit prod. Security drift is another killer. If your promotion pipeline doesn't enforce policy, you're leaking secrets or exposing ports. Teams that skip validation often find themselves needing a [devsecops-pipeline-pack] to retroactively patch compliance gaps, but by then, the drift is already in production.

The cost isn't just engineering hours; it's the erosion of trust. Stakeholders stop trusting the pipeline. They start clicking buttons. Once ClickOps enters your ArgoCD UI, the GitOps promise is dead. You lose the audit trail. You lose the ability to rollback with a single commit. You lose the confidence to deploy at scale.

How a Multi-Cluster Team Blew a Release Window

Imagine a platform team managing 15 clusters across three regions. They're using ArgoCD for state management and Flux for HelmRelease automation. Pure GitOps requires a strict model where Git is the single source of truth ^[2]. During a routine release, the staging Flux HelmRelease upgraded to v2.4.0. The promotion workflow was supposed to trigger a GitHub Actions job, extract the chart version via client_payload, patch the production HelmRelease with yq, and open a PR.

But the team had hardcoded environment variables in the ArgoCD ApplicationSet without using the Lovely Plugin's auto-injection mechanism. When the promotion PR merged, ArgoCD tried to sync, but the syncPolicy was overridden by a stale ARGOCD_ENV variable. The sync failed. The team spent 45 minutes debugging why the production cluster wasn't picking up the new image. Meanwhile, the validator script in their repo was failing on the staging branch, but no one noticed because the validation step was skipped in the promotion path.

This is the exact scenario that breaks when you don't have a cohesive workflow. If your architecture is complex, like when you're [migrating-monolith-to-microservices], these subtle configuration errors compound. You can't fix what you can't trace. The team ended up rolling back manually, missing the release window, and facing downstream questions from the product team.

What Changes When Promotion Is Automated

With the GitOps Workflow Pack installed, the promotion loop becomes deterministic. Errors are structural failures caught by the validator before they reach the cluster. When you install the skill, validate-gitops.sh parses your YAML templates and checks for required fields. If syncPolicy is missing, it exits non-zero. If the Lovely Plugin config is malformed, it fails. You get immediate feedback.

ArgoCD ApplicationSets now leverage the Lovely Plugin for environment variable propagation with the correct priority: PARAM > ARGOCD_ENV > bare. Helm patching per cluster works because the template references the correct context. Flux HelmRelease manifests include configurable rollback strategies and serverSideApply modes, mapping directly to the API specs. Tracking strategies in ArgoCD become reliable because the application spec correctly references the resource manifests ^[4].

You can implement progressive delivery patterns seamlessly, knowing the underlying GitOps layer is solid [progressive-delivery-pack]. The scripts/validate-gitops.sh becomes your gatekeeper. The tests/test-validation.sh harness runs against sample manifests, asserting expected exit codes. Drift-safe configurations pass; malformed ones fail. You sleep better.

What's in the GitOps Workflow Pack

We built this pack to give you the working code, not just theory. Here is the manifest:

• skill.md — Orchestrator skill that defines the GitOps workflow philosophy, explicitly references every other file by relative path, and provides step-by-step instructions for combining ArgoCD, Flux, and GitHub Actions into a cohesive promotion pipeline.
• templates/argocd-applicationset.yaml — Production-grade ArgoCD ApplicationSet leveraging the Lovely Plugin for environment variable propagation, Helm patching per cluster, and automated sync policies. Grounded in Context7 ArgoCD Lovely Plugin docs.
• templates/flux-helmrelease.yaml — Production-grade Flux HelmRelease with configurable rollback strategies, upgrade remediation retries, and server-side apply modes. Directly maps to Context7 Flux API v2 specifications.
• templates/github-actions-promotion.yaml — CI/CD workflow that triggers on Flux staging upgrades, extracts chart versions via client_payload, patches production HelmRelease manifests with yq, and opens promotion PRs. Based on Context7 Flux promotion patterns.
• templates/kustomize-helm-composition.yaml — Kustomization overlay that transparently composes Helm chart output using the Lovely Plugin's auto-injection mechanism, demonstrating hybrid templating for complex microservice deployments.
• scripts/validate-gitops.sh — Executable validator script that parses YAML templates, checks for required GitOps fields (syncPolicy, remediation, plugin config), and exits non-zero (exit 1) on structural or semantic failures.
• tests/test-validation.sh — Test harness that executes the validator against sample manifests, asserts expected exit codes, and verifies that drift-safe configurations pass validation while malformed configs fail.
• references/argo-cd-workflows.md — Canonical reference embedding ArgoCD environment promotion patterns, Lovely Plugin configuration priority (PARAM > ARGOCD_ENV > bare), Git checkout mode requirements, and Hera template rendering workflows.
• references/flux-rollback-strategies.md — Canonical reference embedding Flux HelmRelease rollback configuration fields (timeout, disableWait, cleanupOnFail, serverSideApply), legacy migration notes, and automated remediation best practices.
• references/gitops-repo-structure.md — Canonical reference detailing multi-tenant GitOps repository layouts, App-of-Apps patterns for microservices decomposition, namespace isolation strategies, and GitOps toolkit API versioning (v1 graduation).
• examples/worked-example.yaml — Complete worked example demonstrating a full promotion path: staging HelmRelease upgrade triggers GitHub Actions, which patches production, while ArgoCD ApplicationSet handles cluster-specific overrides via Lovely Plugin.

This pack covers the full stack. From the orchestrator skill.md to the validator scripts. It includes references on ArgoCD workflows, Flux rollback strategies, and repo structure. You get the examples/worked-example.yaml that demonstrates the full promotion path. If you're also handling [release-management-pack], this pack integrates with your version strategy. If you're doing [implementing-database-migrations], the promotion flow ensures schema changes sync with app deployments.

Ship GitOps That Actually Works

Stop guessing. Stop manual promotions. Upgrade to Pro to install the GitOps Workflow Pack. This is the infrastructure you need for multi-cluster, multi-team Kubernetes. For [kubernetes-deploy-pack], this provides the delivery mechanism. And for [migration-playbook-pack], this ensures your cutover is Git-driven. Install the skill, run the validator, and ship with confidence.