Migrate from CircleCI to Woodpecker CI

Migrate from CircleCI to Woodpecker CI: what moves cleanly and what does not

Moving from CircleCI to Woodpecker CI is a pipeline rewrite, a secret re-entry exercise and an artifact export, and it can run beside your existing forge while you do it. If your renewal, credit spend, data residency requirement or lock-in concern is what brought you here, plan the work as three separate tracks: translate the .circleci/config.yml files into Woodpecker workflows, recreate the project and organization variables in Woodpecker's own secret store, and export build history you want to keep before CircleCI's 30-day artifact window closes. Woodpecker connects to GitHub, GitLab, Gitea, Forgejo, Bitbucket and Bitbucket Datacenter, so repositories can stay where they are while builds move in-house. Note that connecting more than one forge to a single Woodpecker server is still experimental, so pilot against one forge first.

Platform or DevOps engineers usually own the rewrite, with a security engineer reviewing the secret handling and an application team lead validating that test results match. Effort is moderate and scales with the number of projects, the number of orbs in use and how much logic lives in custom shell scripts. The main risk is not the YAML itself but silent behavior drift: CircleCI's resource classes, cache keys and workspace persistence have no one-to-one equivalent, so run both systems in parallel on a sample of repositories and compare outputs before you switch branch protection rules or deploy credentials. Ask whoever runs the work to inventory every orb and every environment variable first, since those two lists set most of the scope.

Secrets are the item that cannot be copied. CircleCI does not display environment variable values after they are set, so you will need the original owners to re-enter them into Woodpecker, and every one of them should be treated as compromised for planning purposes, following the rotation approach CircleCI itself recommended after its January 4, 2023 incident. Rotate credentials at the source system as you cut over, not after, so the old pipeline cannot keep using them. Keep the migration in writing with a fixed scope, a named owner for each pipeline and a cutover date per repository, and confirm with your own security team how the Woodpecker server and agents will be hardened, backed up and monitored before any production deploy key is placed there.

How CircleCI capabilities map to Woodpecker CI

This table maps each CircleCI capability used in a typical config.yml pipeline to its closest Woodpecker CI mechanism and marks it clean, needs rework or gap. Read the status first, then the Woodpecker mechanism, because a clean mapping still needs the pipeline file rewritten and tested. Most of the work sits in orbs, secrets and retention, not in the build steps themselves.

CircleCI capability	Woodpecker CI equivalent	Status
Workflows and jobs in config.yml	Parallel workflow files under .woodpecker/ that run side by side, ordered with depends_on	Needs rework: each workflow is rewritten as a separate file or step group
Docker executors	Every step runs its commands inside a specified container image	Clean: images map directly, though build images must be checked for root or socket needs
Orbs	Plugins are container images configured through a settings block; Drone plugins generally work but may need adjustment	Gap: no direct orb equivalent, so each orb is replaced by a plugin or inline commands
Contexts and environment variables	Repository or organization secrets re-entered in Woodpecker, referenced by name in steps	Gap: CircleCI values cannot be read back, so each secret must be re-created from its source
Artifacts	Files written to the shared workspace or pushed to external storage by a step	Needs rework: CircleCI's 30-day retention must be exported before cutover
Caches	No built-in cache equivalent documented here; use volume or external cache plugins	Gap: confirm the chosen caching approach in your own environment before relying on it
Machine and resource classes	Agents run workflows on Docker, Kubernetes or the local machine, sized by your own hosts	Needs rework: sizing moves to infrastructure you run and monitor
Branch and tag filters	when filters on event, branch, path and other conditions, plus matrix builds	Clean: conditions cover most CircleCI filters, but test edge cases such as tag patterns
Scheduled pipelines	Cron-style scheduling is configured on the Woodpecker server; confirm the exact setup for your version	Needs rework: schedules are recreated and tested on the new server
GitHub Actions workflow Preview	Not a Woodpecker feature; CircleCI's separate Preview path runs GitHub Actions files on CircleCI compute	Gap: do not expect existing .github/workflows files to run on Woodpecker

What can leave CircleCI and what must be re-entered

A CircleCI move splits into three groups: what already lives in your repositories, what you must pull out before retention or access ends, and what has to be recreated by hand on the Woodpecker side. Treat each group as a separate workstream with its own owner and check.

