consul kv put: Write Config to Consul KV in CI
consul kv put stores a value at a key in the Consul key/value store, optionally guarded by a check-and-set index.
Pipelines use Consul KV to publish config and feature flags. kv put is the write side; the -cas flag makes writes safe under concurrency.
What it does
consul kv put writes a value to a key, creating the key if it does not exist. The value can be a literal, read from a file with @file, or from stdin with -. With -cas plus -modify-index the write only succeeds if the key is unchanged since that index.
Common usage
consul kv put config/app/log_level debug
consul kv put config/app/settings @settings.json
echo "value" | consul kv put config/app/key -
# atomic update guarded by the current ModifyIndex
consul kv put -cas -modify-index=42 config/app/key newvalueOptions
| Flag | What it does |
|---|---|
| -cas | Only write if -modify-index matches the current index |
| -modify-index <n> | Expected ModifyIndex for a -cas write |
| -flags <n> | Unsigned 64-bit metadata flags on the key |
| -acquire / -release | Acquire or release a lock with -session |
| -session <id> | Session used with -acquire/-release |
In CI
Pass the value as @file.json to publish a whole config blob, and use -cas for any key two jobs might update so a concurrent run cannot clobber a write. A -cas write that fails returns a non-zero exit you can retry.
Common errors in CI
"Error! Did not write to <key>: CAS failed" means another writer changed the key since your -modify-index; re-read with kv get -detailed and retry. "Unexpected response code: 403 (Permission denied)" means the token lacks key:write on that prefix. "Error! Missing KEY argument" means you passed the value but forgot the key path.