Migrate from Bitbucket Pipelines to Jenkins: what the move involves
If your renewal, a runner fee change or a control requirement is pushing you off Bitbucket Pipelines, plan for a rebuild of pipelines and secrets on a self-hosted Jenkins controller and agents, not a copy of files. Your bitbucket-pipelines.yml files do not run on Jenkins, so each pipeline has to be rewritten as a Jenkinsfile, and each secured variable has to be re-entered in Jenkins credentials, because Bitbucket secured variables can only be replaced or deleted, never exported.
Platform engineers who already know Bitbucket usually do the pipeline translation, working with security owners who decide where credentials live, who may approve deployments and which agents are trusted to run which builds. Jenkins is distributed under the MIT License, and its homepage describes more than 2,300 community plugins, so most integrations you need likely exist. Confirm each plugin you depend on against the current plugin index and your own Jenkins version before you commit to a design.
Effort concentrates in three places: converting pipe-based steps into plugins or shared library functions, rebuilding deployment approvals and environment-scoped credentials, and wiring Bitbucket webhooks and build status reporting so pull requests show Jenkins results. Scope the work by counting repositories, pipes and deployment targets, and ask any integrator for a written estimate that lists those items separately. Expect the largest risk in deployment credentials, since a misconfigured controller can expose every project it builds. Your controller also holds all configuration, plugins and secrets in $JENKINS_HOME, so back it up from day one, and plan a parallel run where both systems build the same branch before you switch off Bitbucket Pipelines.
Which Bitbucket Pipelines capabilities map to Jenkins, and where the gaps are
This table maps each Bitbucket Pipelines capability to its Jenkins equivalent and marks it clean, needs rework or gap. Read the status first, then the notes, because rework rows need engineering time even when a Jenkins feature exists. Confirm plugin behavior against the Bitbucket plugin version in your own environment before you commit to a cutover plan.
| Bitbucket Pipelines capability | Jenkins equivalent | Status and what to plan for |
|---|---|---|
| Steps in bitbucket-pipelines.yml | Stages and steps in a Declarative Jenkinsfile committed to the repository | Clean. Each step becomes a stage with explicit shell or tool commands, and the Jenkinsfile lives in the same repo as the code. |
| Parallel steps | Parallel blocks inside a stage | Clean for most pipelines. Confirm how parallel branches share workspaces and agents, since Bitbucket runs each step in its own container. |
| Pipes (for example, deploy and notification pipes) | Jenkins plugins, shell calls to vendor CLIs, or shared libraries | Needs rework. Each pipe must be mapped to a plugin or a reusable shared library function, and its inputs and secrets rewired by hand. |
| Custom pipes and shared pipeline logic | Jenkins shared libraries in a separate Git repository | Needs rework. Logic that was copied across repos is typically consolidated into one shared library with versioned releases. |
| Deployment environments and manual approvals | Credentials scoped to folders or pipelines, and input steps for approvals | Needs rework. Approver lists, environment-specific variables and deployment history do not transfer automatically and must be rebuilt and tested. |
| Secured repository and deployment variables | Jenkins credentials store, populated by an administrator | Gap for export. Secured Bitbucket variables cannot be read back, so values must be re-entered from the owning system and rotated. |
| Caches and artifacts | Jenkins archiveArtifacts and stash/unstash, with workspace or cache plugins | Needs rework. Retention is set by Jenkins build discarders on your controller, not by a fixed Bitbucket window, so set policies deliberately. |
| Bitbucket webhooks and triggers | Bitbucket Branch Source or webhook-triggered multibranch pipeline jobs | Needs rework. Confirm webhook secrets, branch and pull request discovery, and which events trigger builds under your plugin version. |
| Build status reporting to pull requests | Bitbucket build status updates sent by Jenkins plugins | Confirm. Status checks and required-check rules in Bitbucket must be re-pointed to the Jenkins job names, and plugin behavior must be verified. |
What exports, what must be re-entered and what to rebuild
Moving from Bitbucket Pipelines to Jenkins splits into three groups: what travels with the repository, what must be supplied again from its source system, and what has to be rebuilt on the Jenkins side. Work through each group before the first pipeline runs on Jenkins, so nothing is lost when the old pipelines stop.
Pipeline definitions travel with repositories
Each repository's bitbucket-pipelines.yml moves with its code, so it is the first inventory item. Translate each step, parallel block and pipe into a Jenkinsfile stage committed to the same repository. Check the branch and pull request triggers, custom pipelines and any step that depends on a Bitbucket-specific image or pipe, because those need an explicit replacement in Jenkins.
Secured variables must be re-supplied
Bitbucket secured variables can only be replaced or deleted, so their values cannot be copied into Jenkins. Build a register of every secured variable, its consuming repository and the system it came from, such as a cloud account, registry or deployment target. Issue new credentials at the source and store them in Jenkins credentials, then confirm each job reads them under the expected ID.
Artifacts expire after 14 days
Bitbucket Pipelines keeps artifacts for at most 14 days, so older build outputs disappear regardless of the migration. Export the artifacts and build logs you need for audit, rollback or release records before the cutover, and store them in a location you control. Confirm with your compliance owner how long these records must be retained, since that period sets how far back the export must reach.
Jenkins configuration lives in JENKINS_HOME
On the Jenkins controller, all configuration, plugins and secrets sit in $JENKINS_HOME, so that directory is the primary backup target. Plugin versions and global settings are not in your repositories, so record them. Configuration as Code can express the controller setup in YAML through jenkins.yaml, but it does not install plugins, so pin the plugin list separately in an image or Helm values.
Build agents and the webhook path
Bitbucket runners and their build slots have no direct equivalent in Jenkins, so define agent labels, container images and the Kubernetes or SSH agent configuration that replaces them. Recreate the Bitbucket webhooks that trigger Jenkins and the build status reporting that developers rely on for pull request checks. Test both on a non-production repository before switching any production trigger.
Migration sequence from inventory to decommission
This sequence moves Bitbucket Pipelines builds to Jenkins in a controlled order, so each stage produces evidence that the next stage depends on. It ends with decommissioning, only after both systems have built the same commits and the cutover is signed off.
Inventory pipelines, variables and artifacts
Start by listing every repository with a bitbucket-pipelines.yml file, every branch and deployment environment it targets, every pipe and custom image it calls, and every secured variable it reads. Record which artifacts the builds keep and which downstream jobs consume them. Export build history and artifacts that you need to retain, because Bitbucket Pipelines keeps artifacts for at most 14 days. The output is a written inventory with one row per pipeline, and the owning team confirms each row before work begins.
Map steps, pipes and secrets to Jenkins
Translate each pipeline into a draft Jenkinsfile, mapping steps to stages and parallel steps to parallel blocks. Replace each pipe with a plugin, a shared library function or a plain shell command, and record which choice you made and why. Plan where each secured variable goes: Jenkins credentials scoped to folders or jobs, with deployment approvals defined as separate gates. Secured Bitbucket variables cannot be read back, so each value must be re-entered from its system of record. The output is a mapping sheet that security and release owners approve.
Build a pilot pipeline on Jenkins agents
Choose one low-risk repository and stand up a Jenkins controller with dedicated build agents, following the scaling guidance that keeps the controller for coordination and runs builds on agents. Store the Jenkinsfile in the repository, store configuration as code where your team can review it, and back up $JENKINS_HOME from the first day. Connect Bitbucket to Jenkins, then run the pilot on feature branches. The pilot passes when builds, tests, artifact archiving and the agreed deployment to a non-production environment all complete repeatedly without manual edits.
Run both systems against the same commits
Keep Bitbucket Pipelines active while Jenkins builds the same commits for the pilot and then for the remaining repositories in waves. Compare test results, build outputs, image digests or package checksums, and deployment results for each commit. Log every difference and classify it as a pipeline defect, an environment difference or an expected change. Parallel running ends when the differences are resolved and the owners accept the comparison report. The output is that signed comparison report, which becomes the evidence for cutover.
Cut over webhooks and status checks
Move the production triggers for each repository from Bitbucket Pipelines to Jenkins, including webhooks, branch rules and the build status reporting that protects merges. Confirm that Jenkins posts the status results Bitbucket expects, and that required checks block merges as they did before. Update deployment credentials and approval gates so only the new path can deploy. Remove or disable the Bitbucket Pipelines trigger for each repository after its Jenkins trigger is verified. The output is a cutover checklist per repository, signed by the service owner and the release approver.
Decommission Bitbucket Pipelines runners and secrets
After the cutover window closes without rollbacks, disable Bitbucket Pipelines for each migrated repository and remove its variables, including secured values that no longer serve a purpose. Deregister any self-hosted runners and decommission their machines, checking that no other repository still depends on them. Rotate any credential that was shared between the old and new systems, and record the removal in your change log. Confirm the archived build history and artifacts remain available to auditors under your retention policy. The output is a decommission record that lists every repository, runner and credential retired.
How the migration changes by team size and starting point
A single team with a few repositories usually has the smallest migration. One Jenkins controller can hold the jobs, and the team can translate each Bitbucket Pipelines configuration into a Jenkinsfile committed next to the code. The Jenkins scaling guide recommends dedicated build agents so the controller handles HTTP requests and manages the build environment, so even a small team should plan for at least one agent separate from the controller instead of building on the controller itself.
- Controller and agents: Run one controller and add agents for the build images your pipelines need, so the controller stays free of build workloads.
- Backup scope: Everything that defines the instance, including configuration, plugins and secrets, lives in
$JENKINS_HOMEon the controller, so back up that directory from the start. - Jenkinsfile conversion: Move each
bitbucket-pipelines.ymlstep into a stage, and keep the Jenkinsfile in the repository so pipeline changes are reviewed with code. - Plugin footprint: Install only the plugins the pipelines use, since each one adds upgrade work.
- Bitbucket integration: Confirm the Bitbucket plugin and webhook setup with a test branch before cutting over.
Before starting, confirm with your team how many repositories and pipelines are in scope and who will maintain the controller after the migration.
A multi-team organization usually needs to decide how to share one Jenkins installation. The scaling guide describes growing horizontally by adding controllers for new teams or projects, which isolates plugin versions, credentials and job namespaces between groups. Each controller then needs its own backup and upgrade routine, so the number of controllers should follow a clear ownership model rather than being added ad hoc.
- Controller per team or project: Separate controllers keep one team's plugin upgrades from blocking another team's releases.
- Shared agent pool: Dedicated agents can serve several controllers, but confirm how credentials and labels are scoped so one team cannot use another team's agents.
- Shared library ownership: Decide who maintains common pipeline code, since changes to a shared library affect every team that loads it.
- Upgrade cadence: Plan upgrades around the LTS release line so every controller moves to the same supported baseline on a predictable schedule.
- Support model: Agree in writing who handles controller incidents and who approves new plugins.
Ask your platform team how many controllers the organization expects to run and who owns each one before the first pipeline is migrated.
A regulated environment needs more than a working pipeline. The scaling guide describes a primary and backup controller arrangement in which a proxy such as HAProxy or F5 routes traffic to the backup if the primary fails. That design supports availability, but the failover, the backup restore and the change records must also be documented and tested, since auditors will ask how the pipeline can be recovered and who approved each change.
- Primary and backup controller: Test failover with a proxy such as HAProxy or F5 and record the results as evidence.
- Change control: Route Jenkinsfile changes through reviewed merge requests and keep the approval trail in Bitbucket.
- Secrets handling: Bitbucket secured variables cannot be read back, so plan how credentials are re-entered into Jenkins credentials and who holds them.
- Configuration as code: Store controller settings in YAML using the Configuration as Code plugin, but install plugins through Docker images or the Helm chart, since that plugin does not install them.
- Upgrade evidence: Record the LTS version in use and the plugins installed on each controller.
Before the migration, confirm with your assessor which control evidence they expect for pipeline changes, backups and access, since DeployOpen prepares that evidence but independent auditors and certification bodies issue any conclusions.
What drives migration cost and duration, and how to keep each one down
This table lists the factors that raise the effort of moving Bitbucket Pipelines workloads to Jenkins, why each one adds cost, and how to reduce it. Read it as a checklist to scope a quote, since most drivers are set by your own pipeline inventory and availability needs rather than by Jenkins itself.
| Driver | Why it raises cost or effort | How to keep it down |
|---|---|---|
| Number of pipelines and repositories | Each bitbucket-pipelines.yml must be translated, tested and wired to a Jenkins job or multibranch project, so effort grows with repository count. | Inventory every pipeline first, group repositories with similar build patterns, and convert a shared template once. |
| Secured variables and credentials | Bitbucket secured variables cannot be read back, so each value must be re-supplied by its owner and stored in Jenkins credentials. | Rotate secrets during the move, record owners in advance, and store them in the Jenkins credentials store or an external secrets manager. |
| Custom pipes | Pipes are reusable Bitbucket units, and each one used in a pipeline needs an equivalent plugin, shared library step or script. | Count distinct pipes across repositories, then replace each pipe once as a shared library function rather than per pipeline. |
| Deployment environments and approvals | Bitbucket deployment environments and manual steps must be rebuilt as Jenkins input steps, roles and promotion rules, which need sign-off from owners. | Document current approvers and environment rules before work starts, and confirm which approvals must be kept for audit. |
| Build agents (Kubernetes or VM) | Jenkins needs agents that match the build images, tools and network access of the old runners, and each agent platform adds setup and tuning. | Reuse container images from Bitbucket build steps, choose one agent type first, and confirm capacity needs with your platform team. |
| Artifacts and build history | Bitbucket Pipelines keeps artifacts for at most 14 days, so older builds must be exported before the cutover window closes. | Export required artifacts and logs early, agree a retention rule with auditors, and archive only what must be kept. |
| Availability and disaster recovery | A primary and backup controller, proxy routing and tested restores add infrastructure and testing work beyond a single Jenkins instance. | Decide the recovery target with stakeholders, back up $JENKINS_HOME on a schedule, and test restores before the pilot ends. |
| Ongoing upgrades and plugin maintenance | Jenkins LTS releases and plugin updates recur, and LTS 2.580.1 stopped bundling several plugins, so administrators must install them explicitly. | Pin plugin versions, keep the Configuration as Code file under version control, and plan a fixed upgrade cadence with staff. |
| Who pays for what | Implementation labor and any partner scope are one-time, while Jenkins infrastructure, staff time for upgrades and support recur. | Ask each quote for separate line items for build, test, cutover, training and run costs, and confirm what your own staff must supply. |
What running Jenkins after cutover requires
Plan the Jenkins upgrade cadence before the cutover, because the LTS release line sets how often your controller changes. Jenkins picks a new LTS baseline every 12 weeks from a recent weekly release, then ships three LTS releases for that baseline in four-week cycles that contain only backported fixes. Your team should choose a maintenance window that fits those cycles and move between baselines deliberately, not on the day a new one appears. Before you schedule anything, confirm the current LTS version and the Java support status against the Jenkins changelog and the LTS release line documentation, since both move on a fixed schedule and this page should not be your source for the current numbers.
The Java support policy is the second planning input. It lists Java 21 and Java 25 as supported, with planned end-of-support dates published for each, and it names the final LTS release for Java 17. Check which JDK your controller and agent images run, because an upgrade of Jenkins can force a Java upgrade on the same host or container image. Also note that LTS 2.580.1 stopped bundling several plugins, including the bouncycastle API, SSH server and JUnit plugins. Any pipeline that depends on them will fail after the upgrade unless an administrator installs them through the plugin manager first. Add a step to your upgrade runbook that lists every plugin your Jenkinsfiles call, then verifies each one is installed and pinned to a tested version on a staging controller.
What usually goes wrong and how to prevent it
Most failed Bitbucket Pipelines to Jenkins migrations break at the seams: credentials, retained builds, triggers, plugins, the controller and the agents. Each card names one failure, the reason it happens in this move, and the check that prevents it before cutover.
Secrets re-entered incorrectly
Bitbucket secured variables cannot be exported, only replaced or deleted, so every value must be re-created in Jenkins from its source system. Teams often copy an outdated token or mistype a key during cutover. Before the first production run, list every variable each pipeline used, create a matching Jenkins credential with the right type and scope, and confirm each deploy job authenticates in a non-production environment. Record who issued each new secret and when it was rotated.
Artifacts lost after the window
Bitbucket Pipelines keeps artifacts for at most 14 days, so older release packages and test reports may only exist in the old pipeline's history. Before cutover, download the artifacts needed for audit, rollback and customer support into storage you control. In Jenkins, confirm the build retention and artifact archiving settings on each job so that the new retention period is a deliberate choice, not a default you inherited without checking.
Webhooks still aimed at Bitbucket
Repository triggers and webhooks that still reference the old pipeline can fire two builds on one push or none at all. Jenkins needs its own webhook from Bitbucket to the Jenkins endpoint, and build status must come from the new jobs. Remove the Bitbucket Pipelines trigger from each repository, then test with a branch push and a pull request. Confirm that required status checks name the Jenkins job, so merges are gated by the pipeline that actually runs.
Unbundled plugins breaking upgrades
Jenkins LTS 2.580.1 stopped bundling several plugins, including the bouncycastle API, SSH server and JUnit plugins. A controller upgraded without them installed can fail builds that depend on those features. Install the plugins explicitly through the plugin manager, keep a version-controlled list of every plugin and its version, and rehearse each LTS upgrade in staging. Read the stable changelog for every line you cross before moving production.
One controller as a failure point
A single Jenkins controller holds the jobs, plugins and secrets, so its outage stops every pipeline at once. The scaling guide recommends dedicated build agents so the controller mainly handles HTTP requests and manages the build environment. It also describes a primary and backup controller behind a proxy such as HAProxy or F5. Back up $JENKINS_HOME on a schedule, test a restore on separate hardware, and decide in writing whether a standby controller is required.
Agents with broad credentials
A general-purpose build agent that runs jobs from every team can use any credential it is allowed to read, so one compromised pipeline can reach production secrets. Limit each Jenkins credential to the folder or job that needs it, keep deployment credentials off shared agents, and prefer ephemeral agents, for example through the Kubernetes plugin. Require a manual approval step before production deployments, and review which agent labels can run them.
Questions buyers ask before moving Bitbucket Pipelines to Jenkins
What does a move from Bitbucket Pipelines to Jenkins cost?
The cost comes from four components: the Jenkins software itself, which is MIT-licensed and free to use, the build servers and agents you run, the staff time to translate and maintain pipelines, and any support or retainer you buy. Bitbucket Pipelines costs recur through build minutes and, for premium self-hosted runners, a charge of $15 per month per concurrent build slot from runner version 5, according to Atlassian's announcement. Your one-time costs are the migration work and the testing. Your recurring costs are infrastructure, upgrades and on-call time. Costs grow with the number of pipelines, concurrent builds and plugins to maintain. Ask any implementation partner for a fixed-scope quote built from your pipeline count, plugin list and environments, and compare it with your current Bitbucket invoices for the same period.
How long does migrating Bitbucket Pipelines to Jenkins take?
No supplied fact gives a duration for this migration, so the timeline depends on your environment. The main drivers are the number of repositories and bitbucket-pipelines.yml files, how many steps use pipes, how many secured variables must be recreated, and whether you need approval gates or deployment environments. Teams with a small set of standard builds typically finish faster than those with many custom pipes and multi-environment deployments. Ask for a written timeline as part of a fixed-scope proposal, with milestones for pipeline translation, credentials, webhook testing and cutover. Confirm whether the timeline includes parallel running and the rollback plan.
What does the migration need from our own team?
Your team needs to supply access and decisions that only you can make. That means read access to every repository and its bitbucket-pipelines.yml file, a list of the secured variables and deployment targets, owners for each production credential, and someone who can approve changes to Bitbucket webhooks and branch build status checks. Your platform engineers should be ready to provision the Jenkins controller and build agents, and your security team should review how credentials are stored and who can change them. Bitbucket secured variables can only be replaced or deleted, so the values must come from the original systems that issue them. Plan for these inputs before the work starts, since they often set the pace of the project.
Can our own engineers do this migration without outside help?
Yes, a capable platform team can migrate pipelines in-house, especially if the pipelines are simple and the team already runs Jenkins. The work is mostly translating steps into Jenkinsfile stages, moving secrets into Jenkins credentials and building agents. The risks are less about syntax and more about hidden behavior: artifacts that Bitbucket keeps for at most 14 days, caches, deployment approvals and pipes that hide complex logic. Outside help makes sense when you need a fixed scope, independent testing or a secure configuration baseline. DeployOpen plans, implements, hardens, documents and supports self-hosted Jenkins inside your own infrastructure, and most engagements are fixed-scope with the scope agreed in writing before work starts.
How do we run Jenkins and Bitbucket Pipelines in parallel during the cutover?
Run both systems against the same repositories for a defined period, with Bitbucket pipelines still active and Jenkins jobs building in a separate branch or dry-run mode. Bitbucket Pipelines and Jenkins can both respond to the same commits if you configure them to report to different status contexts, so reviewers can see which result is authoritative. Keep production deployment only on one system at a time to avoid double releases. Compare build outputs, test counts and artifact checksums between the two systems. Remove the Bitbucket pipeline only after the team signs off. Confirm how your Bitbucket webhook and build status configuration handles two reporters before you enable it.
How does Jenkins handle approvals compared with Bitbucket deployment environments?
Jenkins does not have a one-to-one copy of Bitbucket deployment environments, so approvals are rebuilt with pipeline logic and access control. In a Jenkinsfile you can pause a stage for a manual approval and limit who can approve it using Jenkins authorization settings. Deployment targets become credentials and environment-specific configuration held on the controller, and you can separate production credentials from development ones. Confirm with your Jenkins administrator which plugins and roles you will use for approvals, because plugin behavior and maintenance differ across versions. Map each Bitbucket deployment environment to an explicit approval rule and test it before cutover.
What breaks most often when moving from Bitbucket Pipelines to Jenkins?
The most frequent problems come from assumptions that were never written down. Common issues include secured variables that were never copied because nobody knew they existed, artifacts that expired before anyone exported them, and Bitbucket-specific environment variables that scripts depend on. Webhook settings and build status reporting can also fail silently if the Jenkins server cannot reach Bitbucket or the credentials expire. Jenkins itself needs attention after upgrades: the 2.580.1 LTS release stopped bundling several plugins, including the SSH server and JUnit plugins, so they must be installed through the plugin manager. Build a checklist that covers each of these items and verify it during the parallel run.
How DeployOpen scopes and runs the migration
DeployOpen plans, implements, integrates, hardens, backs up and documents self-hosted Jenkins inside your own infrastructure, whether that is your cloud accounts, data center or air-gapped network. For a Bitbucket Pipelines move, the scoping conversation should settle which pieces are in the work: the Jenkins controller and its $JENKINS_HOME, the build agents, the Bitbucket webhook and build status reporting, the credentials that replace secured variables, and the approval gates that replace Bitbucket deployment environments. Most engagements are fixed-scope, so the list of repositories to convert, the target agent platform, the deployment targets and the acceptance tests are written down before any work starts. Ask for each of these to be named in the written scope, because a vague scope is the most common reason a migration runs longer than planned.
The written scope also sets the boundary of the security work. Secured Bitbucket variables cannot be read back, so the values have to be re-entered from their original owners into Jenkins credentials, and that step needs a named owner on your side. DeployOpen can configure the controller's access model, the credential scopes and the backup of $JENKINS_HOME, and can document the result so your auditors and security team can check it. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies do that work, so confirm with your assessor which evidence they expect before the scope is signed.
A quote follows from the written scope. Ask the quote to separate one-time migration work from recurring costs, and to state which of your staff, which DeployOpen deliverables and which infrastructure charges are included. Ongoing support, Jenkins upgrades that follow the LTS release line, plugin maintenance and continuous testing are available as retainers, and they can be priced separately from the migration. Ask what a retainer covers for LTS upgrades and plugin changes, how urgent fixes are handled, and what your team must still own. DeployOpen does not publish a price list, so the written scope and the retainer terms are the documents to compare across proposals.
