Ring Promoter vs Argo CD, Kargo, Spinnaker and CI: Release Workflow Design and Architecture Decision Records

Release tooling is usually chosen by feature list and then lived with for years. This article takes a different route. It starts from the question each tool is built to answer, compares Ring Promoter with Argo CD, Flux, Kargo, Spinnaker, Octopus Deploy, Harness and CI pipelines using Ring Promoter’s own comparison at ringpromoter.com/compare, designs three release workflows around the result, and then shows how to capture the decision in Architecture Decision Records (ADRs) so it can be audited, explained and revisited.

Companion reading: the short version of this piece is the blog post Which Tool Answers Which Release Question. The promotion protocol itself is covered in Every Release Earns Production, and gate placement in QA Gates Before Production.

About the sources. Statements about Ring Promoter come from its README and from ringpromoter.com. Statements about other products summarise Ring Promoter’s own comparison page; they are a vendor’s view of its competitors. Products change, so verify each row against the vendor’s current documentation before it informs a decision.

1. Start with the question, not the feature list

The compare page frames the market around three questions:

Tool family	Question it answers	What it leaves to you
Argo CD / Flux	“Does the cluster match the manifests in Git?”	Moving a version from staging to production: a PR, an image updater, or another tool such as Kargo.
CI pipelines (GitHub Actions, Jenkins, GitLab)	“Did the deploy job exit 0?”	A record of what runs in each environment, and automatic rollback. A green job can leave the old version answering 200 OK.
Ring Promoter	“Is this exact version healthy here, and is it allowed into the next ring right now?”	Git sync and drift detection, and traffic shifting inside a ring.

Ring Promoter’s model, from its README, is an ordered set of shared rings, int (Integration) → test (Test) → acc (Acceptance) → prod (Production), with current and previous version and full history kept per (application, ring). Promotion moves one ring at a time and never skips. The source ring must be healthy before a promotion starts; after deploying, the target is health-checked with a configurable number of retries; if it is still unhealthy it is rolled back automatically to its previous version; and every seed, promote, rollback and restart is written to history, success or failure.

2. The feature matrix

The table below reproduces the compare page’s matrix. “Yes” means built in; “Partial” means it needs an add-on, plugin, paid tier or custom script; “No” means not provided. Notes in brackets are the compare page’s own qualifiers.

Capability	Ring Promoter	Argo CD	Flux	Kargo	Spinnaker	Octopus	Harness	GH Actions envs
Promotion model
Ordered environment promotion	Yes (never skip; current, previous, history per app and ring)	No (promote by PR)	No	Yes (Stages + Freight)	Yes (pipeline stages)	Yes (Lifecycles)	Yes	Partial (no ledger)
Kubernetes and VM apps in one control plane	Yes (kubectl, K8s Jobs, GitHub Actions dispatch)	No (Kubernetes only)	No (Kubernetes only)	No (Kubernetes only)	Yes	Yes	Yes	Yes
Opt-in auto-promote per ring, hard stop before prod	Yes (config cannot enable auto-promote into prod)	No	No	Yes	Yes	Yes	Yes	Partial
Verification and rollback
Version-verified health check	Yes (JSON field or header; also checks source ring)	No (resource health only)	No	Partial (custom AnalysisTemplate)	Partial (custom stage)	Partial (script step)	Partial (custom verify)	No
Automatic rollback on failed health	Yes (runs detached)	Partial (needs Argo Rollouts)	Partial (needs Flagger)	Partial (via Rollouts)	Yes	Partial (scripted)	Yes	No
Rejects a non-existent version before deploying	Yes (400 before any dispatch)	No	No	Yes (Freight from warehouse)	Partial	Yes (packages)	Yes	No
Release governance (checked before any deploy)
Maintenance windows	Yes (opened inline from promote dialog)	Yes (sync windows)	No	Partial (via Argo CD)	Yes (execution windows)	Yes (deployment freezes)	Yes (freeze windows)	No (wait timer only)
Go/No-Go sign-off for an exact version	Yes (with QA status and engineer)	No (Git PR review)	No	Yes (manual promotion)	Yes (manual judgment)	Yes	Yes	Yes (required reviewers)
Jira change-request validation	Yes	No	No	No	Partial (plugin)	Partial (paid tier)	Yes	Partial (third-party action)
Dashboard metrics as a release gate	Yes (Grafana; max_age stale detection)	No	Partial (Flagger)	Yes (Analysis)	Yes (Kayenta)	Partial	Yes	No
Where Ring Promoter is not the better choice
Git as source of truth, drift detection, self-heal	No (its database is the source of truth)	Yes	Yes	Yes	No	Partial	Yes	No
Canary / blue-green traffic shifting	No (whole-ring deploys)	Partial (Argo Rollouts)	Partial (Flagger)	Partial	Yes	Partial	Yes	No
SSO and fine-grained RBAC	No (API bearer token + prod password)	Yes	Partial (K8s RBAC)	Yes	Yes	Yes	Yes	Yes
Operational footprint	Small (one Go binary; Postgres or in-memory)	Medium	Medium	Large (Argo CD + Rollouts + Kargo)	Large (about 10 services)	Medium (server + SQL, or SaaS)	Large (SaaS or heavy self-host)	Small (hosted)

