werf: full-cycle CI/CD to Kubernetes with Dockerfile and Helm

The gap werf fills between a Dockerfile and a running release

Most teams end up with three tools where they wanted one. A builder produces an image, a packaging layer renders manifests, and a deploy step pushes both to a cluster. Each step has its own cache, its own idea of what changed, and its own cleanup story. The registry fills with tags nobody can attribute to a commit.

werf targets that seam. The README describes it as a CNCF Sandbox CLI tool that implements full-cycle CI/CD to Kubernetes, integrating into your CI system and using Git, Dockerfile, Helm and Buildah. The audience is a team that already writes Dockerfiles and already has a Helm chart, and does not want to rewrite either. werf is the glue, not a replacement for the formats you know.

The project has been in production since 2017 according to the README, which also states that thousands of projects rely on it. That is a longevity claim, not a quality metric, and it matters mainly because it means the command surface has had time to settle.

How content-based tagging and Buildah fit together

The mechanism worth understanding is tagging. Instead of pushing a tag like latest or a build number, werf derives image tags from the content of the build. The README calls this automatic build caching and content-based tagging. The practical consequence is that two identical builds converge on the same tag, and a changed Dockerfile instruction or changed source layer produces a different one. Deployment then references a tag that means something specific.

The builder underneath is Buildah, listed in go.mod as github.com/containers/buildah v1.35.1, alongside containers/image and containers/storage. That is a different execution path from a Docker daemon: the repository does not depend on a running dockerd for the build. The go.mod file also pulls in Helm-adjacent libraries such as Masterminds/sprig, which is the template function set Helm charts use.

Deployment goes through an enhanced Helm integration. The README claims extra capabilities in Helm and enhanced resource tracking, and the repository layout backs the claim: there is a pkg/ tree for the CLI logic and a stapel/ directory that appears to hold the build-related code. The cleanup side is described as a unique container registry cleanup approach, which is the piece that removes images no live release points at.

Git is a first-class input. The topics list includes giterminism, and the go.mod file depends on go-git. The idea is that what gets built is determined by committed state rather than by whatever happens to be in the working directory, which is what makes a build reproducible from a CI checkout.

Setting up werf and where its commands are documented

The README does not inline install commands. It points at the Getting Started guide at werf.io/getting_started, which covers setting up and using werf both locally and in a CI system. Detailed usage and reference live at werf.io/docs, and there are framework-specific guides for Node.js, Spring Boot, Django, Rails and Laravel at werf.io/guides.html. Those pages, not this article, are where the exact binary install method for your platform lives.

What the README does name are the technologies the CLI drives: Git, Dockerfile, Helm and Buildah. So a first real use starts from a repository that already has a Dockerfile and a Helm chart, with werf.yaml at the root declaring the images and the chart supplying the manifests. The README gives no example werf.yaml, so copy the key names from werf.io/docs rather than from any snippet here.

The commands themselves are visible in the repository layout: cmd/ holds the CLI entry points, which is where the subcommand names live. The README frames the lifecycle as building and publishing container images, testing, deploying to Kubernetes, distributing release artifacts and cleaning up the container registry. Those are the verbs to look for in cmd/ and in the docs.

For local experimentation without a cluster, the repository ships a playground/ directory and a test/ tree, which is where to look if you want to see the project exercised rather than read about it.

Where werf stops being the right tool

werf is opinionated about the whole path. If your organization has deliberately split building from deploying, werf's full-cycle framing fights that split. A platform team that wants one tool to build and another to reconcile cluster state will find werf doing both, and the second half will duplicate whatever the reconciler already does.

The giterminism concept is a real constraint. Builds are tied to committed state, which is the point, but it means uncommitted local edits do not silently enter an image. Developers used to building from a dirty working tree will hit that as friction before they hit it as a feature.

The release cadence is worth reading carefully. The most recent release listed is v2.79.0, marked alpha, dated 2026-09-22. v2.78.2 is marked beta,ea, and v3.4.0 is marked dev. Those channel labels come from the release titles themselves. A team that wants a stable, plainly versioned artifact needs to check which channel they are actually pulling from, because the newest tag is not the most conservative one.

The README does not document rollback. That absence matters: if your delivery process requires a documented, first-class rollback command, you should confirm how the project expects you to handle it before designing around werf.

werf versus Helm alone and versus Argo CD

Helm alone renders and installs charts. It does not build images, and it does not clean a registry. If your images are built elsewhere and your only problem is templating manifests, Helm is already the answer and werf adds a build system you do not need. The difference is scope: Helm manages releases of rendered manifests, werf manages the artifacts those manifests point at.

Argo CD takes a different route entirely. It runs in the cluster and continuously reconciles live state against a Git repository, which makes it a pull-based controller. werf is a CLI you invoke from CI, so it is push-based: the pipeline decides when a build and deploy happen. If your requirement is drift detection against a Git source of truth, Argo CD's model is the closer fit. If your requirement is that a commit produces a tagged image and a release in one pipeline run, werf's model is the closer fit. The two are not mutually exclusive, but running both means deciding which one owns deployment.

Kubedog appears in the related search terms, and it is part of the same family of tooling around tracking Kubernetes resource state during a rollout, which is the concern werf's resource tracking addresses.

Maintenance, release channels and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-22, so the codebase is being changed. That is a statement about commit activity, not a promise about any particular release channel.

Upgrade cost depends on which channel you track. The release list shows alpha, beta and dev labels in active use, so pinning to a specific version rather than floating is the practical choice. The repository carries a CHANGELOG.md and a release-please-config.json, which indicates releases are generated from commit history; reading CHANGELOG.md between your pinned version and the target is the cheapest way to judge upgrade risk. There is also a trdl.yaml and trdl_channels.yaml at the top level, which suggests the project distributes its own binaries through channels rather than relying only on a package manager.

The licence is Apache-2.0, per both the README and the LICENSE file. That is a permissive licence with an explicit patent grant and a requirement to preserve notices. It is compatible with commercial use. This is a description of the licence text, not legal advice; if your organization has a policy review step for dependencies, the Apache-2.0 identifier is what that review needs.

Editorial conclusion

Adopt werf when your delivery pipeline already speaks Dockerfile and Helm and you want image building, deployment and registry cleanup driven by one CLI instead of three glued scripts. Skip it if you only need GitOps reconciliation of manifests you build elsewhere; Argo CD covers that with less machinery. Before committing, verify that your CI runners can run the werf binary, that a container registry is reachable from them, and that your chart's hooks and release names behave the way werf's Helm integration expects.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. werf/werf on GitHub