Skip to content
Helmhive Helmhive Helmhive

Adapter catalogue

An adapter is one typed deployment operation. Each declares its category, risk, required runner tools, configuration fields, and whether it supports verification and rollback. A runner publishes only the adapters for which both the code and the required tools are installed, and the Deployments → Adapters tab marks each catalogue entry Available when a registered runner offers it, otherwise Catalog.

Catalogue entries that no runner offers stay visibly unavailable; the scheduler never falls back to a similar adapter. Every adapter contract is pinned at lifecycle-safe version 2.0, and a runner reporting a different version is rejected at registration, heartbeat, and claim.

Promotion

Section titled “Promotion”

Promotion adapters open a constrained pull or merge request against an infrastructure repository. They write to a repository, never to infrastructure directly.

Gitea GitOps promotion

promotion.gitea

Create a constrained infrastructure branch and Gitea pull request.

  • Writes to a repository
  • Needs a connection
  • Supports rollback
  • Runner needs: git

GitHub GitOps promotion

promotion.github

Create a constrained infrastructure branch and GitHub pull request.

  • Writes to a repository
  • Needs a connection
  • Supports rollback
  • Runner needs: git

GitLab GitOps promotion

promotion.gitlab

Create a constrained infrastructure branch and GitLab merge request.

  • Writes to a repository
  • Needs a connection
  • Supports rollback
  • Runner needs: git

Transform

Section titled “Transform”

Transform adapters rewrite image references or variables in a specific configuration format ahead of a promotion step. A workflow that uses a transform must also contain a promotion step.

Docker Compose images

transform.compose

Update allowlisted Compose service image references.

  • Writes to a repository
  • Supports rollback

Helm values

transform.helm-values

Update configured image fields in a Helm values file.

  • Writes to a repository
  • Supports rollback

Kustomize images

transform.kustomize

Update configured image entries in a Kustomization.

  • Writes to a repository
  • Supports rollback
  • Runner needs: kustomize

Terraform variables

transform.terraform-vars

Update explicit image or release variables without touching state.

  • Writes to a repository
  • Supports rollback

Wavyzz stack.yml images

transform.wavyzz-stack

Update allowlisted service images while preserving stack.yml formatting.

  • Writes to a repository
  • Supports rollback

Generic YAML paths

transform.yaml-path

Update an explicit allowlist of YAML scalar paths.

  • Writes to a repository
  • Supports rollback

Execute

Section titled “Execute”

Execute adapters change infrastructure. They run only after the mutation boundary is recorded and are subject to the execution gate. The Terraform and OpenTofu saved-plan adapters do not support rollback, so a workflow containing them cannot produce a rollback plan.

Ansible playbook

execute.ansible

Run an allowlisted playbook and inventory from a fixed checkout.

  • Writes to infrastructure
  • Supports rollback
  • Runner needs: ansible-playbook

Argo CD sync

execute.argocd

Synchronize and wait for one allowlisted Argo CD application.

  • Writes to infrastructure
  • Needs a connection
  • Verifies
  • Supports rollback
  • Runner needs: argocd

Kubernetes apply

execute.kubernetes

Server-side apply an allowlisted manifest directory and wait for rollout.

  • Writes to infrastructure
  • Needs a connection
  • Verifies
  • Supports rollback
  • Runner needs: kubectl

OpenTofu saved plan

execute.opentofu

Apply an allowlisted saved plan whose SHA-256 was captured in the review.

  • Writes to infrastructure
  • Runner needs: tofu

CI/CD pipeline dispatch

execute.pipeline

Dispatch an allowlisted provider workflow and observe its terminal result.

  • Writes to infrastructure
  • Needs a connection

Terraform saved plan

execute.terraform

Apply an allowlisted saved plan whose SHA-256 was captured in the review.

  • Writes to infrastructure
  • Runner needs: terraform

Deployment webhook

execute.webhook

POST a bounded release document to an allowlisted HTTPS endpoint.

  • Writes to infrastructure
  • Needs a connection

Verify

Section titled “Verify”

Verify adapters are read-only checks placed after the last mutating step. Production workflows require at least one.

Container health

verify.container

Require explicit container services to report healthy through the executor.

  • Read-only
  • Verifies
  • Runner needs: docker

HTTP readiness

verify.http

Require an allowlisted HTTPS endpoint and expected status to become healthy.

  • Read-only
  • Verifies

Workflow result

verify.workflow

Wait for one Gitea, GitHub, or GitLab workflow to succeed.

  • Read-only
  • Verifies

Test

Section titled “Test”

The sandbox marker exists for deterministic proof of the deployment lifecycle without touching real infrastructure.

Sandbox marker

test.sandbox-marker

Write and verify a release marker below an isolated runner-owned root.

  • Writes to infrastructure
  • Verifies
  • Supports rollback

Reading a card

Section titled “Reading a card”
  • Read-only, Writes to a repository, and Writes to infrastructure describe the adapter’s declared risk.
  • Needs a connection means the step must be bound to a connection and authority alias.
  • Verifies means the adapter can act as a verification step; Supports rollback means a rollback plan can reuse it.
  • Runner needs lists the executables a runner must have installed to publish the adapter.