Make a change

Goal

For feature teams. In this task you run joomiz apply to make the changes that a plan showed. You also learn what to do when an apply is refused or does not finish.

Before you start

Run joomiz plan for the environment, and read the plan. Preview a change explains how.
Keep the file as it is. apply needs the same file that you planned. A change of one character, even in a comment, makes it a different file.
Sign in, and set JOOMIZ_SERVER_URL.

Steps

Apply the plan

joomiz apply --environment test

The output has the same shape as the plan. The text on each resource line comes from the provisioner. A successful apply ends with apply succeeded. Deploy your first service shows a full apply.

Apply from a pipeline

A pipeline runs the same two commands, plan and then apply, with the same file. It needs a token. Set the variable JOOMIZ_TOKEN from the secret store of your pipeline. Do not write the token in the file of the pipeline.

A pipeline can read the exit code of each command. The CLI reference lists the codes. Add --strict to plan when the pipeline must stop on an incomplete drift check.

Apply one at a time

Only one apply can be active for an application and an environment. If you start a second one, the control plane refuses it at once. The message names the run that holds the lock:

error: the control plane could not apply joomiz.yaml (HTTP 409)
  Apply already in progress
  another apply is in progress for this application and environment: run 53adae2d-e706-499a-b9f3-048c561ded9c, started at 2026-10-28T16:20:32.533Z, status running
  hint: another apply of this application and environment is running. Follow it with `joomiz runs watch 53adae2d-e706-499a-b9f3-048c561ded9c`, and apply again when it has ended.
  If that apply is stuck, an operator can release the lock with `joomiz runs abandon 53adae2d-e706-499a-b9f3-048c561ded9c`. That does not stop work in progress.

Follow the other run with joomiz runs watch, and apply again when it has ended. Read your runs explains runs watch. A plan is not blocked while an apply runs.

Apply a plan that is out of date

A plan describes the changes that are needed at the moment of the plan. If another apply changed the environment after your plan, your plan is out of date. apply refuses it. The control plane calls this a stale plan. The CLI prints the word Stale plan.

error: the control plane could not apply joomiz.yaml (HTTP 409)
  Stale plan
  the applied state of this application and environment changed after this plan was made; plan again, review the result and apply it
  hint: the applied state of this application and environment changed after this plan was made. Run `joomiz plan -f joomiz.yaml --environment test` again, review the result, and apply the file again.

Plan again, read the result, and apply the file again:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  deployment/cloud-foundry-app: succeeded — Planned 1 change for deployment/cloud-foundry-app.
    shop-test-worker (updated): succeeded — Would update 'shop-test-worker' (deployment/cloud-foundry-app) in environment 'test'. Nothing was changed.
  1 resource type, 1 resource
plan succeeded (revision 617bbfe4-b8ad-4bfd-86c9-21110d946b5d, plan 78cb3cda-8c66-4bd3-8eac-bf07f38ee159)

Apply a file that you did not plan

apply refuses a file that was never planned for the environment. The message says No appliable plan. Deploy your first service shows it. Run plan with the same file, then apply.

Handle an apply that does not finish

An apply can end with some resources changed and some not. The run then has the status partially_applied. This apply ran while the provisioner of the database was not reachable:

error: the control plane could not fully apply joomiz.yaml to environment test (via https://joomiz.example.com/apply?environment=test)
  managed-resource/postgres: failed — the provisioner refused the connection
    shop-db (updated): failed — the provisioner reported no result for this resource
  consumed-resource/kafka-topic: succeeded — Applied 1 change for consumed-resource/kafka-topic.
    shop-events (updated): succeeded — Updated 'shop-events' (consumed-resource/kafka-topic) in environment 'test'. Nothing real was changed — this is a stub.
  some changes were applied and some were not; the environment is part-way through this plan. Fix what failed above and run apply again — it is safe to repeat while nobody else applies to this environment in between. If someone does, apply refuses this plan as stale, and you plan again.
apply partially_applied (plan 2a969cca-053d-4b0b-bf66-1763d82782be, apply 82da7088-db05-4b91-9a23-cc64bcce1caa)

The text says what to do. Fix what failed, and run apply again. It is safe to repeat while nobody else applies to the environment. The repeat applies the changes of the same plan again:

applied joomiz.yaml to environment test (via https://joomiz.example.com/apply?environment=test)
  managed-resource/postgres: succeeded — Applied 1 change for managed-resource/postgres.
    shop-db (updated): succeeded — Updated 'shop-db' (managed-resource/postgres) in environment 'test'. Nothing real was changed — this is a stub.
      outputs.password: https://vault.example.com/secrets/quick-start-shop-db-password
  consumed-resource/kafka-topic: succeeded — Applied 1 change for consumed-resource/kafka-topic.
    shop-events (updated): succeeded — Updated 'shop-events' (consumed-resource/kafka-topic) in environment 'test'. Nothing real was changed — this is a stub.
  2 resource types, 2 resources
apply succeeded (plan 2a969cca-053d-4b0b-bf66-1763d82782be, apply 30c61990-bfcd-481f-a167-c112d518ffaa)

joomiz runs show lists the result of each type of resource for the run. Read your runs shows it.

Release a stuck apply lock

If an apply never ends, it keeps the lock, and no other apply can start. A person with the role operator can release the lock with joomiz runs abandon <id>. Replace <id> with the ID of the run that holds the lock. The message of a refused apply names it.

Without the role, the command is refused:

error: the control plane refused the request (HTTP 403)
  Operator role required
  This operation requires the operator role. Releasing an apply lock is a platform operation, not an application-owner one.

With the role, the command releases the lock:

run c22f80b8-767f-485a-b4a4-8c082fd484cb is now abandoned: the apply lock of its application and environment is released.
This does not stop work that is still in progress. A provisioner may still be changing resources; check them before the next apply.

Releasing the lock does not stop work that is already running. A provisioner may still be changing resources. Check the resources before the next apply. The status of the run is abandoned:

run c22f80b8-767f-485a-b4a4-8c082fd484cb
  kind:         apply
  application:  reference-shop (48908c60-5a6c-45fe-b5e4-88357f8e78c4)
  environment:  test
  caller:       owner:finance-team
  status:       abandoned
  started:      2026-10-28T16:21:10.165Z
  finished:     2026-10-28T16:21:15.251Z
  ended:        abandoned by an operator
  duration:     5.0s
  revision:     e8d56c12-0d39-441f-9f35-f44f269ee4fc
  plan:         524efc69-3a2b-44fb-8507-eaef022bd450
groups:
  consumed-resource/kafka-topic  unknown  (the control plane stopped before this group finished)
This run was abandoned. Some changes may have been made. Run "joomiz apply" again to find out; applying twice is safe. If another apply changed this environment since, apply refuses the plan as stale; plan again first.

The line caller: says which role started the run. This guide says acted as. The line ended: says who released the lock. The word unknown in a line under groups: means that the control plane stopped waiting for that type of resource before it finished. A type that waits for its provisioner is different. It keeps the state accepted after the release, until the provisioner answers.

Check

After an apply, run joomiz plan --environment test with the same file. A plan with 0 resource types, 0 resources means that the environment matches your file.

Troubleshooting

Symptom	Cause	Fix
`HTTP 409` and `Apply already in progress`	Another apply holds the lock.	Follow the run named in the message. Apply again after it ends.
`HTTP 409` and `Stale plan`	The environment changed after your plan.	Plan again, then apply.
`HTTP 409` and `No appliable plan`	The file was never planned, or it changed after the plan.	Plan the file, then apply the same file.
`apply partially_applied`	Some resources changed and some did not.	Fix the failure that the output names. Run `apply` again.
`HTTP 403` and `Operator role required`	Only an operator can release a lock.	Ask a person with the role `operator`.
`Apply <id> may still be running or may have finished` and exit code `3`	The CLI stopped waiting, for example because the connection broke. The apply goes on at the control plane.	Follow it with `joomiz runs watch <id>`, using the ID in the message. Applying twice is safe.
`not applied yet` and `apply failed`	The provisioner accepted the changes and is still making them. The run is waiting for provisioner. The CLI prints `accepted`.	Find the run with `joomiz runs`. Follow it with `joomiz runs watch <id>`.

Look at what happened in Read your runs.