Bring your Argo CD apps into ConfigHub

1. What changes, and what does not

Argo CD stays the delivery controller. Preview has no account or cluster mutation; import makes a parallel ConfigHub copy while Git still delivers; handover then moves sources to reviewed releases. Handover has checks and recovery steps, not zero risk.

For an app-of-apps estate, ConfigHub keeps the root management structure and its parent-to-child relationships visible. Argo CD still renders charts and reconciles the descendants. The plan inventories descendant Applications and their rendered objects so you can inspect what the root governs; controller-generated or live objects remain evidence unless you deliberately choose them as desired configuration.

Start with a small disposable estate. Roots, generators, and pruning can make production migration an ordered fleet operation.

Who does what, before and after

The handover is the step that moves the source of truth. Until handover.sh runs, ConfigHub holds a copy that nothing reads. The Argo CD install, AppProject permissions, sync windows and cluster credentials stay where they are.

Some teams on Flux? Bring your Flux fleet into ConfigHub follows the same steps.

2. Preview the setup

Install the cub CLI and this released plugin:

cub plugin install confighub/examples@cub-argo-v0.4.1 --name argo

What you need: a local checkout of the Git repository this Argo CD installation reads, the cub CLI, and this plugin. Start in that repository's root; replace the directory placeholder below with its path. Planning reads the repository and needs no ConfigHub account or cluster.

cd <your-argo-gitops-repository>
cub argo plan .

Read the result. The summary gives the estate or fleet size and the component and variant counts. The following lines map shared configuration to bases and cluster differences to variants. Check the stage order and warnings before continuing. This plan does not validate the destination.

Argo CD estate: 1 cluster, Argo CD's own (in-cluster), 2 components, 2 variants
Read 9 objects

Control tree (stays as it is: this is the management record)
  Application apptique-apps                  wave   0  root, applied by hand
    Application apptique-dev                 wave   0  deploys workloads; planned below
    Application apptique-prod                wave   0  deploys workloads; planned below

One stage, fleet (pass --stage-label and --stages to roll out in waves)

apptique-dev  (Application, project default, wave 0)
  base     argo-apptique-dev-base  reaches no cluster: its destination is empty
  each variant differs from the base in spec.destination
  stage fleet
    in-cluster  variant argo-apptique-dev-in-cluster  ->  Target argo-targets/in-cluster
                Application apptique-dev, namespace apptique-dev
                gitops/argo/beginner-app-of-apps/manifests/apptique/dev
  note     a plain directory of manifests, read as Argo CD reads it: every .yaml, .yml and .json file at the top level

apptique-prod  (Application, project default, wave 0)
  base     argo-apptique-prod-base  reaches no cluster: its destination is empty
  each variant differs from the base in spec.destination
  stage fleet
    in-cluster  variant argo-apptique-prod-in-cluster  ->  Target argo-targets/in-cluster
                Application apptique-prod, namespace apptique-prod
                gitops/argo/beginner-app-of-apps/manifests/apptique/prod
  note     a plain directory of manifests, read as Argo CD reads it: every .yaml, .yml and .json file at the top level

Handover, when this estate is live (apply will write it as handover.sh; plan runs nothing)
  1. check Argo CD is v3.1 or newer, which is where an oci:// source is read natively; an older one cannot do this at all
  2. repoint Application apptique-apps at argo-apptique-apps-children, which would hold Application apptique-dev, Application apptique-prod. Publish that Space first: a parent left syncing an empty source prunes its children. Nothing above it syncs it, so patch its spec.source in the cluster.
  3. never delete apptique-apps, apptique-dev, apptique-prod: resources-finalizer.argocd.argoproj.io deletes everything it deployed. Every step above is a patch for exactly this reason

Next
  cub argo apply . --out ./argo-onboarding
  That writes apply.sh, handover.sh and cleanup.sh. It runs nothing.

Read the full Argo CD planning reference for layouts and limits.

Try it on the fixture first

These commands print the output above. They need no repository of your own.

git clone https://github.com/confighub/examples.git
cd examples
git checkout 7f1b8f2fc849bb6488bc2c58f1469172018fc9dd
cd gitops/argo/beginner-app-of-apps
cub argo plan .

Run the plan inside a Git checkout. In a copy with no .git directory the plan reports source paths as missing, and --repo-root <checkout> tells it where the repository starts.

What one Application becomes

cub argo apply . --out onboard writes files only. For each Application it writes the copy Argo CD has today under onboard/control/, and the copy it would have after the handover under onboard/repointed/. Each copy sits in a folder named for the Space that holds it, which is argo-apptique-apps-children on the fixture. The two copies of apptique-dev differ in three lines.

 kind: Application
 metadata:
   name: apptique-dev
 spec:
   source:
-    repoURL: https://github.com/confighub/examples.git
-    targetRevision: main
-    path: gitops/argo/beginner-app-of-apps/manifests/apptique/dev
+    repoURL: oci://<gateway>/space/argo-apptique-dev-in-cluster
+    path: .
+    targetRevision: latest

The Application keeps its name, project, destination and sync policy. It reads the Space the plan names as its variant, argo-apptique-dev-in-cluster.

An Application with helm or kustomize settings under source loses those settings in the repointed copy, because what Argo CD reads afterwards is already rendered. The fixture has no such Application, so this page shows none.

How to go back