Pipeline config already in repositories

Your CircleCI pipelines live in .circleci/config.yml in each repository, so the workflow logic is already version controlled and can be read without CircleCI access. For Woodpecker, you will rewrite these into .woodpecker.yaml or several files in a .woodpecker/ directory. Inventory every config file, every workflow, every filter on branches and tags, and every orb reference, because each one maps to a different Woodpecker construct. Confirm with the Woodpecker documentation that no CircleCI import tool exists before you plan around one, since none is listed in the facts supplied for this page.

Build artifacts before retention ends

CircleCI keeps build artifacts for 30 days, and that is both the default and the maximum. Anything you need for audit, release provenance or rollback must be downloaded through CircleCI before that window closes, then stored in your own object store or artifact repository. Build logs and test results have their own retention, so confirm those separately with CircleCI. Decide which artifacts Woodpecker will regenerate on the first build and which must be preserved as evidence.

Environment variables that stay hidden

CircleCI does not display environment variable values after they are set, so you cannot copy them from the app. Ask each secret owner for the current value, or plan a rotation if the owner cannot supply it. Record which variables are deployment credentials, which are API tokens and which are signing keys, because each needs a different rotation path. Create the secrets in Woodpecker's secret store and confirm which projects and events may read each one before the first migrated build runs.

Forge webhooks to rebuild

Woodpecker reacts to push, tag and pull request events from your forge, so each repository needs a webhook pointing at your Woodpecker server before any build runs. Confirm which forge you use, since Woodpecker supports GitHub, Gitea, Forgejo, GitLab, Bitbucket and Bitbucket Datacenter. Remove or disable the CircleCI webhooks at cutover so two engines do not build the same commit. Check the forge documentation for which events and permissions the connection needs.

Deploy credentials and cloud access

Deployment pipelines usually authenticate to cloud accounts, container registries, Kubernetes clusters and package repositories using credentials that CircleCI stores. Rebuild these as scoped identities in each target system, for example a service account limited to one namespace or one registry path. Test each deploy step in a non-production environment first. Ask your security team to confirm who approves new deploy credentials and how they are rotated after cutover.

Context and orb equivalents

CircleCI contexts group shared variables and restrict them to selected projects, and orbs bundle reusable jobs and commands. Neither has a one-to-one copy in Woodpecker, so list each orb the pipelines call and each context they read. Replace orbs with container-image plugins or shared steps, and recreate each context as a set of Woodpecker secrets with explicit project scope. Note any orb that performs a security-relevant action, such as signing or scanning, because its replacement must be verified before you rely on it.

Migration sequence from inventory to decommission

This sequence moves CircleCI pipelines to Woodpecker CI one repository at a time, with each stage producing a record the next stage depends on. The order keeps CircleCI running as the fallback until Woodpecker has produced matching builds and secrets have been rotated.