Two things stand out. First, the last block is unusual for a vendor page: it lists four rows where Ring Promoter loses. Second, the rows where it wins cluster around one idea, which is verifying that a specific version is running and allowed before the next step. That is the gap between “the deploy finished” and “this release has earned production”.

3. Head to head

Argo CD

According to the compare page, Argo CD is better at keeping clusters in sync with Git and fixing drift, at multi-cluster scale with SSO and project RBAC, and it has a large CNCF community. Ring Promoter is better at moving a version from int to prod (“Argo CD has no promotion model”), checking the running version and rolling back automatically, change windows, sign-offs, Jira CRs and Grafana gates, and apps that do not run on Kubernetes. The verdict: Argo CD is a sync engine; Ring Promoter is a release control plane. An Argo CD deployer is on Ring Promoter’s V2 roadmap so the two can run together.

Kargo

Kargo is the closest match: promotion on top of Argo CD. It is better at GitOps-native promotion (it writes to Git) and traffic-level analysis through Argo Rollouts. Ring Promoter needs no Argo CD, Rollouts or CRDs (“one binary instead of three systems”), handles VM and CI-driven apps alongside Kubernetes, has built-in maintenance windows, Jira CR and Grafana gates, and offers version-verified health without writing AnalysisTemplates. The verdict: fully committed to Argo CD on Kubernetes, look at Kargo; mixed estate or no GitOps stack yet, Ring Promoter has less to run.

Spinnaker

Spinnaker is better at multi-cloud (AWS, GCP, Azure) deployment strategies and canary analysis with Kayenta. Ring Promoter is one Go binary rather than about ten Java services, apps are added with config only, and version-verified health and Jira CR gates are built in. The verdict: Spinnaker suits large platform teams who can staff it.

Octopus Deploy and Harness

These commercial platforms are better at breadth (many deploy targets, templates and integrations) and at enterprise access control, audit and vendor support. Ring Promoter has no per-seat or per-service licence, is self-hosted with data and AI diagnosis on your own infrastructure, is small enough to read the whole promotion engine, and keeps your existing GitHub Actions workflows instead of replacing them. The compare page calls Octopus lifecycles and Harness pipelines the closest in concept.

GitHub Actions, GitLab CI and Jenkins

CI is better at building, testing, packaging and anything you can script. Ring Promoter is better at knowing what runs in every ring now and what ran before, rolling back automatically when health fails, and stopping a prod deploy outside a change window. The verdict is the one to remember: “Not a replacement. CI produces the version; Ring Promoter moves it. Your deploy workflow becomes one of Ring Promoter’s deployers.”

4. Release workflow designs

The comparison only becomes useful when it shapes a workflow. Below are three designs built from documented Ring Promoter behaviour. Config and commands are taken from the project README and its sample config.yaml; app names are the README’s examples.

Design A: CI seed, automatic early rings, gated production

This is the pattern the README describes as typical. CI builds and pushes an image, seeds int, and optionally promotes once:

