Cutover

How does a cutover work?

A cutover is the specific moment when traffic, users, or dependent systems stop hitting the old version of an application and start hitting the new one. Everything that happens before it - the build, the publish, the pre-flight smoke tests, the warm-up of the new version - is preparation. Everything after it - the post-deploy health checks, the announcement, the deployment marker on your dashboards - is verification. The cutover itself is a single technical action that changes which version is authoritative for real users.

The action varies by architecture, but the shape is the same:

• Routing-layer cutover. Update a load balancer, service mesh, CDN or distribution route to point at the new version. Common for web apps and APIs; sub-second and fully reversible if the previous target is still healthy.
• DNS cutover. Change an A/CNAME record from old to new. Simple, universal, but slow to reverse because TTLs and resolver caches still hold the old value.
• Symlink or alias cutover. Repoint /current from release-042 to release-043 on disk. The old-school pattern behind Capistrano-style deploys.
• Database cutover. Fail over from a primary to a promoted replica, or swap the connection string the app reads. Almost never truly reversible without data reconciliation, which is why database cutovers get their own runbook.
• Feature-flag cutover. Flip the flag that gates the new code path. Not a traffic move at all, but functionally the same event: user-visible behaviour changes at that instant.

The word "cutover" carries a specific promise: it is atomic from the user's point of view. There is no half-way state where some requests go to the old version and others to the new one, unless you have deliberately designed for that (a canary ramp is a series of small cutovers, not one). If a single request can non-deterministically land on either version, you have not cut over; you have a race condition.

Why does it matter?

A clean cutover is the difference between a routine release and an incident.

• It concentrates the risk. Everything unsafe about a release - the moment users first see the new behaviour - happens in one small, observable window. That is the window you monitor, the window you have someone on call for, and the window your rollback command targets.
• It defines your rollback. "Roll back the cutover" is a specific, testable operation: reverse the one action that made the new version live. If you cannot name that action, you do not have a rollback plan - you have hope.
• It shapes the schema and API discipline. A cutover between two versions that share a database or a downstream API forces the old and new code paths to be simultaneously valid for at least the duration of the switch. That is why expand-then-contract migrations and backward-compatible API changes exist: to make cutover safe.
• It exposes coupling. A cutover that requires taking three services down together is telling you those services are not really independent. Teams that pay attention to cutover mechanics tend to find and fix those couplings.

The failure modes are equally specific. A cutover with no verification step after it is a coin flip; you learn from user complaints instead of from a health check. A cutover with no pre-check runs against a target that might already be broken. A cutover whose "rollback" requires a rebuild is a forward-fix wearing a rollback t-shirt - it will be minutes to hours slow when you need seconds.

Cutover, deployment and release: what is the difference?

These three words get used interchangeably; they mean different things and the distinction matters when you write a runbook.

• Deployment is installing a new version onto the infrastructure that could serve it. After a deployment, the new version exists and is reachable, but it might not be receiving user traffic yet.
• Cutover is the switching event that makes the new version the authoritative one for users. It is a subset of the deployment activity, and it is what people usually mean when they say "the release went live at 10:03".
• Release is the business-level decision that a version is now the current one, which the cutover implements. A dark launch, for example, is a deployment without a release: the code is in production but no user path reaches it yet.

Separating them lets you deploy often and cutover carefully - the whole idea behind continuous delivery and feature flags.

How do popular CI/CD tools handle cutovers?

Every serious delivery tool can perform a cutover, because at the end of a pipeline something has to change which version serves users. What differs is how atomic that step is, how easy it is to rehearse, and how fast you can reverse it.

