# Deprecations<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

[#_description]
== Description

Deprecated settings still work. Updatecli accepts the old form, logs a warning, and translates it to
the new one, so a manifest keeps running between releases. The warning is the notice: nothing on this
page breaks a pipeline today, and everything on it goes away eventually.

*How long a deprecation lasts.*
link:https://github.com/updatecli/updatecli/blob/main/COMPATIBILITY.md[COMPATIBILITY.md] sets the
rule: an old form is only ever dropped in a major release. No patch or minor release removes
anything on this page, so a manifest that runs today goes on running until the next major ships.
The `Since` column is there to tell you how long a form has been on notice, not to start a clock.

*How each entry behaves.* Not all of them are simple renames, and the exceptions are easy to miss
while skimming. Every entry in <<_deprecations_by_release>> carries one or more of these markers:

* *translated* - Updatecli rewrites the old form to the new one on every run, so the pipeline
behaves as though the manifest had already been migrated.
* *warned* - accepted exactly as written, nothing is rewritten, so migrating is a manual edit.
* *ignored* - the setting has no effect at all beyond the warning. `commitmessage.title` is the only
one, see <<_commit_messages>>.
* *error* - already refused outright under some setting or combination. `query` becomes a hard error
as soon as the engine moves to `dasel/v2` or later, see <<_dasel_engines>>.

[TIP]
====
Three commands answer "does any of this apply to me?":

* `updatecli pipeline diff` parses and validates the whole manifest without applying anything, so
every deprecation warning surfaces.
* `updatecli manifest validate --experimental --strict` reports the deprecated keywords on their own
and fails instead of only warning, which makes it the one to run in CI. It is available from
v0.120.0 and is experimental, so it exits unless `--experimental` is set, see
link:/docs/help/experimental/[Experimental features].
* link:/docs/commands/updatecli_manifest_upgrade/[`updatecli manifest upgrade`] prints the
translated manifest, and writes it back to the file with `-i`. That migrates every *translated*
entry in one pass. It cannot help with the *warned*, *ignored*, and *error* entries, which need a
real edit.
====

[#_deprecations_by_release]
== Deprecations by release

The same entries as the rest of this page, one row per release, newest first. Everything listed
here still works, and goes on working until the next major release (see <<_description>>).

[cols="1,1,4", options="header"]
|===
| Release | Released | Deprecated in this release

| link:/changelogs/updatecli/changelogs/v0.120.0[v0.120.0]
| 2026-08-05
| <<_dasel_engines,`dasel/v1` and `dasel/v2` on `json`, `toml`, `csv`>> (*warned*) +
<<_deprecated_parameters,`query` on `toml` and `csv`>> (*error* from `dasel/v2`)

| link:/changelogs/updatecli/changelogs/v0.116.0[v0.116.0]
| 2026-04-10
| <<_githubpullrequest_automerge,`automerge` on `github/pullrequest`>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.114.0[v0.114.0]
| 2026-02-24
| <<_commands,`updatecli apply`, `updatecli diff`, `updatecli prepare`>> (*translated*) +
<<_commit_messages,`commitmessage.title`>> (*ignored*)

| link:/changelogs/updatecli/changelogs/v0.105.0[v0.105.0]
| 2025-08-01
| <<_dasel_engines,`dasel/v1` on `json`>> (*warned*) +
<<_deprecated_parameters,`query` on `json`>> (*error* from `dasel/v2`)

| link:/changelogs/updatecli/changelogs/v0.97.0[v0.97.0]
| 2025-03-31
| <<_deprecated_parameters,`key: name` and `key: hash` on `githubrelease`>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.86.0[v0.86.0]
| 2024-11-04
| <<_stage_identifiers,`conditionids` on targets>> (*translated*, *error* with `disableconditions`)

| link:/changelogs/updatecli/changelogs/v0.80.0[v0.80.0]
| 2024-07-10
| <<_compose_file_name,`update-compose.yaml`>> (*warned*)

| link:/changelogs/updatecli/changelogs/v0.64.1[v0.64.1]
| 2023-10-19
| <<_top_level_keys,`title` at the top level>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.51.0[v0.51.0]
| 2023-05-26
| <<_yaml_key_syntax,`yaml` keys without the `$.` prefix>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.44.0[v0.44.0]
| 2023-02-09
| <<_deprecated_parameters,`indexurl` on `cargopackage`>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.40.0[v0.40.0]
| 2022-12-12
| <<_top_level_keys,`pullrequests`>> (*translated*, *error* with `actions`) +
<<_top_level_keys,`autodiscovery.pullrequestid`>> (*translated*, *error* with `actionid`) +
<<_action_kinds,`kind: github` and `kind: gitea`>> (*translated*) +
<<_stage_identifiers,`scmID` on actions>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.37.0[v0.37.0]
| 2022-11-07
| <<_deprecated_parameters,`multiple` on `json`, `toml`, `csv`>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.34.0[v0.34.0]
| 2022-09-28
| <<_stage_identifiers,`depends_on`>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.33.0[v0.33.0]
| 2022-09-03
| <<_deprecated_parameters,`url` on `maven`>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.31.0[v0.31.0]
| 2022-08-27
| <<_commands,`updatecli show`>> (*translated*)

| link:/changelogs/updatecli/changelogs/v0.25.0[v0.25.0]
| 2022-05-09
| <<_transformers,camelCase transformer names>> (*translated*, *ignored* when the lowercase form is
set too)

| link:/changelogs/updatecli/changelogs/v0.23.0[v0.23.0]
| 2022-04-06
| <<_stage_identifiers,`scmID` and `sourceID`>> (*translated*)
|===

NOTE: The `updatecli-action` `v1` and `v2` branches are not in the table. They belong to
`updatecli/updatecli-action`, which is versioned separately from Updatecli itself, so no Updatecli
release deprecated them and the policy described above does not apply. See <<_branches_v1_and_v2>>.

[#_commands]
== Commands

The four original top-level commands moved under `pipeline` and `manifest`. All four still run and
log `Deprecated command, please instead use ...`.

[cols="1,1,1", options="header"]
|===
| Deprecated | Use instead | Since

| `updatecli apply`
| `updatecli pipeline apply`
| v0.114.0

| `updatecli diff`
| `updatecli pipeline diff`
| v0.114.0

| `updatecli prepare`
| `updatecli pipeline prepare`
| v0.114.0

| `updatecli show`
| `updatecli manifest show`
| v0.31.0
|===

See the link:/docs/commands/[Commands] reference for the current command tree.

[#_manifest_keys]
== Manifest keys

[#_stage_identifiers]
=== Stage identifiers

Mixed-case and snake_case keys were normalised to lowercase. The old spelling is copied onto the new
key and cleared.

[cols="1,1,2,1", options="header"]
|===
| Deprecated | Use instead | Applies to | Since

| `scmID`
| `scmid`
| sources, conditions, targets
| v0.23.0

| `scmID`
| `scmid`
| actions, which only exist from this release on
| v0.40.0

| `sourceID`
| `sourceid`
| conditions, targets
| v0.23.0

| `depends_on`
| `dependson`
| sources, conditions, targets
| v0.34.0

| `conditionids`
| `dependson`, with each entry prefixed `condition#`
| targets
| v0.86.0
|===

`conditionids` is the one that changes shape rather than spelling. A target listing
`conditionids: [check]` becomes:

[source,yaml]
----
targets:
  default:
    dependson:
      - condition#check
----

Updatecli performs that translation itself and, in doing so, also sets `disableconditions: true` on
the target (the conditions named in `dependson` are the only ones that gate it).

IMPORTANT: Setting the old key *and* the new key together is not a warning. `conditionids` combined
with `dependson` makes Updatecli ignore `conditionids`; `conditionids` combined with
`disableconditions: true` is an outright error, because disabling conditions while naming conditions
is contradictory. The same applies to `scmID` alongside `scmid` on an action.

Resource `kind` values must also be lowercase. A capitalised kind is accepted and lowercased with
`kind value "..." must be lowercase`.

[#_top_level_keys]
=== Top-level keys

[cols="1,1,2,1", options="header"]
|===
| Deprecated | Use instead | Notes | Since

| `pullrequests`
| `actions`
| Mutually exclusive - using both is an error, not a warning
| v0.40.0

| `title`
| `name`
| Names the manifest
| v0.64.1

| `autodiscovery.pullrequestid`
| `autodiscovery.actionid`
| Mutually exclusive - using both is an error
| v0.40.0
|===

[#_action_kinds]
=== Action kinds

Both were renamed when actions grew beyond pull requests.

[cols="1,1,1", options="header"]
|===
| Deprecated | Use instead | Since

| `kind: github`
| `kind: github/pullrequest`
| v0.40.0

| `kind: gitea`
| `kind: gitea/pullrequest`
| v0.40.0
|===

[#_transformers]
== Transformers

Every camelCase transformer was renamed to lowercase, all of them in the same release. The behaviour
is unchanged.

[cols="1,1,1", options="header"]
|===
| Deprecated | Use instead | Since

| `addPrefix`
| `addprefix`
| v0.25.0

| `addSuffix`
| `addsuffix`
| v0.25.0

| `trimPrefix`
| `trimprefix`
| v0.25.0

| `trimSuffix`
| `trimsuffix`
| v0.25.0

| `semverInc`
| `semverinc`
| v0.25.0

| `findSubMatch`
| `findsubmatch`
| v0.25.0

| `findSubMatch.captureIndex`
| `findsubmatch.captureindex`
| v0.25.0
|===

The deprecated spellings are hidden from the JSON schema, so an editor completing from the schema
will only ever offer the lowercase form. See the
link:/docs/core/transformer/["Transformer" page].

[#_actions]
== Actions

[#_githubpullrequest_automerge]
=== `github/pullrequest`: `automerge`

Deprecated in v0.116.0 in favour of `merge.strategy`, which offers three behaviours where
`automerge` had two.

[cols="1,1", options="header"]
|===
| Before | After

a|
[source,yaml]
----
actions:
  default:
    kind: github/pullrequest
    spec:
      automerge: true
----

a|
[source,yaml]
----
actions:
  default:
    kind: github/pullrequest
    spec:
      merge:
        strategy: auto
----
|===

`automerge: false` is not a no-op, it translates to `merge.strategy: manual`:

[cols="1,1,3", options="header"]
|===
| Old value | Translates to | Meaning

| `automerge: true`
| `merge.strategy: auto`
| Hand the pull request to GitHub's auto-merge, which merges it once the required checks pass.

| `automerge: false`
| `merge.strategy: manual`
| Leave the pull request open for a human. This is also the default when `merge` is unset.

| - (no equivalent)
| `merge.strategy: client`
| Updatecli merges the pull request itself, after `merge.after` has elapsed (`24h` by default).
|===

`client` has no `automerge` equivalent, so it is only reachable after migrating. See the
link:/docs/plugins/actions/github/["GitHub Pull Request" page].

[#_resource_plugins]
== Resource plugins

[#_dasel_engines]
=== Dasel engines

`json`, `toml`, and `csv` read and write through Dasel, selected by the `engine` parameter.
`dasel/v3` arrives in v0.120.0 and, from that release, both `dasel/v1` and `dasel/v2` are deprecated
in favour of it:

[source,text]
----
Engine "dasel/v1" is deprecated and will be removed in a future updatecli version. Please use "dasel/v3" instead.
----

The history differs per plugin. `json` has warned about `dasel/v1` since v0.105.0, where the warning
pointed at `dasel/v2` instead. `toml` and `csv` had no `engine` parameter at all before v0.120.0, so
that release is where their first warning appears.

[cols="1,1,1", options="header"]
|===
| Plugin | Deprecated engines | Since

| `json`
| `dasel/v1`
| v0.105.0 (retargeted at `dasel/v3` in v0.120.0)

| `json`
| `dasel/v2`
| v0.120.0

| `toml`, `csv`
| `dasel/v1`, `dasel/v2`
| v0.120.0
|===

[WARNING]
====
`dasel/v1` is still the **default**. A `json`, `toml`, or `csv` resource that never mentions `engine`
runs on the deprecated engine and emits that warning on every run. Set the engine explicitly to
silence it:

[source,yaml]
----
sources:
  default:
    kind: json
    spec:
      engine: dasel/v3
      file: package.json
      key: version
----

`engine: dasel` is an alias that always resolves to the newest engine, currently `dasel/v3`. It is
not deprecated, but it does mean the behaviour of your manifest changes when a new engine lands.
====

Migrating the engine forces a second change. Under `dasel/v2` and `dasel/v3`, `query` is rejected
rather than warned about:

[source,text]
----
engine "dasel/v3" requires the parameter "key" over "query"
----

So rename `query` to `key` in the same edit.

Setting `engine: dasel/v3` is not a flag flip either. The Dasel v3 selector syntax is richer than the
v1 and v2 one, and it is not backward compatible with it, so the keys themselves have to be rewritten.
The leading dot is the usual casualty, `.version` is a parse error under `dasel/v3`:

[cols="1,1", options="header"]
|===
| Before | After

a|
[source,yaml]
----
sources:
  default:
    kind: json
    spec:
      file: package.json
      key: .version
----

a|
[source,yaml]
----
sources:
  default:
    kind: json
    spec:
      engine: dasel/v3
      file: package.json
      key: version
----
|===

The link:/docs/plugins/resource/json/["JSON" page] compares the selectors engine by engine, and the
link:https://daseldocs.tomwright.me/[Dasel documentation] covers the v3 syntax in full.

[#_deprecated_parameters]
=== Deprecated parameters

[cols="1,1,1,2,1", options="header"]
|===
| Plugin | Deprecated | Use instead | Notes | Since

| `json`
| `query`
| `key`
| Accepted under `dasel/v1`, hard error under `dasel/v2` and `dasel/v3`
| v0.105.0

| `toml`, `csv`
| `query`
| `key`
| Same rule, these plugins only gained `engine` in v0.120.0
| v0.120.0

| `json`, `toml`, `csv`
| `multiple`
| `query`
| `key` + `multiple` is rewritten to `query`
| v0.37.0

| `maven`
| `url`
| `repository`
| Prefix the old URL onto the repository name
| v0.33.0

| `cargopackage`
| `indexurl`
| `registry.url`
| Copied across automatically
| v0.44.0

| `githubrelease`
| `key: name`
| `key: tagname`
|
| v0.97.0

| `githubrelease`
| `key: hash`
| `key: taghash`
|
| v0.97.0
|===

[#_commit_messages]
== Commit messages

[WARNING]
====
`commitmessage.title` is **ignored**, not renamed (deprecated in v0.114.0). The commit title is now
always generated from the target `name` (or its `description`), so a manifest that sets it sees no
effect at all beyond the warning:

[source,text]
----
commitMessage.title is deprecated and will be ignored. The commit title is now always generated from the target name or description.
----

To control the commit title, rename the target. Everything else under `commitmessage` (`type`,
`scope`, `body`, `footers`, `hidecredit`) still applies.
====

[#_yaml_key_syntax]
== YAML key syntax

[WARNING]
====
`yaml` keys are expected to be JSONPath expressions beginning with `$.`. A key written in the older
dotted form is rewritten automatically and warned about, since v0.51.0:

[source,text]
----
current yaml key is "spec.version" and should be updated to "$.spec.version"
----

The rewrite is **scheduled to become an error** in a future major release. Update the keys now:

[cols="1,1", options="header"]
|===
| Deprecated | Use instead

| `key: spec.version`
| `key: $.spec.version`

| `key: metadata.annotations.example\.com/version`
| `key: $.metadata.annotations.'example.com/version'`
|===

This applies to `key` and to every entry in `keys`, on sources, conditions, and targets alike.
====

[#_compose_file_name]
== Compose file name

The default compose file was renamed from `update-compose.yaml` to `updatecli-compose.yaml` in
v0.80.0. The old name is still picked up, with a warning:

[source,text]
----
Deprecated default compose file "update-compose.yaml" detected. Please rename it to "updatecli-compose.yaml"
----

If both files exist, Updatecli uses the deprecated one and says so:

[source,text]
----
Both default compose files "update-compose.yaml" and "updatecli-compose.yaml" detected. Please remove "update-compose.yaml" to start using "updatecli-compose.yaml"
----

Renaming the file is the whole migration. See the link:/docs/core/compose/["Compose" page].

[#_updatecli_action]
== updatecli-action

[#_branches_v1_and_v2]
=== Branches `v1` and `v2`

The `v1` and `v2` branches of `updatecli/updatecli-action` are deprecated. Pin a released version
instead, or track `main` if you deliberately want the branch tip.

These branches belong to the action's own repository, which is versioned separately from Updatecli,
so this deprecation is not tied to any Updatecli release and is absent from
<<_deprecations_by_release>>.

[#_go_further]
== Go Further

* link:/changelogs/updatecli[Changelogs] - what shipped in each release.
* link:/docs/help/troubleshooting/[Troubleshooting] - error messages and what causes them.
* link:/docs/commands/[Commands] - the current command reference.