RP=https://ring-promoter.example.com
APP=web-frontend
TOKEN=${RING_PROMOTER_TOKEN}   # from CI secrets
VERSION=$GITHUB_SHA            # the image tag you just pushed

curl --fail -sS -X POST "$RP/api/apps/$APP/seed" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"ring\":\"int\",\"version\":\"$VERSION\"}"

curl --fail -sS -X POST "$RP/api/apps/$APP/promote" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"from_ring":"int"}'

Calls run synchronously by default and return 200 on success or 422 when the operation ran but failed (for example, the health check failed and the target was rolled back), so curl --fail turns a failed promotion into a failed CI step. Add ?async=1 to get 202 with a job ID and poll GET /api/apps/{app}/jobs/{id} instead.

Auto-promote then carries the version onward. Declaring it in config makes config the owner of the switch:

rings:
  int:  { namespace: int,  ... }                     # unset: operator-controlled
  test: { namespace: test, ..., auto_promote: true }  # config-owned: on
  acc:  { namespace: acc,  ..., auto_promote: false } # config-owned: off

With test on, a version that lands healthy in test continues to acc inside the same operation and lock. With acc off, nothing reaches prod without a human. The README is precise about the three states: absent keeps the runtime API toggle; an explicit value is applied at every start-up, and the API toggle returns 409 for that ring. Config may not set auto_promote: true on the ring before production, which is refused at start-up so config cannot bypass the production password.

Gates guard the sensitive rings. From the sample config.yaml:

promotion_policy:
  maintenance_window:
    rings: [prod]
    recurring:
      - days: [Sat, Sun]      # empty = every day
        start: "02:00"        # HH:MM, in `timezone`
        end:   "04:00"        # end < start crosses midnight
        timezone: Europe/London   # empty = UTC
  qa_signoff:
    rings: [acc, prod]
  change_request:
    rings: [acc, prod]
    provider: jira            # test | jira
    jira:
      base_url: https://your-org.atlassian.net
      email: releases@your-org.com
      token_env: RP_JIRA_TOKEN        # default
      allowed_statuses: [Approved, "Ready for Release"]   # empty = any issue
      project_keys: [CR, OPS]         # optional prefix guard

A Grafana gate can be added for slow signals such as nightly end-to-end suites, with go_min, no_go_max, a list of checks and max_age. Two interactions matter for workflow design. Auto-promote into a change-request-gated ring fails closed, because there is no interactive CR code, so such rings are always promoted into explicitly. And auto-promote into a Grafana-gated ring stops at a no-go, because an override needs a human reason. The final hop needs the production password (RP_PROD_PASSWORD) in the request body; rollbacks are exempt.

Two operational details from the README are easy to miss. The CI example deliberately seeds only into the first ring; higher rings are “typically promoted deliberately from the UI or a separate approved job using the same promote call”. And the demo CR code test is always accepted whatever the provider, which is convenient for demos and worth stating in your ADR so nobody mistakes it for a production control.

Design B: a mixed Kubernetes and VM estate

Many estates are not all Kubernetes. Ring Promoter selects the deployer per application, so one control plane can promote both. Kubernetes apps use KubectlDeployer (kubectl set image plus rollout status) or the k8sjob deployer, which runs each operation as a Kubernetes Job with the runner contract RP_APP, RP_RING, RP_VERSION, RP_TARGET_ENV and RP_EXECUTION_ID. VM apps with an existing pipeline use GitHubActionsDeployer, which dispatches the workflow, waits for the run and applies the same health check and rollback.

The README’s real example is wslproxy, an OpenResty/Lua app on VMs:

apps:
  - name: wslproxy
    deployer: github                      # override the global deployer
    github:
      owner: bwalia
      repo: wslproxy
      workflow: deploy-single-environment.yml   # per-env deploy, no cascade
      ref: main                           # branch hosting the workflow (default)
      deploy_mode: full                   # value sent as the DEPLOY_MODE input
      token_env: RP_GITHUB_TOKEN          # env holding the API token (Secret)
      poll_interval: 20s                  # how often the run is polled
      run_lookup_timeout: 90s             # wait for the dispatched run to appear

