Is Woodpecker CI a TeamCity alternative for Linux builds?
Woodpecker CI is a credible replacement for TeamCity when your builds are container-based Linux pipelines running on a Git forge such as GitHub, Gitea, Forgejo, GitLab or Bitbucket. TeamCity remains the better fit for teams that depend on build chains, IDE integration or Windows agents. The decision turns on three questions: which build types, operating systems and forge you use today, and how much of your TeamCity setup is actively used rather than inherited. Start with the inventory, not the tool. Woodpecker's engine is small, and that is its strength, but it also means some TeamCity features have no direct equivalent to plan around.
Woodpecker runs every workflow step inside a container image you specify, and its agents can run on Docker, Kubernetes or the local machine. Its forge documentation lists GitHub, Gitea, Forgejo, GitLab, Bitbucket and Bitbucket Datacenter, all with push, tag and pull request events, so it can sit beside your existing repositories. Connecting several forges to one server is still marked experimental in the 3.19.x documentation, so confirm that your setup needs only one forge per server. Check the plugins you rely on as well: the project says Drone plugins generally work but may need adjustments, so each TeamCity runner step should be tested against a container image before you commit.
Keep TeamCity in the plan where the work depends on its strengths. Build chains, snapshot dependencies and the IDE integration have no one-to-one counterpart in Woodpecker's YAML workflows, which use depends_on ordering instead. If any of your agents are Windows machines, confirm that the workload can move to Linux containers before you retire them. Also ask whether your team uses TeamCity's reporting, test history or IDE-driven run configurations daily, because features that go unused are cheaper to drop than features that must be rebuilt.
Which TeamCity alternative fits which scenario
This table maps common TeamCity workloads to the option that fits each one best, with the condition under which that option wins. Read it against your own build inventory: Woodpecker CI is a fit only where its container, forge and agent model match the work, and the rows marked otherwise point to tools that handle Windows, build chains or IDE-driven workflows more directly.
| Scenario | Better fit | Why |
|---|---|---|
| Linux container builds on GitHub, Gitea, Forgejo, GitLab or Bitbucket | Woodpecker CI | Each step runs in a container image and Woodpecker connects to all five forges, so it wins when builds are Linux containers and the repositories stay where they are. |
| Builds that need Windows agents or .NET tooling | TeamCity or Jenkins with Windows agents | Woodpecker agents run workflows on Docker, Kubernetes or the local machine, so Windows-native toolchains need confirmation of a supported agent path before you commit. |
| Multi-step build chains with snapshot dependencies | TeamCity or Jenkins | Woodpecker has parallel workflows with depends_on ordering, but it lacks an equivalent of TeamCity's snapshot dependencies; confirm how your chains map before migrating. |
| Teams that want builds beside an existing forge | Woodpecker CI | Woodpecker runs as a separate server that receives forge webhooks, so builds can move in-house without moving repositories. Multi-forge setups on one server are still experimental. |
| Teams that rely on IDE-driven run configurations | TeamCity or Jenkins | TeamCity's IDE integration and run configurations serve developers directly; Woodpecker pipelines are YAML files, so developers rely on the CLI and repository files instead. |
| Teams with Kubernetes-native build isolation | Woodpecker CI | The Kubernetes backend runs each step in its own pod with a shared temporary volume, which suits teams that already operate clusters and can size that volume. |
| Teams that need a large plugin ecosystem or custom steps | Jenkins | Jenkins has a broad plugin catalog; Woodpecker plugins are container images and existing Drone plugins generally work but may need adjustment. |
How TeamCity and Woodpecker CI compare on capabilities
This table compares how TeamCity and Woodpecker CI handle build definitions, execution, forge support and operations. Read the Woodpecker column as confirmed by the project's documentation, and confirm each TeamCity cell against JetBrains documentation for your exact version. The main takeaway is that Woodpecker covers container-based Linux pipelines well, while TeamCity's build chains, IDE integration and Windows agents need a separate check.
| Capability | TeamCity | Woodpecker CI |
|---|---|---|
| Build definition format | Configured in the web UI, or as Kotlin DSL or XML when versioned settings are enabled; confirm the options for your version | YAML workflows in a single .woodpecker.yaml or several files in a .woodpecker/ directory |
| Build chains or dependencies | Build chains and snapshot dependencies between build configurations; confirm exact behavior in your version | Workflows run in parallel and can be ordered with depends_on |
| Container execution | Builds run on agents; container use depends on how agents and build steps are configured; confirm with JetBrains | Every step runs its commands inside a specified container image, with optional service containers |
| Windows agents | Supports Windows agents; confirm current agent platform support for your version | Built for Linux container workloads; confirm any Windows support before planning around it |
| IDE integration | Offers IDE integration for configuration and build results; confirm the supported IDEs for your version | Configuration is a YAML file in the repository, so editing relies on the editor used for the repository |
| Forge support | Works with its own VCS roots and connectors; confirm the supported VCS systems for your version | GitHub, Gitea, Forgejo, GitLab, Bitbucket and Bitbucket Datacenter with push, tag and pull request events; connecting multiple forges to one server is experimental |
| Plugin model | Bundled features and plugins; confirm what ships with your edition and what needs extra installation | Plugins are container images configured through a settings block as pipeline steps; Drone plugins generally work but may need adjustments |
| Kubernetes execution | Agents run builds; confirm whether Kubernetes-based agents are supported for your edition | Kubernetes backend runs each step in a standalone pod with a temporary shared volume claim for the pipeline |
| Autoscaling and database options | Agent management is handled by the server; confirm autoscaling options and supported databases for your version | Optional autoscaler creates cloud VMs for pending builds; SQLite by default, with PostgreSQL or MariaDB recommended for larger instances |
Where Woodpecker's container model stops short of TeamCity
TeamCity keeps its strongest advantages where the team already depends on its server-side modeling. If build chains and snapshot dependencies express how artifacts flow between configurations, a container-based engine will need that graph rebuilt by hand. Windows build agents are the other hard boundary: Woodpecker's agents run workflows on Docker, Kubernetes or the local machine, so any pipeline that must compile or sign on Windows needs a separate, confirmed path before the migration is scoped. Developers who run configurations from their IDE through TeamCity run configurations will also notice that this workflow has no direct equivalent in Woodpecker, which is driven by the forge's push, tag and pull request events and YAML files in the repository.
Woodpecker covers a large share of ordinary pipelines. Its workflows can be a single .woodpecker.yaml or several files in a .woodpecker/ directory that run in parallel with depends_on ordering, each step runs inside a container image, and matrix builds and when filters handle branch and path conditions. The cost is rewriting: every build configuration, template and parameter becomes YAML that lives in the repository, and teams should expect a translation effort rather than a copy. Plugins written for Drone generally work, but the Woodpecker documentation says some may need adjustments, so each plugin the team relies on should be run once in a test pipeline before the cutover.
Before deciding, test three things on a representative project: a chain that mirrors an existing TeamCity build chain, a build that must run on a Windows agent, and the daily developer loop from the IDE. Confirm which Windows and macOS build requirements remain outside Woodpecker's Linux container model with the Woodpecker maintainers or the project documentation. Also check that the forge in use is supported; the Woodpecker forge documentation lists GitHub, Gitea, Forgejo, GitLab, Bitbucket and Bitbucket Datacenter, and notes that connecting several forges to one server is still experimental. If the test pipelines run cleanly and the Windows and chain requirements are covered, Woodpecker is a credible fit; if not, Jenkins or GitLab CI/CD deserve the same test.
What hosting and data control change for builds and secrets
Moving from TeamCity to Woodpecker CI changes where build logs, artifacts and secrets sit and who can reach them. The cards below cover the decisions that follow from self-hosting, the risks of hosted CI secret storage, and the work needed to show controls to an assessor.
Where logs, artifacts and secrets live
A self-hosted TeamCity server keeps build logs, artifacts and stored parameters on infrastructure you operate. Woodpecker splits the same data across a server, its database and the agents that run steps. Map each data type to a host and a database before cutover, including which agent hosts keep workspace files between steps. Ask whether any logs are forwarded to external services by default.
You choose the network and database
Woodpecker is self-hosted, so your team decides where the server runs, how agents reach it over gRPC, and whether the database is SQLite or PostgreSQL or MariaDB. SQLite is the default, and the documentation recommends PostgreSQL or MariaDB for larger instances. Decide these placements in writing, since they determine backup scope, network paths and who can restore a failed build history.
Keep deployment secrets inside
Hosted CI services hold deployment secrets for every connected project. In January 2023, CircleCI told customers to rotate secrets after an attacker exfiltrated environment variables, tokens and the keys needed to decrypt them. Self-hosting limits that concentration to your own environment, but it also makes your team responsible for the secret store, its access policy and rotation.
Plan secret migration by re-entry
Secret values usually cannot be exported from a CI platform. GitHub's API returns secret names without values, CircleCI does not show variable values after they are set, and Bitbucket secured variables can only be replaced or deleted. Expect to re-enter credentials into your new store from the source system of record, and inventory names and owners from your TeamCity export first.
Set artifact retention yourself
Hosted services set artifact limits you cannot change. GitHub Actions defaults to 90 days, CircleCI caps artifacts at 30 days, and Bitbucket Pipelines keeps them for at most 14 days. With Woodpecker, retention follows your storage and policy decisions, so set it per artifact class such as release binaries, test reports and images. Confirm how your chosen artifact store handles deletion and legal holds.
Control identity and agent access
Decide how people sign in to the Woodpecker server, which forge tokens it holds, and which accounts can trigger deployments. Agents need credentials to reach the server, so scope them to the projects they serve and rotate them on a schedule. Woodpecker 3.19.0 enforces agent labels on the server, which helps restrict which agents run which jobs. Confirm the exact authentication options for your forge in the forge documentation.
Prepare evidence for compliance
DeployOpen can plan the CI control set, configure logging and access records, document retention and secret handling, and assemble evidence for your assessment. Independent auditors and certification bodies issue any attestation or certification, so ask them early which evidence they need. Agree the scope in writing with DeployOpen before work begins.
What a TeamCity alternative costs in components
The TeamCity side of the cost is driven by licensing and people. TeamCity Professional is free within its build configuration and agent limits, so the cost question starts when a team needs more build configurations, pipelines or agents than that tier allows. Enterprise is licensed per agent, and the true-up billing on agent counts is the line item finance teams most often miss, because capacity added during a busy quarter can be billed later. Confirm with JetBrains directly how Enterprise and any true-up apply to your agent count, whether renewals are annual, and what happens to build history if the license lapses. The other recurring cost is the people who run the TeamCity server, its agents and its upgrades, which is paid for in operator hours whether or not a license fee exists.
The Woodpecker side has no license fee, so its costs are infrastructure, labor and support. The recurring items are the Woodpecker server, the agents that run workflows on Docker or Kubernetes, the database (SQLite by default, with PostgreSQL or MariaDB recommended for larger instances), and the optional autoscaler if you create cloud VMs for pending builds. Maintenance also recurs: plugin images, container base images and the .woodpecker.yaml or .woodpecker/ workflow files need review as the project changes, and each Woodpecker release needs an upgrade plan. Costs rise with the number of repositories, parallel builds and agent hours, and fall when builds are cached and workflows are kept small. The one-time costs are migrating pipelines, re-entering secrets (which cannot be exported from TeamCity) and validating builds against the new engine.
Before requesting a quote, write the scope: the number of build configurations and agents on each side, the Windows and Linux split, the forges in use, and the upgrade and support hours you expect. Ask the implementation partner to price migration, hardening, backup and upgrades as separate line items, so you can see which costs are one-time and which recur. Ask for the operator hours assumed for each side, and for a statement of what happens to secrets and build history during cutover. Woodpecker is the cheaper license line only when Linux container builds cover most of your workload, so model the Windows agent work separately and keep TeamCity or another engine for it until the numbers are clear.
What moving from TeamCity to Woodpecker CI involves
The migration runs as a sequence that inventories what TeamCity does, preserves the history and secrets you need, rebuilds pipelines and agents on Woodpecker, and then switches traffic over, so each phase ends with a check you can verify before the next one starts.
Inventory build configurations, chains and agents
Your team lists every build configuration, build chain, template, parameter and agent requirement in TeamCity. If versioned settings are enabled, the committed Kotlin DSL or XML files give you a complete starting inventory; if not, export the project tree from the administration UI. Each entry is tagged by what it builds, which agent it needs (Linux container, Windows, or macOS) and which external systems it touches. The step is done when every configuration has a row in the inventory and every agent requirement is mapped to a Woodpecker backend or is marked as a gap.
Export build history and artifacts to keep
Decide with the release and audit owners which build logs, test reports and artifacts must survive the move, then export them from TeamCity to storage you control. TeamCity holds this data on your own server, so the work is mainly about retention policy and storage capacity, not about rescuing data from a vendor cloud. The step is done when the agreed set of records is stored in a location your compliance team has approved and a sample can be opened and read.
Re-create secrets in Woodpecker
Secret values usually cannot be read back out of a CI system, so your team re-enters deployment credentials, tokens and signing keys into Woodpecker's secret store, scoped to the repositories that need them. Use the inventory from the first step to confirm which secrets each pipeline uses, and rotate any credential that was exposed, copied to a spreadsheet or shared across projects. The step is done when each pipeline's secret references resolve in a test run and the old TeamCity values are retired from active use.
Convert pipelines to Woodpecker YAML
Rewrite each build configuration as a Woodpecker workflow, either a single .woodpecker.yaml or a set of files in a .woodpecker/ directory, using depends_on for ordering where build chain dependencies existed. Each step runs in a container image you choose, and TeamCity-only features such as build templates, custom runners and certain reporting integrations need an equivalent plugin, script or external service. Where a needed plugin does not exist or needs changes, record it as an open item. The step is done when every converted workflow passes a dry run on a branch in a test repository.
Stand up agents with the right backend
Install Woodpecker agents on the platform that fits each workload. Container-based Linux builds can run on Docker or Kubernetes, where each step gets its own pod and pipelines share a temporary volume claim. Windows and macOS builds need agents on those operating systems, and Woodpecker's documentation should be checked for the exact support on each before you rely on it. Your team confirms the agent count, labels and capacity needed for peak build load. The step is done when agents report as connected and a test pipeline runs on each agent type.
Test on a parallel forge connection
Connect Woodpecker to your existing forge (GitHub, Gitea, Forgejo, GitLab or Bitbucket) while TeamCity keeps running production builds. Woodpecker's forge documentation lists push, tag and pull request events for each of these forges, and multi-forge connections to one server are still marked experimental, so plan one forge per server unless you confirm otherwise. Compare outputs of TeamCity and Woodpecker for the same commits, including test results and artifact checksums. The step is done when the outputs match for an agreed set of representative builds.
Cut over webhooks and retire TeamCity
Point the forge webhooks at Woodpecker, disable the matching TeamCity triggers, and watch the first live builds from both tools to confirm nothing runs twice or gets skipped. Keep the TeamCity server read-only for the retention period your audit team set in the export step, then decommission the server, its agents and its database. The step is done when production builds run only on Woodpecker, the decommission record lists every retained data set and its location, and the owners sign off in writing.
Questions buyers ask before choosing Woodpecker CI over TeamCity
How much effort and time does a move from TeamCity to Woodpecker CI take?
The effort depends on what you have configured, and no duration should be set until a scoped plan exists. The main drivers are the number of build configurations, how many build chains and snapshot dependencies link them, how many secrets and parameters must be recreated, and how many agent types need an equivalent. Simple Linux pipelines that build and test in containers are the quickest to convert. Build chains with artifact dependencies and Windows-specific steps take longer because each one needs a design decision. Ask for a written scope that lists each of these counts before agreeing a timeline.
What does the work need from our team?
Plan for three roles. First, an inventory of what TeamCity runs today, ideally exported from versioned settings in Kotlin DSL or XML so nothing is missed. Second, a forge administrator who can register Woodpecker as an OAuth application, manage webhooks and control repository access. Third, someone who knows the build logic well enough to confirm that each converted workflow still produces the same artifacts and runs the same tests. Your team also needs to decide who will operate the Woodpecker server and agents after handover, since those components need patching and capacity planning.
Can our team migrate to Woodpecker CI without outside help?
Yes, a team with container experience can usually handle simple Linux pipelines alone, using the Woodpecker workflow syntax and its documentation. Outside help reduces risk in a few specific places: translating build chains and shared templates, handling secrets that cannot be exported from TeamCity and must be re-entered, setting up agent isolation and access control, and building a rollback plan for the cutover. Many teams run the two systems in parallel for a period, which lowers the chance that a missed build breaks a release. DeployOpen plans, implements and documents this kind of work under a written, fixed scope if you prefer that model.
Does Woodpecker CI run builds on Windows agents?
Confirm this against the current Woodpecker documentation before you decide, because agent platform support changes between releases. The documented agent backends include Docker, Kubernetes and the local machine, and the workflow model is built around container images for each step. If your TeamCity estate depends on Windows agents, MSBuild-based .NET builds or Windows-only tooling, treat that as a gap until you have verified the supported platforms and tested a representative build. Teams with a mixed fleet often keep a small number of Windows build capacity elsewhere while moving Linux builds to Woodpecker.
Can Woodpecker CI run next to our existing forge without moving repositories?
Yes, for the forges it supports. Woodpecker's forge documentation lists GitHub, Gitea, Forgejo, GitLab, Bitbucket and Bitbucket Datacenter, with push, tag and pull request events on each. You can leave repositories where they are and point Woodpecker at them through webhooks, so the forge stays the system of record for code review. The documentation also states that connecting multiple forges to one Woodpecker server is still experimental, so plan for one forge per server unless you test the multi-forge setup yourself.
What should a quote for this migration include?
A quote should follow from a written scope, not a generic estimate. Ask for the scope to state the number of build configurations and pipelines in each category, the build chains and cross-project dependencies to be converted, the agent types and operating systems involved, and how many secrets and parameters must be re-entered. It should also cover the forge integration, the Woodpecker server and agent deployment, backup of the Woodpecker data, the cutover and rollback steps, and any documentation or handover work. Ask which items are one-time and which are recurring support or upgrade work.
How do we handle secrets and build history when leaving TeamCity?
Plan to re-enter secrets rather than export them. TeamCity secure values are not normally readable after they are stored, so you should expect to recreate each one in the new system, rotating any credential that was shared widely. Build history and stored artifacts also need a deliberate export or archive step, because they will not carry over automatically. Record which artifacts your release process depends on, then decide how long to keep the TeamCity data available. Put both steps into the written scope so the cost and access controls are agreed in advance.
How DeployOpen helps you evaluate and move off TeamCity
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For TeamCity vs Woodpecker CI, we start with a written inventory of your build configurations, agents and workloads, then decide with you whether Woodpecker CI fits or whether another open-source engine is the better match.
How we scope
- Inventory TeamCity projects, build chains, agent pools and Windows or macOS build needs before any decision
- Confirm which forges, repositories and deployment targets Woodpecker must reach from your current setup
- Agree scope, deliverables and timelines in writing, since most engagements are fixed-scope
- Ask for a written quote tied to that scope, because DeployOpen does not publish a price list
How we build
- Stand up the Woodpecker server, agents and database in your cloud account, data center or air-gapped network
- Convert representative pipelines into Woodpecker YAML and test them against real branch, tag and pull request events
- Map secrets into a store you control and confirm each value is rotated rather than copied out of TeamCity
- Run security testing on the pipeline and agent configuration before cutover
How we hand over
- Deliver the pipeline inventory, mapping decisions and configuration as documentation your team keeps
- Document backup, restore, upgrade and agent scaling procedures for your own operators
- Train your engineers on writing and reviewing workflows, plugins and container images
- Provide compliance evidence and control documentation for independent auditors to assess, since DeployOpen does not issue attestations
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover
- Keep pace with Woodpecker releases and review the impact of each upgrade on your pipelines
- Re-run security tests as agents, plugins and forge integrations change over time
- Agree the support scope and response expectations in writing before the retainer starts