Inventory pipelines, orbs, contexts and secrets
Engineers list every repository connected to CircleCI, the config files in each one (including any .circleci/config.yml that calls orbs), the contexts and project-level environment variables, and the scheduled or tagged workflows. Security or platform owners add which variables hold credentials. Because CircleCI does not display environment variable values after they are set, the secrets register records names, owners and where each value must be re-entered, not the values themselves. The output is a pipeline inventory and a secrets register, and the step is done when every connected repository has an entry and each orb has a named replacement or a note that none exists.
Export artifacts and build history
Before any cutover, the team pulls the build artifacts and job records they need to keep through the CircleCI API or the artifact download tools. CircleCI sets 30 days as the default and maximum artifact retention, so this export has a fixed window that starts before the inventory is finished. Compliance and release owners decide which records are retained and where they are stored in the organization's own systems. The output is an archive of artifacts with a record of what was exported and when, and the step closes when someone other than the exporter has checked the archive can be read.
Stand up Woodpecker server and agents
Platform engineers install the Woodpecker server and one or more agents in the organization's own infrastructure, using the Docker, Kubernetes or local backend that matches the build needs. They connect the server to the existing forge (GitHub, GitLab, Gitea, Forgejo, Bitbucket or Bitbucket Datacenter), choose a production-grade database for the server rather than the default SQLite, and set agent labels and access rules. Confirm the forge and version combination against the Woodpecker forge documentation before connecting production repositories. The output is a running server and agent pool with a documented configuration, and the step is done when a test push on a sandbox repository triggers a build.
Pilot one repository on Woodpecker
The team picks one low-risk repository with a representative pipeline and converts its config.yml into a .woodpecker.yaml or a .woodpecker/ directory. Each CircleCI job becomes a step that runs in a named container image, workflows with dependencies become workflows with depends_on, and orbs are swapped for Woodpecker plugins or plain commands. Secret values are re-entered from the owner's source of truth, not copied from CircleCI. The output is a pilot result: a pass or fail record for each job, the list of plugin changes, and any behavior differences found, reviewed by the repository owner.
Run both systems in parallel
For a defined period agreed by the team, both CircleCI and Woodpecker build the same commits on the pilot and then on the next repositories. The team compares job status, test counts, produced artifacts and deployment outputs for each commit and logs every mismatch. Deployments stay on CircleCI, or go to a non-production target, until mismatches are closed. The output is a parallel-run log that shows agreement or explains each difference, and the step is done when the owners of each repository accept the results in writing.
Cut over each repository by switching webhooks
For each repository, the team adds the forge webhook to Woodpecker, confirms that pushes, tags and pull requests now start Woodpecker builds, and then removes or disables the CircleCI project and its webhook. Deployment credentials are used only from the new secrets register entries, and any scheduled or tag-triggered workflows are re-checked. The output is a cutover checklist per repository, signed by its owner, that records the webhook change, the first successful Woodpecker build and the CircleCI project status. Repositories move one at a time so a failure affects a single pipeline.
Rotate secrets and decommission CircleCI
After the last repository has cut over, security staff rotate every credential that was stored in CircleCI, because the vendor's January 4, 2023 incident report told customers to rotate secrets after environment variables and keys were exfiltrated. Rotation updates the systems that use each credential, and the old values are revoked. Once artifact exports are verified and the rotation register is complete, the team removes CircleCI contexts, projects and API tokens and records the decommission date. The output is a closed secrets register with rotation evidence and a decommission record that the security and platform owners both sign.

What drives migration cost and duration

This table lists the factors that change how much work a CircleCI to Woodpecker CI move takes and what it costs to run afterward. Read each row as a question to answer in your own inventory before requesting a quote, since most of the effort sits in config conversion, secret re-entry and agent operations rather than in the engine itself. The main takeaway is that the Woodpecker licence carries no fee, so the cost comes from people, infrastructure and the count of orbs, contexts and plugin gaps you find.

Driver	Why it changes cost or effort	What to confirm or ask for in a quote
Number of pipelines and config files	Each pipeline or workflow must be rewritten as Woodpecker YAML, and workflows with many jobs take more review time than single-job files.	Count of config.yml files, workflows and jobs per repository, and whether the vendor converts them or your team does.
Orbs in use	Each orb must be replaced by a container-image plugin, a shell step or an in-house script, so heavily orbed configs need more design work.	List of orbs by name and version, and which ones have a published Woodpecker plugin in the plugin index.
Contexts and environment variables	CircleCI does not display stored values, so someone must re-enter each secret from its source system and confirm it works in a test run.	Number of contexts, secrets per context, and the owner of each source value who can supply it again.
Secret rotation	Because hosted CI stores the values, a move that includes rotation adds work in each downstream system and in deployment targets.	Whether the quote includes rotating credentials, updating cloud or registry trust, and a rollback plan.
Artifact and cache volume	Build artifacts expire on CircleCI after a limited window, so historical artifacts must be downloaded before cutover, and cache storage must be sized on your side.	Total artifact size and retention needs, and the storage backend (for example, S3-compatible object storage) chosen for pipeline files.
Docker or Kubernetes agent platform	Woodpecker agents run on Docker, Kubernetes or the local machine, and the Kubernetes backend creates a pod per step and a shared volume, which adds cluster capacity and RBAC work.	Target platform, expected concurrent steps, node pool sizing, and who operates the cluster and its upgrades.
Database choice	SQLite is the default, while PostgreSQL or MariaDB is recommended for larger instances, so a larger deployment adds database hosting and backup duties.	Expected build volume, the database engine your organization already operates, and backup and restore responsibilities.
Plugin gaps and custom steps	Drone plugins generally work but may need adjustments, so each plugin used on CircleCI needs a test, and any gap becomes a custom container build.	List of every plugin or custom Docker image in use, and which ones need a fork, rebuild or replacement.
Ongoing operations and staff time	Upgrades of the server and agents, pipeline maintenance and on-call for CI outages recur every month and are often the largest long-term cost.	Named owner, upgrade cadence, monitoring scope and whether a retainer for support and upgrades is included.

