Jenkins → CircleCI
Move Jenkins freestyle jobs and Jenkinsfiles onto CircleCI. Copy Execute Shell steps into .circleci/config.yml first. Then replace plugins, agents, credentials, and approvals with CircleCI jobs, orbs, contexts, and self-hosted runners.
Should you make this move?
Both platforms have a case. Compare what you gain with what you give up before scheduling the cutover.
Jenkins
- Extreme flexibility, self-hosting, and a vast plugin ecosystem handle unusual build systems
- Repository-centered workflows keep code, review, and automation close together
- Plugin maintenance, security, scaling, and interface debt create significant operational work
- Advanced governance and automation can become configuration-heavy
CircleCI
- YAML pipelines, orbs, contexts, and SSH debugging make hosted CI approachable for growing engineering teams
- Repository-centered workflows keep code, review, and automation close together
- Usage credits, contexts, and orb-specific behavior create lock-in that does not map one-to-one onto other runners
- Advanced governance and automation can become configuration-heavy
CircleCI: YAML pipelines, orbs, contexts, and SSH debugging make hosted CI approachable for growing engineering teams. This removes a major source-side concern: Plugin maintenance, security, scaling, and interface debt create significant operational work.
What you lose: Extreme flexibility, self-hosting, and a vast plugin ecosystem handle unusual build systems. What you inherit: Usage credits, contexts, and orb-specific behavior create lock-in that does not map one-to-one onto other runners.
Jump to a section
Know the shape of the move.
This timeline assumes
- Up to 60 Jenkins jobs or Jenkinsfiles, 20 agents, and 40 credential entries that feed production deploys.
- You control the Jenkins controller, agent machines, CircleCI org, contexts, and the Git host's required checks.
- CircleCI's guide treats this as a different product, not a plugin-for-plugin copy.
- A pilot covers one Execute Shell job, one Pipeline job with agents, and one deploy that uses credentials.
- Jenkins stays up until CircleCI has owned one release path.
What survives the move.
“Partial” and “manual” are not footnotes. They are work that must be scheduled and verified.
| Item | Outcome | Impact | What happens | Mitigation |
|---|---|---|---|---|
| Execute Shell steps | partial | critical | CircleCI says you can paste those commands into run steps in .circleci/config.yml after a first green Getting Started build. | Create the config, paste the commands, and install anything that is not on the CircleCI image. |
| Plugin-driven build steps | manual | critical | CircleCI says anything beyond Execute Shell needs a manual port against its configuration keys. | Inventory every plugin step and replace it with a run step, an orb, or an explicit skip. |
| Agents and executors | manual | critical | Jenkins labels and node blocks become CircleCI executors, resource classes, or self-hosted runners. Hardware you owned does not appear automatically. | Map each label to a CircleCI executor or a self-hosted runner and run the same compile on it. |
| Credentials and secrets | manual | critical | Jenkins Credentials do not export as CircleCI contexts. Values have to be re-entered and rotated. | List every credential ID and consumer. Recreate them as project env vars or contexts. |
| Jenkinsfile stages and when conditions | partial | high | Declarative stages become CircleCI jobs and workflows. when, input, and options need a new expression. | Translate each stage to a job, each when to a filter or a logic step, and each input to an approval job. |
| Shared libraries | manual | high | Global Pipeline Libraries are Groovy. CircleCI has no Groovy shared-library runtime. | Extract the shell they wrap and put it in orbs, commands, or repo scripts. |
| Build history, test trends, and fingerprints | lost | medium | Jenkins job history stays on the controller. | Export reports you still need for audit and accept a new CircleCI baseline. |
| Plugin-managed artifacts and publishers | partial | high | Archive the Artifacts, JUnit, and HTML publisher plugins become store_artifacts, store_test_results, or an external bucket. | Write artifacts to a known path and configure CircleCI store steps or an upload command. |
| Triggers and webhooks | manual | high | Jenkins Git hooks, cron triggers, and downstream jobs become CircleCI triggers, scheduled workflows, and workflow requires. | Recreate each trigger and disable the Jenkins one before cutover. |
| Controller and agent operations | lost | high | You stop patching Jenkins core, plugins, and executor machines. That ops work does not move. It disappears if the move works. | Keep the controller read-only through rollback and snapshot it before you power anything down. |
| Matrix and parallelism | partial | medium | Jenkins matrix axes and parallel stages become CircleCI matrix jobs or parallelism plus a split. | Rehearse the same axis set and compare shard counts. |
| Folder and RBAC structure | manual | medium | Jenkins folders and matrix auth become CircleCI projects, groups, and contexts. | Rebuild access from a written permission sheet, not from the old folder tree. |
Where each thing goes.
| Source | Destination | Method | Notes |
|---|---|---|---|
| Execute Shell command | run step | transform | Install missing packages on the image. |
| Jenkinsfile stage | CircleCI job | transform | Keep stage order in a workflow. |
| agent / node label | executor or runner | manual | Confirm OS and tools. |
| Jenkins credential ID | context or project env var | manual | Rotate the value. |
| when condition | workflow filter or logic step | transform | Test matching and excluded branches. |
| input step | approval job | manual | Name the approver group. |
| shared library | orb, command, or repo script | manual | No Groovy runtime. |
| JUnit publisher | store_test_results | transform | Keep the XML path stable. |
| Build trigger | CircleCI trigger or schedule | manual | Disable the Jenkins trigger first. |
Make the move recoverable.
Create the source-of-truth backup
Preserve Jenkins job definitions, credentials inventory, and agent images before you change merge gates.
- Inventory jobs, Jenkinsfiles, plugins, agents, credentials, triggers, and downstream deploys.
- Export job XML or snapshot the Jenkins home you still treat as recoverable.
- Copy every Jenkinsfile from the production commit.
- List credential IDs and consumers without writing secret values into the ticket.
- Record current required checks on the Git host.
Proof to capture: A dated manifest lists every job, plugin step, credential consumer, and required check.
First green CircleCI build
Follow CircleCI's published first step before you paste production shell.
- Connect the repo and get a green hello-world build.
- Paste Execute Shell commands into run steps.
- Install packages that the image does not ship.
Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.
Plugin and library rewrite
Remove Groovy and plugin steps that have no CircleCI equivalent.
- List every plugin step and shared-library call.
- Replace each with a command, orb, or explicit skip.
- Test the deploy path with rotated credentials.
Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.
The things most likely to hurt.
These are operating limits. Treat every “Stop if” condition as a blocked migration, not a suggestion.
A plugin step is silently skipped
The CircleCI job is green but a Jenkins publisher, scanner, or gate never ran.
- Consequence
- Broken artifacts or skipped security checks ship.
- Mitigation
- Tick every plugin step on the inventory before you call the pilot done.
Stop if: Any production plugin step lacks a CircleCI replacement or a signed skip.
Jenkins and CircleCI both deploy
A Git webhook still hits Jenkins after CircleCI is required.
- Consequence
- Two releases, or a rollback to the wrong build.
- Mitigation
- Disable Jenkins triggers and downstream jobs before you open CircleCI deploys.
Stop if: The same commit deploys from both systems.
Self-hosted Jenkins agents disappear too early
Someone powers down agents before rollback is closed.
- Consequence
- You cannot return to Jenkins inside the window.
- Mitigation
- Keep the controller and a restore snapshot until the observation period ends.
Stop if: Jenkins cannot run the production job from backup.
Do the work in this order.
- Days 1–5 · inventory
Inventory and decisions
10–18 hours active3–5 days elapsedPlugin and credential owners waiting- Inventory jobs, plugins, agents, and credentials.
- Mark Execute Shell jobs versus plugin-heavy jobs.
Depends on: Jenkins admin and CircleCI admin access
Stop / go checkpointPilot?
Go when: Every production job has an owner and a CircleCI disposition.
Stop when: A deploy credential or plugin step is unknown.
- Days 4–8 · backup
Export and snapshot
6–12 hours active2–4 days elapsedController snapshot waiting- Export Jenkinsfiles and job config.
- Snapshot Jenkins home and list credential IDs.
Depends on: Approved inventory
Stop / go checkpointTransform?
Go when: The snapshot restores a sample job.
Stop when: Job XML or Jenkinsfiles are incomplete.
- Days 7–20 · pilot
Translate and pilot
24–60 hours active8–14 days elapsedFirst CircleCI runs waiting- Get a green Getting Started build.
- Port one freestyle and one Pipeline job.
- Rebuild the deploy credential path.
Depends on: Verified backup
Stop / go checkpointScale?
Go when: Pilot jobs match Jenkins on the same SHA.
Stop when: A plugin step has no replacement.
- Days 18–28 · cutover
Switch triggers
12–28 hours active4–8 days elapsedGit host required checks waiting- Port remaining jobs.
- Move required checks to CircleCI.
- Disable Jenkins webhooks and downstream deploys.
Depends on: Passed pilot
Stop / go checkpointOpen production?
Go when: CircleCI is the only deploy trigger.
Stop when: Jenkins still runs a production job.
- Days 26–35 · observe
Observe and close
8–12 hours active6–9 days elapsedRelease cycle waiting- Watch scheduled and release jobs.
- Keep Jenkins powered for rollback.
Depends on: Verified cutover
Stop / go checkpointClose rollback?
Go when: No trigger fires through one release.
Stop when: A required Jenkins path is missing on CircleCI.
Cut over with a way back.
Cutover
Make CircleCI the only required CI and the only deploy trigger.
- Freeze Jenkins job edits that affect production.
- Merge the approved .circleci/config.yml on the compared commit.
- Point the Git host required check at CircleCI.
- Disable Jenkins webhooks, cron triggers, and downstream deploys.
- Run one production deploy from CircleCI and keep Jenkins recoverable.
Proof to capture: CircleCI owns checks and deploys. Jenkins cannot ship. Pilot results still match.
Rollback
Return checks and deploys to Jenkins without a double release.
- Stop CircleCI deploy jobs and schedules.
- Restore the Jenkins required check.
- Re-enable Jenkins webhooks and downstream jobs.
- Disable the CircleCI deploy workflow.
- Run one Jenkins release path.
Proof to capture: Jenkins is the merge gate again and only one deploy ran.
- Required CircleCI check missing
- Deploy ran twice
- Plugin step skipped
- Credential failure
- Jenkins restore untested
Prove the migration worked.
Every blocking check must pass. Capture the evidence before cleanup begins.
| Pass | ID | Check | Method | Expected result | Evidence |
|---|---|---|---|---|---|
V-01Blocking | Job coverage | Compare the Jenkins job list to CircleCI workflows. | Every production job is ported or signed as retired. | Job ledger. | |
V-02Blocking | Same-commit parity | Run Jenkins and CircleCI on one frozen SHA for the pilot jobs. | Tests and artifacts match. | Job logs. | |
V-03Blocking | Step replacement | Tick every plugin step against a CircleCI command or skip. | No unsigned skips. | Plugin worksheet. | |
V-04Blocking | Credential recreation | Exercise each rotated context on a non-production job, then the deploy job. | Least privilege and a successful auth. | Context audit. | |
V-05Blocking | Executors | Run each mapped label on its CircleCI executor or runner. | OS, tools, and architecture match the Jenkins agent. | Executor log. | |
V-06Blocking | Required checks | Attempt a merge with CircleCI failing. | The branch stays closed. | Branch-protection screenshot. | |
V-07Blocking | Single deploy | Rehearse production with Jenkins triggers disabled. | One CircleCI deploy. | Deploy log. | |
V-08Blocking | Jenkins restore | Boot the snapshot or re-enable the production job. | Jenkins can run the job again. | Restore note. |
Remove the scaffolding safely.
Safe after: One full release cycle and seven stable days with Jenkins still restorable.
- Archive Jenkins job XML, Jenkinsfiles, and the plugin worksheet.
- Revoke Jenkins credentials that CircleCI now holds.
- Leave the controller snapshot until legal and billing review finish.
- Power down agents only after rollback closes.
- Update runbooks with CircleCI workflow names.
- Schedule the next context and orb pin review.
When the plan met reality.
First-hand accounts are preferred. Vendor case studies are labeled, and every note below is an editorial paraphrase—follow the link for the full context.
Antony Fuentes recounts Instawork moving iOS and Android end-to-end tests from on-premises Jenkins onto CircleCI, where developers already built and deployed. Jenkins ran out of memory, forced old report deletion, drifted Ruby versions, and duplicated every build-process change. The CircleCI move needed Python and pyenv setup, timezone config, environment variables, test data, and custom Allure reporting. Python version mismatches and session-grouping gaps showed up during the rewrite.
- Inventory QA-only Jenkins jobs separately from the developer pipeline, then give each one an owner on CircleCI.
- Rehearse mobile E2E on CircleCI with the same Ruby, Python, and report toolchain before you retire the Jenkins agents.
- The driver was one pipeline, not a feature-for-feature Jenkins clone.
- On-prem memory, OS drift, and duplicated build steps were the daily cost of keeping Jenkins for QA only.
KAYAC's SRE team moved Lobi CI off a three-box Jenkins install on Amazon Linux 1 after the AMI end-of-life date approached. Perl, Go, and Node jobs moved onto CircleCI images, with a custom image for the older Perl app. They ran X-large containers at 20-way parallelism. Wall-clock CI fell from about 10 minutes to about 4 or 5 minutes, and queue wait dropped near zero. Visible CI spend roughly doubled from tens of thousands of yen to the low hundreds of thousands, which they judged cheaper than Jenkins maintenance.
- Treat AMI or OS end-of-life as a reason to leave self-hosted Jenkins, not a reason to rebuild another Jenkins farm.
- Raise CircleCI parallelism until setup time eats the gain, then stop. Lobi aimed at a five-minute target.
- Application code did not change. The work was images, parallelism, and giving up Jenkins plugin care.
- Higher invoice cost can still be the cheaper move when you stop staffing Jenkins emergencies.
Verify against the primary material.
Platform behavior changes. Check these sources and the review dates above before executing a production migration.
- CircleCI: migrate from JenkinsAccessed 2026-10-29
- Jenkins: pipeline syntaxAccessed 2026-10-29
- CircleCI: configuration referenceAccessed 2026-10-29