Migrate from CircleCI to Jenkins

Migrate from CircleCI to Jenkins: what the move involves

A team facing a CircleCI renewal, credit pressure or a data residency requirement should know early that the move is a pipeline rewrite plus secret re-entry, not a file copy. Each .circleci/config.yml has to become a Jenkinsfile committed to the project's repository, with workflows mapped to stages, Docker executors mapped to Kubernetes pod agents, and orbs replaced by plugins or shared libraries. Environment variables and contexts cannot be exported from CircleCI, so every secret must be re-entered into Jenkins credentials and the old values rotated as part of the cutover. Platform engineers usually own this work, supported by a small group of application owners who know which builds, test suites and deploy steps matter. The effort depends less on the number of repositories than on how many orbs, custom executors and context-scoped secrets each pipeline uses, and on how much of the pipeline logic lives in CircleCI-specific features. Confirm the inventory of orbs and contexts with each owner before estimating anything, and ask any implementation partner for a written scope that lists each pipeline to be converted and the test criteria for accepting it.

Jenkins is distributed under the MIT License, so the platform can run entirely inside your own cloud accounts, data centers or isolated networks, and the controller, agents, plugins and secrets stay under your control. That is the main reason residency-driven teams choose it. Costs shift from metered credits to infrastructure you run: controller and agent compute, storage for $JENKINS_HOME, backups, and the recurring work of applying LTS releases and plugin updates on the schedule your team sets. Ask for a quote that separates one-time conversion work from these recurring operating costs. Run the old and new pipelines in parallel for a defined period before CircleCI access ends, and keep artifacts exported before the CircleCI retention window closes. Plan for the risks that most often cause delays: plugins that are no longer bundled with the current LTS line and must be installed separately, unclear ownership of the controller and its backups, and secrets that were never documented. Confirm the Jenkins LTS release you will standardize on and the Java version it requires against the Jenkins support policy before the first pipeline is converted.

Which CircleCI features map cleanly to Jenkins and which need rework

This table maps each CircleCI feature that a pipeline depends on to its closest Jenkins equivalent and labels it clean, needs rework or gap. Jenkins Pipeline is defined in a Jenkinsfile committed to source control, written in Declarative or Scripted syntax, so every row describes what moves into that file or into the controller and agents. Read the rework rows first, because they set the effort for the migration.

CircleCI feature	Jenkins equivalent	Status	What to plan for
Workflows and jobs	Stages and parallel stages in a Jenkinsfile	clean	Job ordering and fan-out move into stages and parallel blocks. Check that each job's dependencies are explicit in the new file.
Docker executors	Kubernetes pod agents via the Kubernetes plugin	needs rework	Each executor image becomes a pod template or container step. Confirm the cluster, namespace and image pull access before rewriting.
Orbs	Jenkins plugins or shared libraries	needs rework	Orb logic has no direct copy. Map each orb to an installed plugin or to a shared library function that your team maintains.
Contexts	Jenkins credentials scoped to folders or jobs	needs rework	Context values cannot be read back from CircleCI, so each secret must be re-entered from its source and rotated. Scope credentials to the narrowest folder.
Resource classes	Agent sizing through pod resource requests and limits	needs rework	Size agent pods per stage rather than per job. Expect to tune requests after observing real build runs on your own cluster.
Caches	Persistent volumes, shared agent workspace or external cache storage	gap	Jenkins has no built-in equivalent of CircleCI's cache keys. Plan a cache location and an invalidation rule before cutover.
Artifacts	archiveArtifacts step on the controller, or upload to external object storage	needs rework	CircleCI keeps artifacts for 30 days, so export them first. Choose where long-term artifacts live, because controller disk fills quickly.
Configuration and plugins	Jenkins Configuration as Code and the plugin manager	clean	Controller settings can be stored as YAML, but Configuration as Code does not install plugins, so pin plugins through images or the Helm chart.

How a config.yml becomes a Jenkinsfile

The translation runs in one direction: CircleCI jobs become Jenkins stages with steps, workflow dependencies become stage ordering and parallel blocks, and the Docker image each job runs in becomes a pod template on a Kubernetes agent type. Start by listing every job in .circleci/config.yml, then group jobs by the agent image they need. Each group usually maps to one pod template, so you can see how many agent types the Jenkins controller must know about before writing any pipeline. Where a CircleCI job relies on a machine executor, a macOS or Windows executor, or a resource class, confirm with your platform team which agent is available to Jenkins before you rewrite that job, because the Kubernetes plugin describes pod agents and does not replace those build environments. Plan to review a few representative jobs by hand, since the Jenkinsfile syntax is Declarative or Scripted and the exact mapping depends on your pipeline structure.

