# werf — Consistent Delivery Tool for Kubernetes

> Build container images and deploy Helm-compatible releases to Kubernetes with content-based tagging, GitOps-ready pipelines, and built-in cleanup policies.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# werf — Consistent Delivery Tool for Kubernetes

## Quick Use
```bash
# install
curl -sSL https://werf.io/install.sh | bash
# converge (build + deploy) to the current kube context
werf converge --repo registry.example.com/myapp
```

## Introduction
werf is a CLI tool that combines container image building, Helm-based deployment, and artifact lifecycle management into a single consistent workflow for Kubernetes. It is designed to integrate into any CI/CD system and enforce reproducible, content-addressed builds with automatic registry cleanup.

## What werf Does
- Builds container images using Dockerfiles or its own Stapel builder with layered caching
- Deploys to Kubernetes using Helm-compatible charts with enhanced tracking and rollback
- Tags images by content digest rather than Git branch or commit SHA for deterministic deploys
- Cleans unused images from the container registry based on configurable retention policies
- Integrates with GitLab CI, GitHub Actions, Jenkins, and other CI systems out of the box

## Architecture Overview
werf reads a `werf.yaml` configuration that declares images, build instructions, and the Helm chart location. During the converge phase, werf builds images (using Buildah under the hood), pushes them to a registry with content-based tags, and runs a Helm-compatible release with enhanced resource tracking. It monitors Kubernetes resource readiness and can roll back automatically on failure. A built-in cleanup command scans the registry and removes images that are no longer referenced by Git history.

## Self-Hosting & Configuration
- Install via the official install script, Homebrew, or as a standalone binary
- Define images and build instructions in `werf.yaml` at the project root
- Place Helm chart templates in `.helm/templates/` alongside `werf.yaml`
- Configure registry credentials via Docker config or environment variables
- Set cleanup policies in `werf.yaml` to control image retention by branch, tag, or age

## Key Features
- Content-based image tagging that guarantees the same source produces the same tag
- Enhanced Helm deployments with real-time resource tracking and failure detection
- Built-in registry cleanup that removes orphaned images automatically
- Stapel builder for advanced multi-stage builds with Ansible provisioning
- Giterminism mode that ensures builds are fully reproducible from Git state

## Comparison with Similar Tools
- **Helm** — package manager for Kubernetes charts; werf adds image building, content tagging, and cleanup on top of Helm
- **Skaffold** — development workflow tool by Google; werf targets production CI/CD with stricter reproducibility
- **Flux/Argo CD** — GitOps controllers that sync manifests; werf handles the build-push-deploy pipeline before GitOps takes over
- **Kaniko** — in-cluster image builder; werf provides a complete delivery pipeline beyond just building images
- **Tilt** — inner-loop Kubernetes development; werf focuses on outer-loop CI/CD delivery

## FAQ
**Q: Does werf replace Helm?**
A: Not entirely. werf uses Helm internally for templating and release management but adds image building, content-based tagging, and cleanup that Helm does not provide.

**Q: Can I use standard Dockerfiles with werf?**
A: Yes. werf supports both standard Dockerfiles and its own Stapel syntax for image definitions.

**Q: What is giterminism?**
A: Giterminism is werf's mode that restricts builds to only use files committed to Git, ensuring fully reproducible builds regardless of local workstation state.

**Q: Does werf work outside of CI/CD?**
A: Yes. You can run `werf converge` from a local machine, but it is designed primarily for automated CI/CD pipelines.

## Sources
- https://github.com/werf/werf
- https://werf.io

---
Source: https://tokrepo.com/en/workflows/werf-consistent-delivery-tool-kubernetes-339c3c24
Author: Script Depot