What usually goes wrong and how to prevent it

Most failed CircleCI to Woodpecker CI moves do not fail on the pipeline YAML. They fail on secrets, retained build history, plugin behavior, and the webhooks and forge settings that decide which system runs each build. Each card below names one risk and a check to run before cutover.

Secrets left unrotated

CircleCI reported in its January 4, 2023 incident that an attacker exfiltrated customer environment variables, tokens and keys. CircleCI does not let you read stored environment variable values back out of the app, so you cannot copy them into Woodpecker CI. Treat every value as compromised for the migration, issue new credentials, and store them as Woodpecker secrets with scoped visibility. Confirm the old credentials are revoked, not just unused.

Orbs replaced by unchecked plugins

CircleCI orbs bundle commands and jobs that your config calls by name. Woodpecker plugins are container images configured through a settings block, and the Woodpecker docs note that Drone plugins generally work but may need adjustments. Pin each plugin to a specific image tag, read its settings reference, and run it once in a non-production repository before relying on its output in a release.

Matrix and clone step behavior

Matrix builds and the default clone step can behave differently from CircleCI parallelism and checkout. Woodpecker 3.19.0 fixed an injection of matrix environment variables into the default clone step, which is a reason to confirm you run a release at or after that version. Compare the environment and checked-out commit in one matrix job against the CircleCI run, and check any script that assumes a particular working directory.

Artifacts lost after 30 days

CircleCI keeps build artifacts for 30 days by default and at most 30 days, so older artifacts cannot be recovered from the platform after the window closes. Export the artifacts you need through the CircleCI API before you disconnect projects, and store them in your own object storage or artifact repository. Woodpecker stores no equivalent history for you, so set retention on the new side before the first real release runs.

Webhooks pointing at both systems

If the forge still sends push and pull request webhooks to CircleCI, and also to Woodpecker CI, every commit can trigger two builds and two deployments. Before cutover, list every repository's webhooks and status checks on the forge, remove CircleCI hooks from the repositories you moved, and confirm which required checks branch protection expects. Run one test push and confirm exactly one pipeline starts.

Experimental multi-forge setups

Woodpecker's forge documentation for version 3.19.x lists GitHub, Gitea, Forgejo, GitLab, Bitbucket and Bitbucket Datacenter, but states that connecting multiple forges to one server is still experimental. If your organization has repositories on more than one forge, avoid assuming one Woodpecker server covers them all. Run a separate server per forge, or confirm the behavior with the Woodpecker project for your exact setup before you retire CircleCI.

How the migration differs by starting point

A small team with a handful of pipelines on GitHub usually has the smallest migration. Repositories stay where they are, and Woodpecker connects to GitHub as a forge, so the work concentrates on rewriting a few pipeline files and rebuilding secrets. The scope depends mainly on the number of pipelines and the number of people who must change their habits. Illustrative example: a team with three repositories and one deploy job would translate each CircleCI workflow into one file under the .woodpecker/ directory and run those files as parallel workflows.

Config rewrite: Each CircleCI workflow becomes a Woodpecker workflow file, either a single .woodpecker.yaml or several files in a .woodpecker/ directory.
Secrets: CircleCI does not display stored environment variable values again, so retrieve each value from its source system and enter it in Woodpecker, as described in CircleCI's environment variable guide.
Artifacts: CircleCI keeps build artifacts for 30 days at most, so download anything you need to keep before cutover.
Server sizing: A small instance can start with the default SQLite database, but confirm the choice against your expected build volume.