Jenkins Configuration as Code can define the controller's settings, such as security realm, cloud definitions and credentials references, in YAML files located through the CASC_JENKINS_CONFIG variable, which defaults to $JENKINS_HOME/jenkins.yaml. The plugin does not install plugins, so the plugin list must be managed separately, typically by baking it into a Docker image or by using the Helm chart described in the Jenkins Kubernetes installation guide. Keep the list of plugins that your migrated pipelines depend on in version control next to the YAML, and check it against the plugins CircleCI orbs replaced. Recheck that list at every LTS upgrade, because the 2.580.1 changelog notes that several previously bundled plugins must now be installed explicitly.

What can leave CircleCI and what must be re-created

A CircleCI to Jenkins move splits into two groups: items that leave CircleCI through documented paths, and items that Jenkins must hold again in its own configuration. Plan the export first, because build artifacts expire on a fixed schedule and environment variable values cannot be read back from the CircleCI app.

Pipeline config in the repositories

The repository is the main export path. Each project's .circleci/config.yml, along with any packed or shared config it references, already lives in Git and moves with the code. Before conversion, inventory every branch and tag that carries a CircleCI file, the orbs each one calls and the pipeline parameters it expects. Those references decide which Jenkinsfile stages and plugins you need to write, so the inventory is the input to the conversion plan.

Build artifacts before the window closes

CircleCI keeps artifacts for 30 days, which is both the default and the maximum. Anything you need for audit, rollback or a release record must be downloaded before that window closes, ideally through the API in a scripted sweep. Decide which artifacts are release-critical, such as test reports, signed packages and SBOMs, and store them in a location you control. Build logs and job history generally have no export path of their own, so record the outcomes you need as artifacts or in your ticketing system.

Environment variables that must be re-entered

CircleCI does not display environment variable values once they are set, so the values cannot be copied out of the app. Build a register of every variable name, the context it belongs to and the system that issues the value, such as a cloud account, container registry or signing key. Re-enter each value into Jenkins credentials from its owner, not from a copy. Where a value is uncertain or may have been exposed, rotate it during the move instead of carrying it across.

Forge webhooks and repository connections

Jenkins does not inherit the connections that CircleCI holds to your forge. Each repository needs a source control connection in Jenkins, a webhook or polling schedule that triggers builds, and a checkout credential with the right read scope. Remove or disable the CircleCI webhooks once a project cuts over, so builds do not run twice. Confirm with the forge administrator which account owns the new tokens, because a token tied to a departed employee becomes a single point of failure.

Jenkins credentials and job definitions

Jenkins credentials and job definitions are rebuilt in Jenkins, not exported from CircleCI. Pipelines become a Jenkinsfile committed to each repository, and shared logic moves into a shared library or plugin. Credentials live in the Jenkins credential store under $JENKINS_HOME, which the scaling guide names as the place where configuration, plugins and secrets must be backed up. Consider keeping Jenkins controller configuration in code with the Configuration as Code plugin, and confirm its plugin installation steps with your team before relying on it.

Migration sequence from inventory to decommission

This sequence moves CircleCI pipelines to Jenkins in five controlled phases, so each repository is proven on Jenkins before its builds, secrets and artifacts leave CircleCI. Each phase closes with a written output that the next phase depends on.

