Migrate Jenkins deployment jobs to Argo CD without moving your builds
Jenkins keeps building and testing, and Argo CD takes over deployment. For a team whose Jenkins jobs run kubectl or helm against production clusters, the goal is to stop those jobs from pushing changes into the cluster and have Argo CD pull the desired state from Git instead. How much work this takes depends on how many jobs, environments and cluster credentials are involved, and on how many jobs share deploy logic. This section gives no effort figure. Ask for one only after the inventory described below is complete.
Most of the work is redesign, not data migration. The deploy stage of each pipeline is replaced by a step that commits a change to a config repository, typically an image tag update in a Helm values file or a Kustomize overlay, and then lets Argo CD reconcile it. Teams need to decide the repository layout, which environments are promoted by pull request, who approves those pull requests, and how the Jenkins service account loses write access to the clusters. Before any job is changed, list every credential the jobs use, every namespace they touch and every script that runs kubectl directly, because those are the places where a deploy can bypass Git. Plan a period in which both paths exist and confirm that Argo CD shows the expected state for each application before the Jenkins deploy stage is removed.
Two things need confirmation with your own environment before you commit to a design. First, check which Argo CD minor release you will run and whether the repository credentials will be stored as Kubernetes Secrets, since Argo CD 3.0 removed repository configuration from the argocd-cm ConfigMap. Second, decide how Jenkins authenticates to Git for commits, and whose identity appears in the audit trail. Git history will become your deployment record, so the commit author, the signed or reviewed change and the Argo CD sync history should together answer who changed what and when. For the upgrade details, read the Argo CD upgrade notes for 2.14 to 3.0 before you fix a version.
Which Jenkins deployment capabilities map to Argo CD and which do not
This table compares the deployment steps most Jenkins jobs perform with their closest Argo CD equivalent, and marks where the step needs redesign rather than a direct swap. Read each row against your own jobs: a mapped capability still needs a Git-based workflow, and a redesign row usually means the step moves out of the pipeline entirely. Plugin behavior should be confirmed against the plugin's own documentation before you assume equivalence.
| Jenkins capability | Argo CD equivalent | Redesign needed |
|---|---|---|
| kubectl apply step | Argo CD syncs manifests from a Git path it tracks | Yes: move manifests into a config repository and remove cluster credentials from Jenkins |
| helm upgrade with ad hoc --set flags | Helm source in an Application with values files committed to Git | Yes: every flag must become a versioned values file or parameter |
| Image tag bump in a script | Commit to the config repository, or an Image Updater setup if you adopt it | Yes: confirm the update mechanism and who approves it |
| Environment promotion by job parameter | Promotion by pull request between environment paths or branches | Yes: promotion becomes a reviewed change, not a parameter |
| Manual approval input step | Approval on the pull request, enforced by branch protection in your Git host | Yes: confirm your Git host's review rules meet your change policy |
| Rollback by rerunning an older job | Revert the commit in Git, then Argo CD syncs the previous state | Partly: confirm that resources and database changes also roll back cleanly |
| Build notifications through plugins | Argo CD Notifications, configured separately from the build | Confirm: notification triggers and channels must be reconfigured, not copied |
| Credentials looked up during deploy | Secrets delivered through the destination cluster or a secrets operator | Yes: deploy-time lookups must be removed from pipeline logic |
Documented paths for moving deploy logic out of Jenkins
The most direct path replaces the Jenkins deploy stage with a job that edits a manifest in a Git config repository and commits the change. Argo CD detects the new commit and syncs it to the cluster, so Jenkins no longer needs kubectl access or cluster credentials. The Git history then becomes the record of each deployment.
- What it gives: Each deploy is a commit with an author, a reviewer and a timestamp, which serves as the audit trail for change decisions.
- Image tag updates: The job rewrites the image tag in a values file or Kustomize overlay, usually with a small tool such as
yqorkustomize edit, then commits or opens a pull request. - Promotion by pull request: Moving a version from staging to production can require a reviewed pull request, enforced by branch protection on the config repository.
- What it cannot do: The commit does not confirm that the rollout worked. The Jenkins job must read Application health and sync status if a later stage depends on the result.
- Credential scope: The Jenkins credential needs push access to the config repository only, ideally through a bot account limited to that repository.
Check the branch protection rules, the scope of the Jenkins credential, and how the job handles merge conflicts when two builds update the same file at once.
If releases are installed with helm upgrade today, you can keep the charts and move the values files into Git. Argo CD renders the chart itself, so the Helm release state that Jenkins used to manage is replaced by Application resources. Generating Applications from a list of services and environments avoids writing each one by hand.
- What it gives: Charts stay unchanged, and per-environment values move into Git where they can be reviewed like any other change.
- Application generation: A template or script can produce one Application per service and environment. ApplicationSets are the documented mechanism for this, but confirm which generator types the current release supports before designing around them.
- Release state: Argo CD does not write Helm release records the way the helm CLI does, so commands such as helm list stop showing these releases. Tell the operations team before the cutover.
- What it cannot do: It does not reproduce a helm rollback or the Jenkins step that ran helm test. Rollback and test need their own documented process.
- Repo-server exposure: The repo-server runs Helm and Kustomize on repository content, so only chart sources and repositories your team controls should be configured. The Argo CD security documentation explains this risk.
Confirm which Helm features your charts depend on, including hooks and any template functions that behave differently outside the helm CLI, and render each chart in a non-production cluster before switching.
By default, Argo CD checks Git on a polling interval. A webhook from the Git host to Argo CD's webhook endpoint asks Argo CD to refresh an application when the repository changes, so a commit from the Jenkins job takes effect sooner. The webhook shortens the wait but does not replace periodic reconciliation, which remains the safety net. Confirm the endpoint path, payload handling and secret settings in the current release documentation before configuring anything.
- What it gives: Faster reaction to config commits without an extra Jenkins step, and a clearer link between a commit and the sync that follows.
- Shared secret: Configure a webhook secret on both the Git host and Argo CD so that unsigned or mis-signed requests are rejected. Confirm the exact setting names for your version.
- Jenkins role: Jenkins does not have to call Argo CD in this path. If a job calls the API to trigger a sync, that call needs a dedicated Argo CD account with only the sync permission for the target applications.
- Token handling: API requests are authenticated with JSON Web Tokens, so store the Jenkins token in the Jenkins credential store and rotate it on a schedule your security team sets.
- What it cannot do: A webhook only triggers a refresh. It does not confirm that the deploy succeeded, so health and sync status still need to be checked separately.
Test the webhook against a non-production repository, confirm that a request with a wrong secret is refused, and verify the network path from the Git host to Argo CD.
The Jenkins Configuration as Code (CasC) plugin configures Jenkins itself from YAML files. It locates them through the CASC_JENKINS_CONFIG variable, which defaults to $JENKINS_HOME/jenkins.yaml. After the split, the Jenkins controller still builds and tests, so CasC makes its settings reproducible. The CasC plugin page documents what it configures. It does not install plugins, so plugin versions must be pinned through a Docker image or the Helm chart.
- Scope: CasC configures Jenkins settings such as the security realm, credential references and agent definitions. It is not a deployment tool for Kubernetes.
- Plugin installation: Pin plugins in the image or chart so that the controller starts with a known set. This is a separate step from writing jenkins.yaml.
- Bundled plugin change: The Jenkins LTS changelog reports that LTS 2.580.1 stopped bundling several plugins, including the bouncycastle API, SSH server and JUnit plugins. Install them explicitly if your builds use them.
- Secrets: Keep credential values out of jenkins.yaml and reference secrets supplied by the environment. Jenkins keeps configuration, plugins and secrets in $JENKINS_HOME on the controller, so include that path in backups.
- Pipeline files: Jenkinsfiles stay in source control and continue to define the build and test stages that remain in Jenkins after the split.
Check that every plugin used by the remaining build and test jobs is pinned, and remove the old deploy credential from Jenkins once Argo CD owns the cluster.
Sequence for a parallel run and cutover from Jenkins deploys
This sequence moves deploy ownership from Jenkins to Argo CD one namespace and one service at a time, so each cutover is verified against Argo CD's sync and health states before Jenkins stops writing to the cluster.
Inventory deploy jobs and their credentials
Your team lists every Jenkins job that changes a cluster, including kubectl apply, helm upgrade and helm install calls, the namespaces and clusters each one targets, and the credentials it uses, such as kubeconfig files, service account tokens and cloud roles. DeployOpen can run this inventory with your platform engineers as a fixed input to the scope. The step is done when each deploy job maps to one target environment, one owning team and one config repository path, and every credential has an owner and a planned removal point.
Pilot one service in a non-production namespace
Choose one low-risk service and one non-production namespace. Create the Argo CD Application pointing at the config repository, move the manifests or chart values there, and let Jenkins build the image and commit the new tag through a pull request. Keep the Jenkins deploy stage running against a separate namespace so the two paths do not touch the same resources. The step is done when a commit to the config repository results in a synced and healthy Application, and the rollback has been tested by reverting that commit.
Run both paths without double writes
For each service in the parallel run, decide which path owns the live resources at any moment. Jenkins can keep running its deploy stage in a shadow namespace or run it as a dry run that reports differences, while Argo CD owns the production-like namespace. Use Argo CD's diff view and the Application sync status to compare the rendered output with what Jenkins would apply. The step is done when the comparison shows no unexplained drift and no two controllers reconcile the same resources.
Verify sync and health states before cutover
Treat Argo CD's documented Application sync status (Synced or OutOfSync) and health status (Healthy, Progressing, Degraded, and others) as the verification signal for each service. A cutover candidate should reach Synced and Healthy after a normal Git change, and a deliberately broken change should show Degraded or a failed sync that the team can read and recover from. The step is done when the on-call team has seen both outcomes and agreed the signals are sufficient to decide.
Cut over one service or environment at a time
Move ownership service by service and environment by environment, starting with the lowest-risk and ending with production. For each cutover, first disable the Jenkins deploy stage for that service only after Argo CD owns its resources and the Application reports Synced and Healthy. Keep the Jenkins job available for a defined rollback window so the previous path can be restored. The step is done when each service has a dated record of its owner change, the Jenkins stage is disabled, and no Jenkins run has written to its namespace since.
Disable Jenkins deploy stages only after ownership moves
Remove or disable the kubectl and helm stages in each Jenkinsfile only after Argo CD has reconciled the resources for that service. Disabling the stage first can leave resources unmanaged, and running both paths can cause an OutOfSync loop. Keep the build and test stages in Jenkins. The step is done when the Jenkinsfile for each migrated service contains only build, test and config repository commit steps, and the pipeline history shows no cluster writes after the change.
Decommission Jenkins deploy credentials
After the rollback window closes for a service, revoke the kubeconfig files, service account tokens and cloud roles that Jenkins used to write to the cluster, and remove them from Jenkins credential stores. Confirm that the Argo CD cluster registration and repository credentials are the only write paths left, and that the credential removal is recorded in your change system. The step is done when a fresh search of Jenkins credentials shows no cluster write permissions for the migrated namespaces, and the audit trail links each commit to the Argo CD sync that deployed it.
Webhooks for fast refresh and an audit trail built from Git history
A Git webhook lets Argo CD refresh an application as soon as the config repository changes, instead of waiting for its periodic poll of the repository. In a Jenkins migration this matters because the Jenkins job's last step is now a commit that bumps an image tag, and the deployment should start from that commit without a delay. The webhook sends a notification from the Git host to Argo CD, which then re-reads the repository and compares it with the live cluster. Polling still runs as a fallback, so a missed or failed webhook delays a sync but does not block it. Setup depends on your Git host and on the Argo CD version you run, so confirm the exact endpoint, payload, secret handling and supported events in the Argo CD webhook documentation for that version before you cut over. Plan the webhook secret as a credential, and check how it is stored and rotated.
Webhooks also open the API endpoint that receives them to traffic from your Git host, which the Argo CD security documentation treats as a hardening concern. Decide which network path the Git host uses to reach Argo CD, restrict it where the host supports fixed addresses, and confirm that the webhook secret is validated on every request. Keep the Argo CD API and UI behind your normal access controls, because a webhook must not become a second way in.
The audit trail for deployments comes from three records that already exist once Jenkins stops applying changes directly. The config repository history shows who changed an image tag or manifest, when, and in which commit. Pull request approvals show who reviewed and accepted the change, which is where separation of duties is enforced. Argo CD's sync history shows what it applied to each cluster and when. Together they answer the questions an auditor asks: what changed, who approved it, and what ran. Confirm that your Git host retains approval records and branch protection settings for the period your policy requires, and that Argo CD retains its history long enough to match, since its retention is a setting you control. Match Jenkins build records to the commit that bumped the tag so each deployment traces back to a build and a test run.
What drives the effort of moving Jenkins deploy jobs
The effort of moving Jenkins deploy jobs to Argo CD depends less on the number of pipelines than on how much deployment logic lives inside them and how many people and clusters depend on it. The cards below separate the one-time migration work from the costs that keep recurring after cutover, so you can scope a quote against your own estate.
Deploy jobs and shared libraries
Count the Jenkins jobs that run kubectl or helm, and the shared libraries they call. A single shared library that wraps deployment steps may change many jobs at once, while a job with custom Groovy logic that patches manifests in place needs that logic re-expressed as Git changes or rendering tooling. Inventory each job by what it actually changes in the cluster, not by its name. Ask for this inventory to be part of the written scope.
Clusters and environments
Each cluster and each environment in the promotion path needs its own destination definition, its own Application or ApplicationSet, and its own sync and health verification. The number of clusters multiplies the configuration to write and test, and it sets how much recurring work each new environment adds. Confirm which environments are production, which are shared, and whether any sit in segmented networks where Argo CD needs a reachable path.
Helm charts versus raw manifests
Pipelines that run helm upgrade need a decision on whether Argo CD renders the chart, or whether CI renders manifests and commits them to the config repository. Each option changes what the config repository contains, how values files are versioned, and how diffs look in pull requests. Raw manifests are simpler to review, while charts with many value overrides often need a clear values layout before migration begins.
Credential storage and scope
Jenkins often holds kubeconfig files, service account tokens or cloud credentials as stored secrets that many jobs can read. Moving deployments to Argo CD removes cluster write access from CI, but Argo CD still needs repository credentials and cluster registrations, and those must be defined as Kubernetes Secrets. Inventory each stored credential, who can read it, and which deploy paths it reaches, then decide which ones are retired and which are re-scoped.
Approval and promotion rules
Approvals that sit in Jenkins input steps, change tickets or manual job parameters must be mapped to pull request reviews, protected branches and sync windows. This mapping is a one-time design task, but each environment promotion afterwards depends on it, so rules that were implicit in Jenkins need to be written down. Ask who approves production changes today and whether that role can review a pull request in the config repository.
Teams sharing the Jenkins controller
When several teams share one Jenkins controller, their deploy jobs often share plugins, folder permissions and global credentials, which makes each migration step affect more than one team. Splitting deployment ownership into per-team repositories and Argo CD projects can reduce that coupling, but each team needs its own review, onboarding and access model. Recurring effort grows with the number of teams that must request changes to shared Argo CD configuration.
Questions teams ask before moving Jenkins deploys to Argo CD
What does it cost to move Jenkins deploy jobs to Argo CD?
The cost depends on how many deploy jobs exist, how varied they are, and how much of the surrounding setup must change. Argo CD itself is licensed under Apache-2.0 with no paid edition from the project, so the spend is labor, infrastructure and any vendor support you choose. Costs split into one-time work (repository design, Argo CD installation, SSO and RBAC, rewriting each deploy stage, cutover testing) and recurring work (patching, upgrades, on-call and access reviews). Drivers that push the cost up include credentials that are hard to retire, deploys that run ad hoc helm or kubectl commands, and many clusters or environments. When you ask for a quote, request a line item per job family, the repository layout assumed, and what is excluded, such as Jenkins changes that are not deploy-related.
How long does a Jenkins to Argo CD migration take?
Duration is driven by the number of pipelines to split, the number of environments, and how many deploy paths run through shared libraries. Work usually moves in waves: first a pilot application, then one team or environment at a time, so each cutover can be checked before the next. No researched timeline applies to your estate, so confirm the duration with a written scope that lists the applications, clusters and environments included. Ask for the cutover order, the pilot criteria and the point at which Jenkins deploy stages are disabled for each application. Also check when the Argo CD version you deploy will need an upgrade, since the project's release process ships a minor release four times a year and patches only the three most recent minor lines.
What does the work need from our internal team?
Your team must own decisions that an outside party cannot make for you: which Git repositories hold configuration, who approves production changes, which identity groups map to Argo CD roles, and which clusters Argo CD may reach. Engineers who know the current Jenkinsfiles and shared libraries are needed to confirm what each stage actually does, including hidden steps such as secret retrieval or post-deploy checks. Platform engineers need to be available for cluster access, network paths for webhooks and TLS. Security and compliance staff should review the RBAC model and the audit trail design before the first production sync. Plan these commitments early, because they usually set the pace of the migration more than the Argo CD configuration itself.
Can our own team do this migration without a partner?
Yes, many teams do this in-house, and the work is well documented. The main risks are the places where Jenkins has been doing more than deploying: credential handling, environment-specific logic, and manual steps that nobody has written down. A capable internal team should inventory every deploy job, decide the repository layout, and run a pilot before moving the rest. Outside help is most useful when the team lacks Kubernetes or Argo CD production experience, has a short window for cutover, or needs independent hardening and evidence for an assessment. Whichever way you go, compare an internal plan and a partner's fixed-scope proposal against the same list of deliverables and exclusions.
Do we have to replace Jenkins to deploy with Argo CD?
No. Jenkins is a build and test system, and the usual pattern keeps it in that role. Its pipelines still compile code, run tests, build and scan images, and then commit an updated image tag or manifest to a configuration repository. Argo CD watches that repository and performs the deploy, so the Jenkins deploy stages and the cluster credentials they held are removed. Jenkins is distributed under the MIT License, and it can keep running on its current Java and LTS baseline as long as you follow its support policy. Confirm which Jenkins plugins your build stages depend on, because some plugins stopped being bundled in the 2.580.1 LTS release and must be installed separately.
How does rollback work during cutover?
Rollback works best when each application has one deploy path at a time. Before cutover, keep the existing Jenkins deploy job available but disabled for the application, and record the last known good image tag and manifest revision. If the Argo CD sync fails or the result is wrong, revert the commit in the configuration repository or sync the application to the previous revision, then re-enable the Jenkins job only after confirming there is no second controller reconciling the same resources. Avoid running both paths against the same namespace for longer than the pilot needs. Ask your partner or internal lead to write the rollback steps per application and to rehearse them on a non-production cluster before the production window.
What should we check before turning off Jenkins deploy credentials?
Check that every deploy path that used those credentials has been moved, that Argo CD can reach each destination cluster with its own registered credentials, and that no scheduled Jenkins job still applies manifests. Confirm that Argo CD repository credentials are stored as Kubernetes Secrets, because Argo CD 3.0 removed repository configuration from the argocd-cm ConfigMap. Review who can change Argo CD Applications and projects, and disable the built-in admin user with admin.enabled set to false once SSO or local users are configured. Keep an audit trail that links each production change to a Git commit, a pull request approval and an Argo CD sync record, since this evidence is what reviewers usually ask for.
What your team provides and what you receive
Your team supplies the inputs that make the mapping accurate. The most important is the Jenkins job inventory: every pipeline or freestyle job that runs a kubectl apply, kubectl set image or helm upgrade step, with the target cluster, namespace and environment it touches. DeployOpen also needs read access to each Jenkins controller, the plugin list (including the Kubernetes and Configuration as Code plugins if they are in use), and a copy of any $JENKINS_HOME backup so credentials and shared libraries can be traced. Git hosting access is needed to create the config repository and to set branch protection and repository permissions. For the Argo CD installation, you provide cluster-admin or equivalent access on each destination cluster, plus the namespace and ingress decisions. Name a single owner for each environment who can approve cutover, because that owner will also approve the pull requests that change production.
In return, DeployOpen delivers a set of written artifacts that match the agreed scope. These are the mapping inventory that records each Jenkins job, its deploy step, its Argo CD Application or ApplicationSet replacement and its owner; the config repository layout with directory structure, environment folders and the image tag update pattern; the Application definitions as versioned manifests; a cutover runbook that sets the order of job retirement per environment; and a rollback plan that states how each Jenkins deploy job is reinstated and how Argo CD sync is paused. Confirm with your DeployOpen contact which of these artifacts are in the fixed scope, which are optional, and how any change to the inventory after sign-off is priced. Ask for the acceptance criteria for each deliverable before work starts.
How DeployOpen scopes and delivers a Jenkins to Argo CD migration
The sequence turns an inventory of Jenkins deployment jobs into a written scope, a pilot, a parallel run and a cutover, so that Argo CD takes over deployments from Git while your team keeps the Jenkins builds and tests it already trusts.
Inventory every Jenkins deployment job
DeployOpen reviews the Jenkinsfiles, shared libraries, credentials and plugins behind each job that deploys, and records the target cluster, namespace, release method (kubectl, Helm or raw manifests) and the owner of each pipeline. The inventory also notes which jobs build, which only deploy, and which run ad hoc steps that never reach Git. The step is done when your team has signed off on a single list of in-scope jobs and their targets.
Agree the target repository layout
Together, DeployOpen and your platform team decide how the config repository is structured: one path per application and environment, how Helm values or Kustomize overlays are arranged, and who may merge to each environment branch. Decisions on Argo CD project boundaries and the SSO groups that map to them are recorded here, since they shape who can change what. The output is a written layout and access model that your security and change teams can review before any code is moved.
Split build from deploy in a pilot pipeline
DeployOpen converts one representative Jenkins job so that Jenkins still builds, tests and pushes the image, then, instead of running kubectl or helm, commits the new image tag to the config repository through a pull request or a direct commit, as your policy requires. Argo CD is connected to that repository and pulls the change. The pilot is complete when a build produces a Git commit, Argo CD reports the application as Synced and Healthy, and the Jenkins job no longer holds cluster credentials.
Configure webhooks and the audit trail
The pilot is extended with a webhook from the Git host so Argo CD refreshes on push rather than waiting for its polling interval, and the webhook secret is stored and rotated under your existing process. DeployOpen also confirms that each deployment can be traced from the Jenkins build number, the commit author, the merged pull request and the Argo CD sync history. The check is a test change that you can follow end to end from the Jenkins build to the running cluster state.
Run old and new paths in parallel
For a defined period agreed in the scope, the migrated jobs and the original deployment steps run side by side against a non-production environment, and DeployOpen compares the resulting cluster state after each run. Differences in manifests, labels, resource ownership or hook behavior are logged and fixed in the layout or templates. The step closes when your team accepts the comparison results and the open differences are either resolved or documented as accepted risks.
Cut over job by job
Each in-scope job moves to the Argo CD path in an agreed order, and the old deploy stage is removed from the Jenkinsfile in the same change so that two systems never reconcile the same resources. Cluster credentials that Jenkins used are revoked once the last job for that cluster has moved. The output is a cutover record per job showing the date, the change reference and the verification run.
Hand over runbooks and ongoing support
DeployOpen delivers the documentation for the config repository, the Argo CD setup, the Jenkins changes, the webhook configuration and the rollback steps, and walks your operators through them. Ongoing support, Argo CD upgrades and continuous testing can be covered by an optional retainer, which is agreed separately from the fixed-scope work. The handover is complete when your team runs a routine change and a rollback on their own.