The design lesson is in the README’s warning: point the deployer at a workflow that deploys exactly one environment. A cumulative delivery pipeline, where each stage depends on the previous one, would turn a single-ring deploy into a run all the way to production, and a prod rollback could revert lower rings. For GitHub-deployed apps, seed also checks that the branch, tag or SHA exists and rejects a typo with 400 before dispatching anything.

Design C: pairing with Argo CD, Argo Rollouts or Flagger

The compare page recommends pairing rather than replacing: “Argo CD or Flux, with Ring Promoter for promotion” where Git must be the source of truth for cluster state, and “Argo Rollouts or Flagger, alongside either” for percentage-based canary traffic. Today there is no Argo CD deployer (it is planned for V2), so a pairing needs a deliberate design. These are our design notes, not built-in features:

• Decide who owns the image tag. If Argo CD self-heals a Deployment and Ring Promoter’s KubectlDeployer runs kubectl set image on the same object, the two tools may disagree about the desired state. Give each field one owner. One option is the k8sjob deployer, whose runner script receives RP_VERSION and RP_TARGET_ENV and could update the environment’s Git configuration for Argo CD to sync; the exit code decides success.
• Let version-verified health close the loop. With health_version_field or health_version_header set, Ring Promoter only reports success when the endpoint reports the version just deployed, however the change reached the cluster. Size retry.count, retry.delay and operation_timeout to cover the time sync and rollout take.
• Treat canary as inside a ring. Ring Promoter deploys a ring as a whole. Argo Rollouts or Flagger can shift traffic within that ring; Ring Promoter then decides whether the version may enter the next ring. During a canary, a health endpoint may be served by either version, so check how your health URL routes before enabling version verification there.

Whatever you choose, record it. This is exactly the kind of cross-tool contract that is obvious to the person who designed it and opaque to everyone else.

5. Failure modes this setup prevents

The value of a promotion control plane shows up in the failures it removes. Each of these is documented behaviour.

Failure mode	What happens without a control	Ring Promoter mechanism
Green deploy, old code	The deploy job succeeds but old pods still answer 200 OK; the release is marked done.	Version-verified health: the endpoint must report the exact version just deployed, otherwise the check fails and the ring rolls back. The source ring is verified too.
Aborted rollback	A CI runner timeout or load-balancer idle timeout kills the request mid-deploy, leaving a ring half-changed.	Operations run on a context detached from the HTTP request, bounded by operation_timeout, so neither the deploy nor its rollback can be cut off.
Stale metrics read as GO	A nightly suite quietly stops running and its last green result shows forever.	max_age turns an old result into NO DATA. An unreachable Grafana is advisory, so an observability outage does not become a release outage, and the UI never shows it as a GO.
Half-finished release	A gate fails after some rings have changed.	Gates are checked before any deploy; a failed gate leaves all state untouched.
Concurrent promotions	An accidental scale-up runs two promotions on the same app.	A Postgres session advisory lock serialises operations per app across replicas.
Skipped environment	A version jumps from test straight to prod.	promote {from_ring} always targets the next ring; rings are never skipped.
Typo’d version	A non-existent ref triggers a doomed workflow run.	For GitHub-deployed apps, seed rejects it with 400 before dispatch.
Sign-off reused for a different build	Approval for v1 is treated as approval for v2.	Go/No-Go sign-offs are version-specific: a GO for v1 does not authorise v2.

6. Architecture Decision Records

The previous sections contain at least five decisions with long-lived consequences: which tool owns promotion, which owns sync, whether version verification is mandatory, which rings auto-promote, and how the limits are mitigated. Decisions like these tend to live in a chat thread or one engineer’s head. Architecture Decision Records give them a durable home.

What an ADR is

An ADR is a short document that records one significant decision, the context that forced it, and its consequences. The format most teams start from was proposed by Michael Nygard in 2011 in “Documenting Architecture Decisions”. It has five parts:

1. Title: a short noun phrase, numbered (for example “ADR-001: Use Ring Promoter for environment promotion”).
2. Status: proposed, accepted, deprecated or superseded (with a link to the replacing ADR).
3. Context: the forces at play, technical, organisational and regulatory, stated neutrally.
4. Decision: what we will do, in active voice (“We will…”).
5. Consequences: what becomes easier and what becomes harder, including the costs.

MADR (Markdown Any Decision Records) is a popular alternative with more structure: a problem statement, decision drivers, considered options, the decision outcome and the pros and cons of each option. It suits decisions like this one, where the considered options (Argo CD alone, Kargo, Ring Promoter, a commercial platform) are themselves useful to record. Either format works; consistency within a repository matters more than the choice.

Why ADRs matter for release tooling

• Reversibility. Release tooling sits on the path to production. Swapping it later touches every pipeline and every on-call runbook. An ADR forces the team to write down what would make the decision wrong before it is expensive to change.
• Audit. When a change-management reviewer asks why prod promotions require a CR code and a password but rollbacks do not, the ADR is the answer, with the date and the people who accepted it. Ring Promoter’s history table records what happened; the ADR records why the controls exist.
• Onboarding. A new engineer who finds Argo CD installed but not deciding promotions will reasonably assume a mistake. One page of context prevents a well-meant “fix”.
• Revisiting when constraints change. The compare page lists limits that may not last: no SSO or per-user RBAC yet, no Argo CD deployer until V2. Writing “revisit when SSO lands” into the consequences turns a known gap into a trigger.

Lifecycle and storage

An ADR is born proposed, usually as a pull request. Review happens in the PR, where the people affected can comment. Merging marks it accepted. When circumstances change, you do not rewrite the accepted ADR; you write a new one that supersedes it, and update the old one’s status to point forward. Some ADRs are rejected, and keeping those is valuable too, because they stop the same debate recurring.

Store ADRs in the repository they govern, typically docs/adr/ with numbered file names such as 0001-use-ring-promoter-for-promotion.md. Keeping them beside the config means a change to promotion_policy and the ADR that justifies it can be reviewed together. Tools such as Nat Pryce’s adr-tools automate numbering and linking, but a directory and a template are enough to start.

A note on sources: the Ring Promoter repository contains design documents (for example docs/kubernetes-executor-design.md) but no ADR directory at the time of writing, so the records below are worked examples for your own repository, not summaries of the project’s internal decisions.

Worked example: ADR-001

# ADR-001: Use Ring Promoter for environment promotion; keep Argo CD for cluster sync

Status: Accepted, 2026-10-05
Deciders: platform team, release management, SRE lead

## Context
- Our estate mixes Kubernetes services and VM services (OpenResty) that are
  deployed by existing GitHub Actions workflows.
- Argo CD already keeps our clusters in sync with Git. It has no promotion
  model: moving a version from acc to prod is a manual PR today.
- Change management requires a maintenance window, a QA Go/No-Go for the exact
  version and an approved Jira change request before production changes.
- Options considered: Argo CD + PRs (status quo), Kargo, Ring Promoter,
  a commercial release platform.
- Kargo requires Argo CD and Kubernetes; it would not cover our VM services.

## Decision
We will use Ring Promoter to promote versions int -> test -> acc -> prod for
all services. Kubernetes services use the kubectl or k8sjob deployer; VM
services use the github deployer pointed at single-environment workflows.
Argo CD continues to own cluster sync for platform components it manages
today. No Deployment will have its image tag owned by both tools.

## Consequences
Positive
- One record of current, previous and historical versions per app and ring.
- Automatic rollback on failed health; gates checked before any deploy.
- VM services keep their workflows; no rewrite.
Negative
- No SSO or per-user RBAC in Ring Promoter. Mitigation: access only through
  our authenticating reverse proxy; API token held in CI secrets only.
- Ring state lives in Postgres, not Git. Postgres becomes part of the release
  path and is backed up accordingly. No drift detection from this tool.
- Smaller ecosystem: deployers are kubectl, Kubernetes Jobs and GitHub Actions.
Revisit when
- Ring Promoter ships SSO/RBAC, or an Argo CD deployer (listed for V2).
- More than half our services move to a GitOps-only model.

Worked example: ADR-002

# ADR-002: Require version-verified health checks on every ring