Inventory pipelines, contexts, orbs and artifacts
Your platform or DevOps team lists every CircleCI project, its .circleci/config.yml, the workflows and jobs it defines, the orbs and executors it uses, and the contexts that hold its environment variables. The team also records which artifacts and test results matter, because CircleCI keeps build artifacts for a limited period (30 days as both the default and maximum, according to CircleCI's documentation). The step is done when you have one inventory sheet that maps each project to its jobs, orbs, contexts, owners and artifact needs, and each owner has confirmed it.
Pilot one low-risk repository on Jenkins
Pick a repository with a simple build and test path and few secrets. Stand up a Jenkins controller, configure Kubernetes pod agents with the Kubernetes plugin, and write a Jenkinsfile that reproduces the CircleCI workflow as declared stages. Store the controller configuration in code where practical, and back up $JENKINS_HOME because it holds the configuration, plugins and secrets. The step is done when the pilot pipeline builds and tests from the same commit on both systems and the team has documented each plugin it relied on.
Run both systems against the same commits
Keep CircleCI as the release path and let Jenkins build every commit that the pilot repository receives, using the same branch filters and test commands. Compare build results, test counts, artifact outputs and build times for each commit, and log every difference with its cause. Credentials used by the parallel run should be scoped to build and test only, not production deployment. The step is done when the differences list is empty or each remaining difference has an agreed fix, and the owners accept the results in writing.
Cut over each repository with rotated secrets
For each repository, switch the release trigger from CircleCI to Jenkins during a window agreed with its owners. Re-create the required secrets in Jenkins credentials, because CircleCI does not display environment variable values after they are set and a migration cannot export them. Rotate every secret the repository used, since CircleCI's January 4, 2023 incident report told all customers to rotate secrets after an attacker exfiltrated environment variables and keys. The step is done when a production-path build succeeds on Jenkins, the rotated credentials are confirmed in both the deployment target and Jenkins, and the old CircleCI secrets are revoked.
Decommission CircleCI projects after export
Once a repository has run on Jenkins through its cutover and its owners have signed off, export the artifacts, test reports and build history you need through CircleCI's API before the retention window closes. Archive these exports in your own storage, then disable the CircleCI project and remove its contexts and environment variables. The step is done when the export archive is verified as readable, the CircleCI project is disabled, and the inventory sheet records the date and owner of the decommission.

How the migration differs by starting point

Orbs are reusable packages of CircleCI configuration, and how many your pipelines depend on sets the size of the rewrite. A team that uses a handful of well-known orbs for Docker builds, cloud CLIs or notifications has a short list of plugins or shared library functions to replace. A team that pulls in many orbs, some of them custom or maintained inside the company, has to inventory each one, decide whether the behavior is worth keeping, and then write the equivalent steps in a Jenkinsfile or a shared library.

Few orbs: Map each orb to an installed Jenkins plugin or a short shell step, and remove the rest.
Many orbs: Build an inventory of every orb call by repository, including the version pinned in each config.
Custom orbs: Move them into a Jenkins shared library so they can be versioned and tested like other code.
Hidden dependencies: Orbs can change environment variables or caching behavior, so compare each pipeline's output before and after the rewrite.
Plugin count: A larger orb set usually means a larger plugin list to install, back up and upgrade later.

Check the orb inventory first, because it is the best predictor of how much pipeline rewrite and plugin governance your team will take on.

Jenkins is a self-managed server with its own upgrade cycle, so the staff skills needed to run it are the main cost that does not appear in a pipeline rewrite. A team that already runs Jenkins knows how to back up $JENKINS_HOME, manage plugins and read LTS release notes. A team with no Jenkins experience must learn those tasks before it can run production builds. The Jenkins LTS line ships a new baseline every 12 weeks, and plugins that stop being bundled must be installed separately, so someone must own that work every cycle.

Controller operations: Assign an owner for upgrades, backups of $JENKINS_HOME and restore tests.
Plugin governance: Track plugin versions, remove unused plugins and test upgrades in a staging controller first.
Java runtime: Keep the controller on a Java version that Jenkins supports, and plan moves before the listed end-of-support dates.
Configuration as code: Teams new to Jenkins can use the Configuration as Code plugin to keep controller settings in version-controlled YAML.
Training: Budget time for Jenkinsfile syntax, shared libraries and agent troubleshooting for every engineer who writes pipelines.

Ask any implementation partner to name who will run upgrades after go-live, because that role is the one most often left unassigned.

What drives the cost and duration of the move

This table lists the factors that set the effort of moving CircleCI pipelines to Jenkins and the cost components behind each one. Read each row as a question to answer during scoping, because the drivers compound: a large config with many orbs and contexts takes longer than the same number of simple pipelines.

Driver	Why it changes effort or cost	How to keep it down
Pipeline count and complexity	Each config.yml with workflows, approval gates, matrix jobs and conditional branches becomes a Jenkinsfile that must be written, tested and reviewed. Complex dynamic configuration takes the most rework.	Inventory every pipeline first, group near-identical ones, and migrate shared patterns once as a shared library.
Number and depth of orbs	Each orb is a reusable package that must be replaced by a Jenkins plugin, a shared library function or a plain shell step. Deeply nested orbs with their own parameters take more design work.	List orbs by use count, replace the most-used ones first, and drop orbs that duplicate built-in steps.
Contexts and secrets	CircleCI does not display environment variable values after they are set, so each value must be re-entered in Jenkins credentials from the source system and each deployment secret rotated.	Map contexts to Jenkins folders and credential scopes, and confirm which values the owners still hold before work starts.
Artifact volume and retention	CircleCI keeps artifacts for 30 days by default and at most 30 days, so history must be exported before it expires. Large binaries and test reports raise transfer and storage work.	Export only artifacts that audits or releases need, and set retention on the Jenkins controller and archive storage in advance.
Kubernetes readiness	Pod agents from the Jenkins Kubernetes plugin need a working cluster, image registry, service accounts and network paths. Teams without this platform must build it before pipelines move.	Confirm cluster capacity, registry access and agent image ownership early, and pilot one pipeline on a pod agent.
Plugin count	Each plugin needs a version choice, a security review and a test run. Jenkins LTS 2.580.1 stopped bundling several plugins, so some must be installed explicitly through the plugin manager.	Install only plugins that the migrated pipelines need, pin versions, and record each plugin's purpose.
Parallel-run length	Running CircleCI and Jenkins side by side doubles build compute and staff review time until teams trust the new pipelines. The run must finish before credits or the CircleCI contract end.	Set exit criteria per pipeline, such as matching artifacts and passing deploy tests, and agree the run length in writing.
Build servers and agents	Recurring compute for the controller and agents depends on build concurrency and peak load. The Jenkins scaling guide recommends dedicated agents so the controller handles only HTTP requests and build management.	Ask the implementer to size agents from your measured concurrency, and use autoscaling on Kubernetes where possible.
Storage, upgrades, support and staff time	Storage recurs with retention. Upgrades recur on the Jenkins LTS cadence, and each upgrade includes plugin testing. Staff time for pipeline ownership is usually the largest ongoing component.	Ask for a quote that separates one-time migration work from recurring operations, and confirm who performs upgrades and backups.

What usually goes wrong and how to prevent it

Most failed CircleCI to Jenkins moves fail in the same few places: secrets, build history, plugin maintenance, controller capacity and cutover timing. Each card below names one of these risks, why it matters for this migration, and the check that prevents it.

Secrets must be re-created, not copied

CircleCI does not display environment variable values after they are set, so the values cannot be read out and imported into Jenkins credentials. Treat every context and project variable as a secret to rotate. Build an inventory of each variable, confirm its owner, issue a new value at the source system, and store it in Jenkins credentials or an external secrets store. Because CircleCI reported in January 2023 that an attacker exfiltrated customer environment variables, tokens and keys, rotating old values is part of the migration, not an optional follow-up.

Build artifacts expire before the move

CircleCI sets 30 days as both the default and the maximum retention for build artifacts. Any release bundle, test report or coverage file older than that window will be gone, so the history a regulator or auditor may ask for disappears first. Before cutover, script the artifact download through the CircleCI API for the builds you must keep, store them in a repository your team controls, and record the checksum. Confirm which artifacts your audit or release process actually depends on.

Plugin drift during LTS upgrades

Jenkins plugins are not pinned by default, and each LTS baseline can change which plugins ship with the controller. The 2.580.1 LTS stopped bundling several plugins, including the SSH server and JUnit plugins, so a pipeline that worked on the prior baseline can fail after an upgrade. Pin plugin versions in your configuration, install every plugin your Jenkinsfiles call through the plugin manager, and test each upgrade on a staging controller before production. Keep a written list of plugins that replace CircleCI orbs so you know which ones to review.

One controller becoming the bottleneck

Teams often move every CircleCI project onto a single Jenkins controller, then find it slow to respond and difficult to recover. The scaling guide recommends dedicated build agents so the controller only handles HTTP requests and manages the build environment, and it describes adding controllers for new teams or projects. Size agents as Kubernetes pod templates, keep builds off the controller, and plan a backup controller behind a proxy. Document where $JENKINS_HOME lives and back it up, because all configuration, plugins and secrets sit there.

Converting pipelines without a parallel run

Cutting over every project on one date removes the fallback when a Jenkinsfile misses a CircleCI orb behavior, an environment variable or a cache step. Run both systems on the same commits for a defined period, compare build outcomes, test results and artifact checksums, and move projects in groups. Keep CircleCI active until each group matches. Confirm the CircleCI plan and credit position with your account team so the parallel run does not end when credits run out.

Questions teams ask before moving from CircleCI to Jenkins

What does a move from CircleCI to Jenkins cost, and what drives it?

The cost is mostly people time plus the infrastructure you run, not a licence fee, because Jenkins is MIT-licensed. Your CircleCI bill stops at cutover, while Jenkins adds recurring costs: build agents, controller hosting, storage, plugin maintenance and LTS upgrades. The biggest drivers are the number of pipelines, how many use orbs or custom executors, how many secrets must be re-created, and how much parallel running you need. Ask any provider for a quote that separates one-time migration work from recurring operations, and ask which of your current CircleCI features will need plugins or shared libraries. Your own CircleCI invoice and credit usage are the baseline for comparison.

How long does a CircleCI to Jenkins migration take?

Duration depends on pipeline count and complexity, so no fixed timeline applies across teams. Plan the work in phases: inventory existing workflows and orbs, build a Jenkins controller and agents, convert a pilot pipeline, then run old and new pipelines in parallel until results match. Parallel running is the step most teams underestimate because it needs both systems funded and monitored. Ask for the timeline in a written scope, with named deliverables for each phase and a clear cutover criterion.

What must our team provide before a migration starts?

Before work starts, your team needs to supply access and decisions that only you can make:

A list of CircleCI projects, workflows, contexts and orbs in use
Access to the Git forge that hosts the repositories and to the target Kubernetes or VM capacity for agents
Named owners for deployment credentials, approvals and on-call response
Decisions on retention, artifact storage and which environments can be changed during the parallel run

Ask the provider to confirm which of these they need in writing so the scope and quote reflect your actual environment.

Can our own engineers do the migration without an outside partner?

Yes, if your team already runs Jenkins or Kubernetes and has time to own the project. Converting a Jenkinsfile is well documented, but the work also includes plugin selection, controller and agent hardening, backups of $JENKINS_HOME, and LTS upgrades that arrive on a regular cycle. Teams that build in-house usually handle the pipeline conversion and assign a single owner for upgrades and backups. An implementation partner can take on the platform build, testing or ongoing support under a fixed scope if your team does not have that capacity. Compare both options against the same written scope.

How do we move CircleCI secrets to Jenkins safely?

You cannot export CircleCI environment variable values, because CircleCI does not display them after they are set, so each secret must be re-entered in Jenkins credentials from its source system. Treat this as a rotation event rather than a copy. CircleCI's January 4, 2023 incident report told all customers to rotate secrets after an attacker exfiltrated environment variables, tokens and keys, so rotating during the move is a sound baseline. Record which credential each pipeline uses, store values in a managed secrets backend where possible, and restrict who can read Jenkins credentials. Confirm with your security team which rotation steps and approvals apply to production keys.

What happens to our CircleCI build artifacts and history?

CircleCI keeps build artifacts for 30 days by default and at most 30 days, so anything you need for audit or rollback must be downloaded through the API before that window closes. Jenkins does not inherit this history. Plan where artifacts go next, such as an artifact repository or object storage you control, and decide how long build logs and test reports must be kept. Export and retention rules should be written into the scope, with an owner for the archive. Confirm retention requirements with your compliance lead before cutover.

Can Jenkins work with our existing Git forge?

Yes, Jenkins can be connected to the Git server you already use, so repositories do not have to move at the same time as pipelines. Jenkins reads its pipeline from a Jenkinsfile committed to the project's source control repository, and it uses plugins to connect to the forge and report build status. Confirm the exact plugin and webhook setup for your forge version and whether your forge needs network access to the Jenkins controller. Keeping the forge unchanged reduces the scope of the migration and simplifies the parallel run.

How DeployOpen scopes and runs a CircleCI to Jenkins migration

DeployOpen plans, implements, customizes, integrates, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure. For a CircleCI to Jenkins move, we start with a written inventory of your pipelines, secrets and artifacts, then build the Jenkins controller, agents and Jenkinsfiles in your environment, with a parallel run before CircleCI is switched off.

How we scope

Inventory every CircleCI config.yml, workflow, orb and context across the repositories in scope
Record which pipelines need Docker executors, machine runners or resource classes and map them to Jenkins pod agents
Agree the written scope, deliverables and timeline with you before any migration work starts

How we build

Convert workflows into Jenkinsfile stages and steps, committed to each project's source control repository
Replace orbs with vetted Jenkins plugins or shared libraries, and move CircleCI contexts into Jenkins credentials
Run the old and new pipelines side by side and compare build results, test reports and artifacts before cutover

How we hand over

Document the controller, agent, backup and plugin setup, including the contents of $JENKINS_HOME that must be backed up
Train your engineers to write and review Jenkinsfiles and to run plugin and LTS upgrades
Deliver a rotation record for the secrets that CircleCI held, so your team can confirm every credential was reissued

How we support

Confirm with you which upgrade, backup and monitoring tasks stay with your team and which go to a retainer
Offer ongoing support, upgrades and continuous testing as a retainer after handover
Ask for a quote built from the written scope, since DeployOpen does not publish a price list

Migrate from CircleCI to Jenkins