Confirm which GitHub permissions the Woodpecker connection requires and whether a trial pipeline can run beside CircleCI through one full release cycle.

What changes for developers after cutover

Developers mostly keep working in the same repositories, but the pipeline definition moves to a Woodpecker file. A team can use a single .woodpecker.yaml at the repository root or a .woodpecker/ directory holding several workflow files, which run as parallel workflows and can declare depends_on ordering. Each step names a container image and runs its commands inside it, so developers now debug the container image itself, not a CircleCI executor. Filters such as when conditions on event, branch and path decide what runs on each push, tag or pull request. Ask each team to review how its existing CircleCI when logic maps onto those filters before the first cutover build, because pipelines that depended on CircleCI-only behavior will fail in unexpected ways.

Triggering and reading builds changes less than the config does, but the places to look move. Builds start from forge events, so pushes and pull requests on GitHub, GitLab, Gitea, Forgejo, Bitbucket or Bitbucket Datacenter drive Woodpecker through webhooks, and developers check status on the Woodpecker UI and in the forge's commit status. Confirm with your platform team that the forge connection and webhook delivery work for every repository in the pilot group, and that developers know where logs now live. Old CircleCI job links will not resolve, so teams that bookmark build history should export it first.

Operational ownership moves with the server and agents. Woodpecker's server handles the UI, API and webhooks, and agents connect to it over gRPC, so the organization now answers for uptime, agent capacity and upgrades on infrastructure it controls. On-call rotations should cover the server, the database (SQLite by default, with PostgreSQL or MariaDB recommended for larger instances) and the agent pool. Access control also changes: repository permissions still come from the forge, but administrators, secret scopes and who can reach the agent hosts are now decisions your team makes and must document. Agree on these roles and an escalation path before the first production pipeline runs on Woodpecker.

Questions buyers ask before migrating from CircleCI to Woodpecker CI

What drives the cost of moving from CircleCI to Woodpecker CI?

The cost is mostly labor and infrastructure, not a license fee, because Woodpecker CI is Apache-2.0 licensed. The main components are the time to rewrite pipelines, the servers or Kubernetes capacity for the Woodpecker server and agents, database and storage, and the staff who run upgrades and on-call support. The size of the cost depends on how many CircleCI config files, orbs, contexts and environment variables you have, how many projects share patterns, and how much custom tooling sits behind your pipelines. Ask any quote to itemize pipeline conversion, infrastructure build, secret re-creation, parallel-run testing and handover, and to separate one-time work from ongoing support. Your own CircleCI invoices show what recurs today, which is the baseline to compare against.

How long does a CircleCI to Woodpecker CI migration take?

The duration depends on the number of pipelines, how many CircleCI orbs and custom executors they use, how much of the build depends on hosted features, and how much parallel running your release process requires. No supplied source gives a duration for this migration, so treat any single number with caution and ask for a timeline built from a written scope. A useful scope separates a pilot on a few low-risk repositories from the rest of the estate, and it includes time for each repository to run in both systems until results match. Teams with many shared orbs and complex approval gates usually need longer than teams with simple build-and-test pipelines.

What does my team need to provide for the migration?

You need people who know the pipelines, the deployment targets and the release approvals, plus someone who can grant access to the forge, the Woodpecker server and the build infrastructure. Expect to provide an inventory of CircleCI projects, contexts, orbs, environment variables and deployment steps, and access to the repositories and CircleCI project settings. Named owners must approve secret re-creation, because CircleCI does not display environment variable values after they are set, so the values must come from the systems that issued them. Someone with authority over production deployments should sign off on the parallel-run results before CircleCI is switched off.

Can our internal team migrate from CircleCI to Woodpecker CI on its own?

Yes, a team with CI, container and Git experience can do it, and the Woodpecker documentation describes the core concepts: workflows in YAML, container images for each step, when filters, matrix builds and plugins. The harder parts are usually operational: running the server and agents, choosing a database, backing up the instance, handling upgrades, and building the plugin replacements for orbs. Ask whether your team has capacity for those tasks alongside normal delivery work. Fixed-scope help from DeployOpen covers planning, implementation, hardening, backup, upgrades, documentation and support, and it can be limited to the parts your team does not want to own.

Do our repositories have to move when we switch to Woodpecker CI?