Status: Accepted, 2026-10-05
Relates to: ADR-001

## Context
- A plain URL health check can pass while the previous version still serves
  traffic: a deploy job can succeed while old pods still answer 200 OK.
- Ring Promoter supports health_version_field (a JSON field, dotted paths
  allowed) or health_version_header on a ring. When set, every post-deploy
  check must report the exact version just deployed, and the source ring is
  verified before promotion.

## Decision
Every service will expose its deployed version (image tag or ref) on its
health endpoint, and every ring will set health_version_field or
health_version_header. New services are not onboarded without it.

## Consequences
Positive
- "Green deploy, old code" fails the check and triggers automatic rollback.
- Promotions only start from a source ring proven to run that version.
Negative
- Each service needs a small code change to report its version.
- Rings that pin a ref (ref: release) record the version the endpoint reports
  instead of verifying a known one; we accept this for release-branch apps.
- During any in-ring canary, the endpoint may be served by either version;
  such rings need their health URL reviewed before enabling verification.

Worked example: ADR-003

# ADR-003: Human gate before production; auto-promote only early rings

Status: Accepted, 2026-10-05
Relates to: ADR-001, ADR-002

## Context
- Auto-promote can chain hops inside one operation and lock, stopping at the
  first ring with the flag off or on any failure.
- Ring Promoter refuses auto_promote: true in config on the ring before prod;
  enabling it via the API requires the production password.
- Auto-promote into a change-request-gated ring fails closed, and into a
  Grafana-gated ring stops at a no-go.

## Decision
- test declares auto_promote: true; acc declares auto_promote: false.
  Both are config-owned so the state is visible in Git and reviewed.
- acc and prod require qa_signoff and a Jira change_request; prod also
  requires an open maintenance window and RP_PROD_PASSWORD.
- Grafana overrides are allowed only with a written override_reason, and
  are reviewed weekly from the job log.

## Consequences
Positive
- Fast feedback through int, test and acc with no clicks.
- Nothing reaches production without a named human, an exact-version GO
  and an approved CR.
Negative
- Production releases wait for a window and a person; we accept the latency.
- Rollbacks are exempt from the password by design; incident response is
  never blocked, so access to the rollback API must itself be controlled.
- The demo CR code "test" is always accepted; we must never rely on CR
  validation alone as a security control.

Decision checklist

Before accepting an ADR in this space, check each item:

• Which question are we answering: sync (“does the cluster match Git?”), build (“did the job pass?”) or promotion (“is this version healthy and allowed next?”)?
• Is any part of our estate outside Kubernetes? If so, which tools in the shortlist can deploy to it?
• Must Git be the only source of truth for cluster state? If so, how will promotion state and Git stay consistent?
• Do we need traffic shifting inside an environment, and which tool provides it?
• Do we need SSO and per-user RBAC now? If the chosen tool lacks it, what is the interim control?
• Can every service report its deployed version on its health endpoint?
• Which rings may auto-promote, and is the hop into production always deliberate?
• Which gates apply to which rings: maintenance window, version-specific sign-off, change request, metrics?
• What does a rollback require, and who can trigger it?
• What is the operational footprint we are willing to run, and who staffs it?
• Have competitor claims been checked against current vendor documentation?
• What specific events will make us revisit this decision?

7. Summary

Argo CD and Flux keep clusters in line with Git. CI produces a version. Ring Promoter, by its own description, decides what earns production: it moves one exact version through int, test, acc and prod, checks each ring is really running it, enforces change windows, sign-offs, Jira CRs and Grafana gates before anything changes, and rolls back by itself when health fails, for Kubernetes and VM apps from one binary. It does not do GitOps, traffic shifting or SSO today, and its ecosystem is smaller. Those trade-offs are acceptable for some teams and not for others. The way to make the call well is to answer the checklist honestly and write the outcome down in an ADR that says when to look again.

Further reading: ringpromoter.com/compare, ringpromoter.com, the Workstation Ring Promoter page, Ring Promoter: Modern CI/CD for AI-Powered Deployments and Ring Promoter v1.0.2: Rings, Orbit and Lanes.