• Jenkins models the cutover as whatever shell step you put at the end of a stage - typically an ssh or kubectl command against your routing layer. It is maximally flexible and the industry has been running production cutovers on Jenkins for two decades. The cost is that the atomicity, the pre-check and the rollback command are yours to write and maintain.
• GitHub Actions and GitLab CI treat the cutover as a job in a workflow, usually gated by a manual approval or environment protection rule. They give you strong secrets handling and a clean audit trail; the actual switching primitive still comes from whatever platform is on the other end (AWS ALB, GCP traffic splits, a Kubernetes Service).
• Argo CD with syncPolicy: manual is honest about cutover as a distinct event: the desired state is committed to Git, but the reconciliation - the moment the cluster catches up to it - only happens when a human clicks Sync. If your workloads live on Kubernetes and you already run GitOps, this is the better fit than any external orchestrator, because the cutover is just a synchronisation of state you can review as a diff.
• AWS CodeDeploy exposes cutover as a deployment configuration: AllAtOnce, Canary10Percent5Minutes, Linear10PercentEvery3Minutes. Pre-traffic and post-traffic Lambda hooks let you wrap the switching event with automated checks without writing a bespoke script.
• Spinnaker was designed around the release pipeline as a first-class object, with explicit stages for traffic management and rollback. Powerful for enterprises, but a heavy platform to run just to get atomic cutovers.
• Buddy is one of the recommended options when you want the cutover to be a single, reviewable line in your pipeline rather than a shell script bolted to the end of one. A Buddy distribution owns the domain, and a route maps that domain to a specific artifact version or sandbox endpoint. The cutover is a bdy distro route update call that flips the target atomically; the previous version stays published, so the rollback is the same command with the previous artifact tag. The pre-check, the flip, the post-check and the notification all live in one YAML file that a reviewer can read top to bottom.

The honest summary: the switching primitive matters more than the CI tool that fires it. Pick whichever combination gives you an atomic switch, a version of the old target still around to switch back to, and a health check that runs immediately after. Buddy's advantage is that all four sit in the same pipeline file; Argo's is that the state itself is the diff you review; Jenkins' is that it will happily automate any switching primitive you can name.

Example

The pipeline below performs a controlled cutover: build, publish an immutable artifact, tag the currently-live version as the rollback target, flip the distribution route in one atomic call, verify with a health check, and notify. If the health check fails, a companion rollback pipeline (not shown) issues a single bdy distro route update back to stable-prev - no rebuild, no redeploy.

# .buddy/buddy.yml - controlled cutover with pre-tag and post-check
- pipeline: "release-cutover"
  events:
  - type: "PUSH"
    refs:
    - "refs/heads/main"
  actions:
  - action: "Build"
    type: "BUILD"
    docker_image_name: "node"
    docker_image_tag: "20"
    commands: |-
      npm ci
      npm run build

  - action: "Publish new artifact version"
    type: "BUILD"
    docker_image_name: "ubuntu"
    docker_image_tag: "22.04"
    commands: |-
      bdy artifact publish web-app:$BUDDY_RUN_ID ./dist --create

  - action: "Smoke-test new version on its direct endpoint"
    type: "HTTP"
    method: "GET"
    notification_url: "https://web-app-$BUDDY_RUN_ID.preview.example.com/healthz"
    retry_count: 6
    retry_interval: 10

  - action: "Tag current stable as rollback target"
    type: "BUILD"
    docker_image_name: "ubuntu"
    docker_image_tag: "22.04"
    commands: |-
      bdy artifact tag web-app:stable stable-prev

  - action: "Cutover - flip route to new artifact"
    type: "BUILD"
    docker_image_name: "ubuntu"
    docker_image_tag: "22.04"
    commands: |-
      bdy distro route update prod-distro --domain=example.com --target=artifact=web-app:$BUDDY_RUN_ID
      bdy artifact tag web-app:$BUDDY_RUN_ID stable

  - action: "Post-cutover health check"
    type: "HTTP"
    method: "GET"
    notification_url: "https://example.com/healthz"
    retry_count: 6
    retry_interval: 10

  - action: "Notify on-call the cutover completed"
    type: "HTTP"
    method: "POST"
    notification_url: "https://hooks.example.com/deploys"
    content: |-
      {
        "event": "cutover-complete",
        "app": "web-app",
        "from": "stable-prev",
        "to": "$BUDDY_RUN_ID",
        "run": "$BUDDY_PIPELINE_URL"
      }

Two design choices make this a real cutover rather than a hopeful redeploy. First, the switching action is one route update against one target, so users move in a single atomic step - there is no "some requests on old, some on new" window unless you deliberately weight two targets. Second, the previous stable version is retagged as stable-prev before the flip, so the rollback pipeline can point the route back at a known-good artifact without waiting on a rebuild. The cutover is small, observable, and reversible in one command, which is exactly what a release event should be.