Updatecli
Docs

Cargo Package

sourceconditiontarget

✔

✔

✗

Description

The cargopackage resource queries a cargo registry (crates.io by default) for the versions of a crate.

source

Returns the version matching versionfilter.

condition

Checks that version is published for the crate.

target

Not supported - a target fails with Target not supported for the plugin Cargo Package. To bump a dependency in a file, use the "TOML" resource against Cargo.toml, or the cargo autodiscovery crawler.

Parameters

NameTypeDescriptionRequired
packagestring

“package” defines the name of the Cargo package.

compatible:

  • source
  • condition

remark:

  • it is required.

example:

  • package: serde
registryobject

“registry” defines the Cargo registry to query.

compatible:

  • source
  • condition

default: the crates.io API, https://crates.io/api/v1/crates

remark:

  • in a condition with an scm, the scm directory is used as the registry root directory and “registry.url” and “registry.rootdir” are ignored.
    authobject“auth” defines the credentials used to authenticate with the cargo registry.
    rootdirstring

“rootdir” defines the local directory of a cargo registry index, used instead of the registry API.

remark:

  • “url”, “rootdir” and “scmid” are mutually exclusive.
    scmidstring

“scmid” defines the scm holding the cargo registry index, used instead of the registry API.

remark:

  • only used by the cargo autodiscovery.
  • “url”, “rootdir” and “scmid” are mutually exclusive.
    urlstring

“url” defines the URL of the cargo registry API.

default: https://crates.io/api/v1/crates, when neither “rootdir” nor a scm is set.

remark:

  • “url”, “rootdir” and “scmid” are mutually exclusive.
versionstring

“version” defines the package version to check.

compatible:

  • condition

default: the output of the associated source.

example:

  • version: 1.0.0
versionfilterobject

“versionfilter” defines the version pattern and its kind, such as regex, semver or latest.

compatible:

  • source

default: kind: latest

remark:

  • yanked versions are ignored.
    kindstring

“kind” defines the versioning scheme used to select a version.

default: latest

remark:

  • accepted values are “latest”, “semver”, “regex”, “regex/semver”, “time”, “regex/time”, “lex” and “pep440”.
  • “latest” returns the last version of the list.
  • “lex” sorts the versions lexicographically and returns the last one.
  • “pep440” follows https://peps.python.org/pep-0440/

example:

  • kind: semver
    patternstring

“pattern” defines the version pattern, according to “kind”.

default:

  • latest: “latest”
  • semver and pep440: “*”
  • regex: “.*”
  • time and regex/time: “2006-01-02”

remark:

  • for “latest”, “latest” returns the last version, any other value must match a version exactly.
  • for “semver” and “regex/semver”, it is a semantic versioning constraint.
  • for “pep440”, it is a pep440 version specifier.
  • for “regex”, it is a regular expression.
  • for “time” and “regex/time”, it is a Go date layout.
  • ignored by “lex”.

example:

  • pattern: ~1.2
  • pattern: “>=1.0.0 <2.0.0”
  • pattern: ^v\d+.\d+.\d+$
    regexstring

“regex” defines the regular expression extracting the version from each entry.

remark:

  • only used by the kinds “regex/semver” and “regex/time”.
  • the value of the first capture group is used as the version.

example:

  • regex: ^v(\d+.\d+.\d+)$
    replaceallobject

“replaceall” applies a regular expression replacement to each version before filtering.

remark:

  • only used by the kinds “regex”, “regex/semver” and “regex/time”.
  • the replacement runs before “pattern” or “regex” is evaluated.

example:

replaceall:
  pattern: "_"
  replacement: "."

turns “curl-8_15_0” into “curl-8.15.0”.

    strictboolean

“strict” enforces strict semantic versioning rules when parsing versions.

default: false

remark:

  • only used by the kinds “semver” and “regex/semver”.

package is mandatory. version is condition-only (the version whose existence is being checked).

Note
indexurl is deprecated and hidden from the table above. Use registry.url.

Registry

registry describes where to look, and its three location fields are mutually exclusive, setting more than one is rejected before the run, naming the field that would be overridden:

FieldMeaning

url

A registry HTTP index. Unset means crates.io.

rootdir

A local directory holding a filesystem index, instead of an HTTP one.

scmid

The id of an scm whose clone holds the index. Overrides rootdir and url.

registry.auth carries the credentials for a private registry:

spec:
  package: serde
  registry:
    url: https://cargo.acme.example.com
    auth:
      token: '{{ requiredEnv "CARGO_TOKEN" }}'

Example

# updatecli.yaml
name: Retrieve the latest Cargo Package Version

scms:
  private-registry:
    kind: git
    spec:
      url: "https://github.com/updatecli-test/fake-cargo-registry.git"
      branch: "main"

sources:
  rand:
    name: Get latest rand version from public cargo registry
    kind: cargopackage
    spec:
      package: rand
  test-crate-2:
    name: Get latest test-crate-2 version from private cargo registry
    kind: cargopackage
    scmid: private-registry
    spec:
      package: test-crate-2
      versionfilter:
        kind: semver
        pattern: ~0

conditions:
  existing-package-private-reg:
    name: Test if test-crate-2 0.1.0 exists on private registry
    kind: cargopackage
    disablesourceinput: true
    scmid: private-registry
    spec:
      package: test-crate-2
      version: 0.1.0
  existing-package-not-existing-version-private-reg:
    name: Test if test-crate-2 0.6.0 does not exists on private registry
    kind: cargopackage
    disablesourceinput: true
    scmid: private-registry
    failwhen: true
    spec:
      package: test-crate-2
      version: 0.6.0
  non-existing-package-private-reg:
    name: Test if non-existing-test-crate 0.1.0 does not exists on private registry
    kind: cargopackage
    disablesourceinput: true
    scmid: private-registry
    failwhen: true
    spec:
      package: non-existing-test-crate
      version: 0.1.0
  existing-package-public-reg:
    name: Test if rand version exists on public reg
    kind: cargopackage
    disablesourceinput: true
    spec:
      package: rand
      version: 0.7.2
  existing-package-p-not-existing-version-public-reg:
    name: Test if rand version 99.99.99 does not exists on public reg
    kind: cargopackage
    disablesourceinput: true
    failwhen: true
    spec:
      package: rand
      version: 99.99.99
  non-existing-package-public-reg:
    name: Test if non-existing-package-to-be-sure-123456 does exists on public reg
    kind: cargopackage
    disablesourceinput: true
    failwhen: true
    spec:
      package: non-existing-package-to-be-sure-123456
      version: 0.7.2

targets:
  # Targets are not supported

Links

Last updated on August 2, 2026
Prev
Dashboards
Next
Target