How to export your data from Bitbucket Pipelines before you leave
A renewal, a runner fee change, a data residency rule or a lock-in concern is usually what forces a move off Bitbucket Pipelines, and the export window starts the day you begin planning. Repository YAML and repository content can move, but artifacts expire within 14 days and secured variables can only be replaced. Bitbucket Pipelines keeps artifacts for at most 14 days with a 1 GB limit per artifact, so any build output your releases depend on has to be copied out before it ages off. Caches are kept for 7 days with a 1 GB limit, so they are working storage, not an archive.
Start by inventorying what exists in each repository: the bitbucket-pipelines.yml file, any custom pipes, deployment environments, and the build outputs you still need for audit or rollback. Pull the YAML and the repository history with Git, which will not be affected by the pipeline retention limits. For artifacts, decide which builds matter and download them through the pipeline before they expire, then store them in your own object or artifact storage. Confirm with Atlassian's current documentation whether any pipeline run history or logs can be retrieved after a repository is archived, because the retention rules for logs may differ from those for artifacts.
Secured variables are the step most teams underestimate. Atlassian documents them as encrypted and editable only by replacement or deletion, so their values cannot be read back and must come from your original secret source, such as a password manager, a vault or the cloud provider's secret store. Build an inventory that maps each secured variable to its owner and its source before cutover, and plan a rotation of deployment credentials in the new system rather than assuming values can be copied. Ask your Atlassian administrator to confirm which variables exist at workspace, repository and deployment level, because each scope has to be recreated separately.
Which Bitbucket Pipelines data you can export and in what form
This table lists the Bitbucket Pipelines data you can take out, the export path for each item, and the form it takes. Read the middle column first, since items marked for confirmation need an answer from Atlassian before you set your export window. The main takeaway is that the pipeline definition is safe in Git, while artifacts expire and secured variables cannot be read back.
| Data item | Exportable? | Export method and format |
|---|---|---|
| bitbucket-pipelines.yml | Yes, through Git | Clone the repository. The file is plain YAML and keeps its full commit history. |
| Build artifacts | Yes, within 14 days | Download before expiry. Each artifact is capped at 1 GB. Confirm the bulk download path with Atlassian. |
| Caches | No, not an archive | Kept for 7 days with a 1 GB limit. Do not plan to recover build data from caches. |
| Build logs | Confirm with Atlassian | Ask Atlassian for the log export format and how long logs remain available. |
| Secured variables | No, values cannot be read | Encrypted and only replaceable or deletable. Re-create values from the original secret source. |
| Non-secured variables | Confirm with Atlassian | Ask whether values can be read back in the UI or API. Otherwise, record them from your own source of truth. |
| Pipeline run history | Confirm with Atlassian | Ask whether run history can be exported in bulk. Keep a record of build numbers and commit SHAs. |
| Pipe references | Yes, as text in YAML | Pipe references sit in bitbucket-pipelines.yml. Record the pipe versions your builds used. |
What does not export from Bitbucket Pipelines and how to work around it
Bitbucket Pipelines keeps some data in a form you can copy out and some data you cannot read back at all. Repository pipeline files move easily, while secured variables, expiring artifacts and caches, and runner-side state need a planned workaround before the migration window closes. The cards below cover each gap and the check to run for it.
Secured variables cannot be read back
Secured variables can only be replaced or deleted once they are set, so their values never leave Bitbucket in readable form. The values must come from the original secret source, such as a password manager, a cloud secrets service or the system that issued the credential. Before cutover, inventory every secured variable per repository and workspace, record which system owns each value, and confirm that someone can still reach that source. Plan for re-issuing credentials where the source cannot be found.
Re-issue credentials instead of copying them
Deployment keys, API tokens and cloud access keys that were stored as secured variables should be treated as compromised by the migration itself. Issuing new credentials in the target CI system and revoking the old ones keeps the chain of custody clear. Check which service accounts the pipelines authenticate as, whether they have scopes beyond what the builds need, and whether the target pipeline can use short-lived credentials from your identity provider instead of static values.
Move values into a dedicated secrets manager
Where the source of a secret is unknown or spread across many repositories, a secrets manager gives the new CI system one place to read from. Store each value once, grant access by pipeline or project, and log reads. This also reduces the exposure seen in hosted CI incidents, where stored environment variables and the keys to decrypt them were taken together. Confirm the secrets manager runs in your own infrastructure and that its backup and recovery procedure covers the stored values.
Artifacts expire after 14 days
Bitbucket Pipelines keeps artifacts for at most 14 days, with a 1 GB limit per artifact, so any build output you need for audit, rollback or release records must be copied out during the build. Add a final step that uploads artifacts to your own object storage or artifact repository, and record the build number, commit and checksum with each copy. Check whether any release or compliance process relies on older artifacts before cutover.
Caches are not an archive
Pipeline caches, such as dependency directories, are kept for 7 days and capped at 1 GB, so they serve speed, not record keeping. Do not plan to recover build history or dependency state from them after migration. Instead, rebuild caches in the new system and pin dependency versions in lockfiles, so that a rebuild produces the same inputs. Confirm that your lockfiles and base images are in the repository or in a registry you control.
Runner-side state stays behind
Anything written on a self-hosted runner, including tool installs, local caches, scripts, certificates and logs, belongs to the runner machine rather than to the pipeline definition. Inventory what each runner holds, confirm which items are reproduced from code, and rebuild the build image or agent from a documented definition. Review the runner host for stored credentials and rotate any that sit there. Confirm the runner version you run and whether it is still eligible for the platform's runner pricing terms.
The sequence for a complete Bitbucket Pipelines export
This sequence moves build history, pipeline definitions and deployment secrets out of Bitbucket Pipelines in an order that protects the data most likely to be lost. Each stage ends with a check, so the team knows what has been captured before it moves on.
Inventory repositories, pipelines and deployments
The repository owner lists every repository with a bitbucket-pipelines.yml file, the branches and tags that trigger builds, the deployment environments each pipeline targets, and any pipes, custom pipelines and scheduled runs. The inventory is a spreadsheet or ticket that names an owner for each item. It is done when every repository that has run a pipeline in the last period appears on the list and each entry has an owner.
Copy artifacts and needed outputs before expiry
Engineers download the artifacts and build outputs the team still needs, such as release packages, test reports and signed images, and store them in a location the organization controls. Bitbucket Pipelines keeps artifacts for at most 14 days and caps each artifact at 1 GB, so this step should start on day one of the export. Confirm that each copy opens and that its checksum matches the value recorded at build time. The step is done when every artifact in scope has a verified copy outside Bitbucket.
Record the source of every secured variable
The security or platform lead maps each secured variable to the system where its real value lives, such as a password manager, a cloud secrets store or the identity provider that issued a token. Bitbucket secured variables can only be replaced or deleted, so their values cannot be read back for the move. Rotate any credential that has no traceable source. The step is done when every variable has a named source, an owner and a rotation plan, and nothing depends on a value only Bitbucket holds.
Export repository pipeline definitions
Because bitbucket-pipelines.yml lives in each repository, the export is mainly a matter of keeping the Git history intact. Engineers clone each repository with its full history, branches and tags, and confirm that the pipeline file, any scripts it calls and any pipe configuration are present in the clone. Repository access stays under the forge's control, so the step is about the code and its history. It is done when a mirror clone of each in-scope repository exists and the pipeline file in it matches the one in Bitbucket at the export commit.
Document pipe and cache dependencies
Engineers list each pipe, container image, external service and cache that a pipeline depends on, then record where each one comes from and which replacement will be used on the new platform. Caches are kept for 7 days and are not an archive, so they do not need to be copied, but their dependencies do. The output is a mapping table with one row per dependency. It is done when every pipe in the inventory has a replacement or a documented reason it is no longer needed.
Rebuild on the new platform and compare artifacts
After the new CI engine is configured with the replacement secrets, the team re-runs builds from the same commits used in Bitbucket. For each run, they compare the produced artifacts with the archived originals using checksums, test report counts and, where builds are reproducible, the package contents. Differences such as timestamps or build paths should be recorded and explained. The step is done when every in-scope pipeline produces artifacts that match the originals or have a documented, reviewed difference.
Verify each stage and sign off the export
After each stage above, a second person checks the evidence against the inventory: the artifact copies, the variable source register, the mirror clones and the comparison results. Gaps are logged and assigned before the next stage begins. The final sign-off lists the repositories, pipelines, artifacts and secrets that moved, together with any items retired or rotated. The export is complete when the owner signs the record and the archive is stored under the organization's retention policy.
Why the export window is set by artifact expiry and secret handling
The export window for a Bitbucket Pipelines migration is set by two things that Bitbucket does not keep for you: build outputs and secured variables. Artifacts from a pipeline run are kept for at most 14 days, with a 1 GB limit per artifact, and caches are kept for 7 days with a 1 GB limit. Once those periods pass, the build outputs from that run are gone, so the history of what each pipeline produced cannot be recovered from the platform. Caches are working storage to speed up builds and cannot serve as an archive. Plan the export before anything else, because the oldest outputs you still need are the ones closest to expiry. Ask your build owners which artifacts are required for audit, rollback or reproducing a released version, and copy those out on a schedule that runs well inside the 14-day window.
Secured variables follow a different rule. Bitbucket stores them encrypted and does not show their values again, so the only operations available are replacing or deleting them. An export therefore cannot pull the values across. For each secured variable, record which repository, workspace or deployment environment uses it, which system issued the credential, and who can rotate it. Treat every entry as a re-creation task that starts with the original secret source, such as a cloud account, a registry or a vendor console, and not with a copy from Bitbucket. Where a value is no longer available from its source, the team has to issue a new credential, which means the cutover depends on access to the people and systems that own those credentials.
This shapes the timeline in three ways. First, export artifacts and any build evidence your compliance program relies on while the 14-day window is still open, and keep a dated record of what was copied. Second, schedule secret re-creation before the first pipeline runs on the new platform, and confirm that rotated credentials work in a test branch before the old ones are revoked. Third, do not treat Bitbucket as the system of record for historical build outputs after migration. Confirm current limits against Atlassian's artifact documentation and variables and secrets documentation, since the platform's rules may change.
What to plan before the Bitbucket contract or runner subscription ends
Four decisions shape the export window: when the Bitbucket plan and billing end, how self-hosted runner slots are paid for until builds move, who keeps repository access for the new CI engine, and when secrets stop changing. Each card names the owner of that decision and the question to put to Atlassian or to your own team before the date is set.
Plan and billing end date
Confirm the exact date when your Bitbucket plan, Pipelines minutes and any runner billing stop, and whether build history stays readable after billing ends. Artifacts expire after at most 14 days, so a billing lapse can remove the last copy of build outputs before anyone exports them. Finance and the workspace owner should agree this date with the export plan. Ask Atlassian whether pipeline logs and artifacts remain accessible after the subscription lapses.
Self-hosted runner slot arrangement
If your builds run on Bitbucket self-hosted runners, check how many concurrent build slots you pay for and whether any runner version still in use is being phased out. Atlassian licenses premium v5 runners per concurrent build slot, so the slots you keep during the export window are a recurring cost that the platform owner must budget. Keep the runners running until the replacement engine builds the same branches successfully, and confirm with Atlassian how slots are released when you stop.
Repository access for the new engine
A CI engine such as Woodpecker CI needs read access to repositories and permission to write build status back to Bitbucket. Decide which service account or app holds that access, which workspace or projects it covers, and who can revoke it. The engine's webhook and status permissions should be reviewed before the first parallel run, so that a build failure does not look like a lost connection. The identity owner for the forge, usually the Bitbucket workspace administrator, signs off.
Freeze window for secured variables
Secured variables cannot be read back in Bitbucket, only replaced or deleted, so their values must come from the original secret source. Set a freeze window in which no one changes a secured variable, because a change made after the copy is taken will not appear in the new engine. Record which variables each pipeline uses, and assign an owner who can re-enter each value from the vault or password manager. Ask Atlassian whether any variable history or audit trail can be exported, and plan for the answer being no.
Cache and artifact copy ownership
Caches are kept for 7 days with a 1 GB limit, so they cannot serve as an archive. Artifacts are kept for at most 14 days with a 1 GB size limit per artifact. Name one owner for copying each build output to storage you control, and set a checkpoint before the final pipeline run. Confirm with the release or QA lead which artifacts must be kept for audit or customer delivery, since these are the items that the export must not miss.
Contract and renewal notice
Check the Bitbucket contract for renewal dates, notice periods and any data return terms that govern when pipeline data may be requested. Procurement and legal should confirm these terms in writing, because the export window may be shorter than the period in which a team expects to keep building. Ask Atlassian what it provides for export of pipeline configuration and build history, and record the answer in the migration plan before any date is fixed.
Where exported pipelines can land: Woodpecker CI, Jenkins or GitLab CI/CD
Woodpecker CI is the option that can leave your repositories where they are. It connects to Bitbucket and Bitbucket Datacenter as a forge, so pushes, tags and pull requests keep triggering builds while the code stays in Bitbucket. The work is in the pipeline definition and the agents, not in the source control system.
- Pipeline format: each step of
bitbucket-pipelines.ymlbecomes a workflow step in a.woodpecker.yamlfile or a.woodpecker/directory, where every step runs inside a container image you choose. - Plugins: Bitbucket pipes map to Woodpecker plugins, which are container images configured through a settings block. Confirm each plugin exists in the plugin index before you rely on it.
- Agents: you run the server and agents yourself, on Docker, Kubernetes or the local machine, so compute is a platform cost you own.
- Secrets: secured variables cannot be read back, so you re-enter them from their original source.
- Forge limits: multi-forge setups on one server are still experimental, so confirm the Bitbucket connection with your own repositories before you commit.
Before you choose this path, read the Woodpecker CI migration guide for Bitbucket Pipelines and confirm how your Bitbucket Datacenter version is supported.
Jenkins keeps the build layer separate from the repository layer as well, so it also works with Bitbucket as the source of truth. The pipeline moves from a YAML file into a Jenkinsfile, and most of the migration effort lands on plugins and credentials rather than on the forge.
- Pipeline format: steps and parallel steps become stages in a Jenkinsfile, written in Declarative or Scripted syntax and committed to the repository.
- Plugins: pipes are replaced by plugins or shared libraries, so the plugin inventory becomes part of the migration plan and of ongoing maintenance.
- Configuration: the Configuration as Code plugin can define the controller from YAML, but it does not install plugins, so plugin versions are managed separately.
- Agents and scale: dedicated build agents keep the controller free for HTTP and management, and all configuration and secrets back up from the controller's home directory.
- Upgrades: LTS releases and Java support dates change on a schedule, so check the release line before you pin a version.
Ask your team to inventory every pipe and every plugin in use, because that list usually determines how long the move takes. The Jenkins Pipeline documentation is the natural starting point for the Jenkinsfile side.
GitLab CI/CD is the option that changes the most at once. A self-managed GitLab instance hosts the repositories as well as the pipelines, so the move includes source code, merge request history and CI configuration. Plan this as a repository migration with a CI migration attached, not as a pipeline-only change.
- Repository move: repositories, issues and review history must be imported into GitLab before pipelines can run there, so confirm what your import tooling carries over.
- Pipeline format:
bitbucket-pipelines.ymlis rewritten as.gitlab-ci.ymlwith GitLab Runner executors, so each step needs a runner and an executor choice. - Tier decisions: GitLab Free, Premium and Ultimate differ in CI/CD and security features, so map which features your current pipelines rely on before choosing a tier.
- Operations: a self-managed instance needs backup, restore and an upgrade plan that follows the required upgrade stops, which adds recurring staff work.
- Deployment shape: the reference architecture you choose depends on user count, and stateful components should run on VMs or managed services rather than inside Kubernetes.
Schedule the repository import and the CI rewrite as separate workstreams, and confirm the GitLab tier and reference architecture against your user count in the GitLab documentation before you commit.
Questions buyers ask before exporting from Bitbucket Pipelines
How much effort does exporting from Bitbucket Pipelines take?
The effort depends mainly on how many repositories have pipelines, how much build output you need to keep, and how many secured variables must be re-created. Each repository's bitbucket-pipelines.yml is a text file and moves easily, so the pipeline definitions are rarely the bottleneck. Artifacts are kept for at most 14 days and caches for 7 days, so anything you want to keep has to be copied out while it still exists. Secured variables cannot be read back, so each one needs its value traced to the original secret source. Ask any partner to size the work from an inventory of your repositories, pipeline counts, artifact volumes and variable counts, and confirm the scope in writing before work starts.
How long does a Bitbucket Pipelines export window last?
The hard limits that set the window are documented by Atlassian: artifacts are kept for a maximum of 14 days, and caches for 7 days. Anything older than those windows is gone from Pipelines, so the export must run before the oldest build output expires. In practice, the timeline depends on approvals, change windows and how quickly secret owners can provide values. If you have a build that runs every day, the window is effectively always closing, so start the artifact copy early. Confirm the current retention settings for your plan with Atlassian, since they can change.
What does the team need to provide for the export?
The work needs people who can grant access and people who own the content. Typically that means:
- Repository administrators who can read pipeline definitions and artifacts for each project
- Secret owners who can supply the original values for secured variables, since Bitbucket will not reveal them
- Build owners who can confirm which pipelines, deployments and artifacts still matter
- A security contact who approves how credentials are handled during the move
Without these people available, the schedule slips regardless of how fast the technical work goes.
Can we export Bitbucket Pipelines data ourselves?
Yes, many teams do the export in-house, especially when the repository count is small and the pipelines are simple. Repository files and pipeline YAML can be copied with normal Git tooling, and artifacts can be downloaded through Bitbucket while they still exist. The parts most likely to need outside help are the artifact inventory, the secured variable handover and the verification that the new platform builds the same output. Whichever route you pick, write down the owner of each step and the checks used to confirm the result.
What cannot be exported from Bitbucket Pipelines at all?
Secured variables cannot be exported. Atlassian documents them as encrypted and editable only by replacement or deletion, so their values must come from the systems that issued them, such as a cloud account, a token provider or a password vault. Build history is also limited: once the artifact or cache window closes, the output is no longer available from Pipelines. Plan for these gaps by inventorying each secret's source and by copying the build outputs you need before the windows close. Confirm the exact behavior of your Bitbucket plan with Atlassian before you rely on it.
Does the export affect our repositories or existing deployments?
Exporting pipeline definitions and artifacts does not change the repositories themselves, but the cutover to a new CI engine does affect how builds and deployments run. Each deployment step, webhook and status check needs a matching setup on the new platform before Bitbucket Pipelines is switched off. Run both systems in parallel for a period, compare outputs and only then retire the old pipelines. Confirm with your deployment owners which production paths depend on Bitbucket Pipelines before the cutover date is set.
What should we confirm with Atlassian and the new platform?
Confirm with Atlassian the current artifact and cache retention for your plan, any export or download limits on artifacts, and how to obtain a complete list of repositories with pipelines enabled. Confirm with the new platform owner that the selected CI engine supports your build images, plugins or pipes, and the forge you use. Also ask whether the target can receive secrets through a secrets manager, and whether it can reach the same artifact storage your builds rely on. Get the answers in writing before the export plan is approved.
What does an outside export engagement typically cost?
The cost is set by the written scope, and DeployOpen does not publish a price list. A quote follows from the repository inventory, the number of secured variables, the artifact and build history to preserve, the verification effort and any cutover support. One-time work covers the inventory, the copy and the handover of secrets. Recurring costs appear only if you want ongoing support after the move. Ask any provider to itemize these components so you can see who does each part and what you still need to do yourself.
Official Atlassian and Woodpecker sources to check
Before you set any export deadline, read Atlassian's documentation on artifacts and on variables and secrets, because those two pages decide what you can move and how fast. The artifacts page is where the 14-day maximum retention and the 1 GB per-artifact size limit are documented, and it sets the clock for copying build outputs out of Pipelines. The variables and secrets page confirms that secured variables can only be replaced or deleted, so the values must come from your original secret source. Read both pages in full, including any notes on caches, which the topic facts describe as kept for 7 days with a 1 GB limit. Check the figures against the live text on the day you plan, since Atlassian can change them and this guidance does not replace the vendor's current wording. Use artifacts in steps is the first page to open.
Next, read the Woodpecker forge documentation to confirm that your code host is supported and which events trigger builds. The forges overview lists Bitbucket and Bitbucket Datacenter with push, tag and pull request events, and it also states that connecting multiple forges to one server is still experimental. That matters if you plan to run a second forge alongside Bitbucket during the transition. Confirm which Bitbucket edition you run, because Cloud and Datacenter may need different setup steps. Ask your platform team to write down the exact Woodpecker version they will deploy, since the forge documentation is versioned and the project publishes new releases regularly. Woodpecker forges overview sets out the supported forges and the event types.
Finally, treat these pages as the baseline for a written export checklist rather than a one-time read. Assign an owner to record the artifact retention limit, the secured variable inventory and the forge support status with the date you checked them. Ask Atlassian's support team or your account contact to confirm any limit that affects your contract, and test a single pipeline end to end on a non-production repository before scheduling the cutover. The cost of this check is internal staff time, and it recurs whenever Atlassian or Woodpecker publishes changes that affect your plan.
How DeployOpen scopes and delivers a Bitbucket Pipelines exit
The sequence turns an unstructured set of Bitbucket Pipelines configuration, artifacts and secrets into a written scope, a verified export and rebuilt pipelines on a self-hosted engine that your team operates.
Agree a written scope
DeployOpen and your team list every repository with a bitbucket-pipelines.yml file, the pipelines and branches that matter, the artifacts and caches in use, the deployment targets, and the secured variables each pipeline depends on. Your team confirms owners for each repository and for each secret source. The output is a signed scope document that sets deliverables and timelines before any work starts, and that scope is the basis for the quote.
Inventory pipelines, artifacts and secrets
DeployOpen reviews each bitbucket-pipelines.yml file for steps, pipes, caches, artifacts, deployment environments and triggers, and records which values are stored as secured variables. Because secured variables can only be replaced or deleted in Bitbucket, the inventory also identifies where each value originates, such as a password manager, cloud secret store or vendor console. The output is a mapping sheet that shows, for every pipeline, what can be copied out and what must be re-issued from its original source.
Export code, build outputs and history
Repositories stay in Bitbucket, so the Git history itself does not need to move. DeployOpen exports the artifacts your team needs to keep before they expire, since Bitbucket Pipelines keeps artifacts for at most 14 days, and copies them to storage you control. Caches are not treated as an archive because they last only 7 days. Your team confirms which build logs and outputs are retained for audit or release purposes. The output is an archive with a manifest listing each file, its source pipeline and its checksum.
Verify the export before cutover
DeployOpen checks the archive against the inventory: every artifact in the manifest must open, match its checksum and map to a pipeline in the scope. Where an artifact is needed for a later release, the team performs a restore test in the new environment. Gaps are logged and assigned an owner. The output is a signed verification report that your team accepts in writing, which is the evidence that the exit is complete for the agreed scope and not an audit report.
Re-create secrets at their source
Your team re-issues each secured variable from its original source, and DeployOpen loads them into the chosen engine's secret store, such as Woodpecker secrets or Jenkins credentials. Values are never copied from Bitbucket because they cannot be read back. Rotation is recommended for credentials that were exposed to any hosted service. The output is a secret register listing each secret, its new location, its owner and the date it was last rotated, with no secret values in the document.
Rebuild pipelines on the self-hosted engine
DeployOpen translates each bitbucket-pipelines.yml into the target format, such as Woodpecker YAML or a Jenkinsfile, and replaces pipes with containers or plugins where a direct equivalent exists. Woodpecker can keep Bitbucket as the forge, so webhooks and build status reporting can be configured against the existing repositories. Each rebuilt pipeline runs in parallel with the original on a non-production branch. The output is a set of pipelines with a comparison of build results against the originals.
Cut over and hand over
After the parallel runs match the expected results, your team switches the protected branches and deployment triggers to the new engine and disables the Bitbucket Pipelines configuration in each repository. DeployOpen documents the runbook, backup and restore steps for the CI server, and ownership of each pipeline. Ongoing support, upgrades and continuous testing can follow under a retainer if your team wants it. The output is a handover pack and a cutover record for each repository.