No. Woodpecker CI connects to GitHub, GitLab, Gitea, Forgejo, Bitbucket and Bitbucket Datacenter, so the code can stay on the forge you already use while the builds move in-house. Woodpecker's forge documentation lists push, tag and pull request events for these forges, and it states that connecting multiple forges to one server is still experimental. Confirm which forge and version you run, and check whether your CircleCI projects depend on features of that forge, such as protected branch rules or code owners, that you must reproduce for the new webhook setup.

How are CircleCI orbs and secrets handled during the move?

Orbs are reusable CircleCI packages, and Woodpecker CI has no direct equivalent, so each orb's function must be replaced with a container step, a Woodpecker plugin from the plugin index, or an internal script image. The Woodpecker plugin documentation notes that Drone plugins generally work but may need adjustments. Secrets cannot be copied from CircleCI, because its documentation says environment variable values are not readable in its app after they are set. Treat every value as something to re-create from its source system, and rotate credentials that were stored in CircleCI, which is good practice after any hosted CI platform change, and was the advice CircleCI itself gave customers in its January 4, 2023 incident report.

What happens to our CircleCI artifacts and build history?

CircleCI's artifact documentation sets 30 days as both the default and maximum retention period, so artifacts and build history older than that window are not something you can count on keeping in CircleCI. Export anything you need to keep, such as test reports, release binaries and build logs, before the migration and before the retention window closes. Plan where artifacts will live in the new setup, for example in a registry or object store that you run, and confirm how Woodpecker CI handles step outputs and caches in your version, because the topic documentation does not describe a direct replacement for CircleCI's artifact feature. Set your own retention rules for the new system.

What security risks should we review before migrating?

A hosted CI service holds deployment secrets for every connected project, which is why the CircleCI incident report in January 2023 led to a broad secret rotation. Moving to self-hosted Woodpecker CI moves that risk into your own network, so the review should cover who can administer the server, how agent machines are isolated, which secrets reach which pipelines, how forge webhooks are authenticated, and how the database and backups are protected. Woodpecker's Kubernetes backend runs each step in its own pod, which is one isolation option to evaluate. Security testing of the CI environment is part of the scope that DeployOpen can plan and run, but DeployOpen does not issue audit reports or certifications, so any assessment of your controls must come from an independent auditor or certification body.

How DeployOpen scopes and runs a Woodpecker CI migration

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For a move from CircleCI to Woodpecker CI, we start from a written scope that lists which pipelines, forge connections and secrets are in play, then build and hand over the Woodpecker installation in your environment.

How we scope

Inventory every CircleCI project, workflow, orb, context and executor type before any build work starts.
Confirm which forge hosts the repositories, since Woodpecker connects to GitHub, GitLab, Gitea, Forgejo, Bitbucket and Bitbucket Datacenter.
Record which environment variables must be re-created, and agree who supplies rotated values for each one.
Agree in writing which artifacts and build history are exported, given CircleCI's 30-day artifact retention window.

How we build

Deploy the Woodpecker server, agents and database in your own environment, with the backend (Docker or Kubernetes) you have chosen.
Convert CircleCI config into Woodpecker YAML, mapping workflows to parallel workflow files and orbs to container-image plugins.
Replace CircleCI orbs that have no direct plugin equivalent with container steps that you own and can review.
Run the converted pipelines alongside CircleCI and compare results on representative branches before cutover.

How we hand over

Document the installation, agent configuration, pipeline conventions and secret handling in a runbook your team keeps.
Provide a rotation checklist for every credential that lived in CircleCI, covering tokens and keys that cannot be exported.
Walk your engineers through adding pipelines, plugins and agents so they can maintain the system after handover.
Deliver an export record of the artifacts and build history retained before the CircleCI account is closed.

How we support

Fixed-scope engagements end with written deliverables and a documented acceptance step agreed at the start.
Ongoing upgrades, backups and Woodpecker release tracking are available as a retainer, so your team is not left to patch alone.
Continuous security testing of the CI environment, including the server, agents and secrets handling, can be added to the retainer.
Ask any quote to name the pipeline count, forge, agent backend and secret volume it is based on.

Migrate from CircleCI to Woodpecker CI