Updatecli
Docs

Maven

Description

The Maven crawler looks recursively for all pom.xml files from a specific root directory, and tries to update the dependencies declared in each one.

Two things are updated per POM:

  • every entry under <dependencies>

  • the <parent> POM, when one is declared

This crawler is enabled by default, so it can be used either automatically by running updatecli diff from a directory containing the files to update, or by providing a manifest. The automatic discovery behavior can be tuned by providing a YAML manifest with a maven crawler in top-level directive autodiscovery as explained in the "Autodiscovery" page.

Generated manifests

Each dependency produces a maven source resolving the latest version, two xml conditions asserting that the groupId and artifactId still match, and an xml target writing the new version into the POM.

Repositories, mirrors, and credentials

The repository used to look up a dependency is taken from the <repositories> declared in the POM, falling back to Maven Central.

Updatecli also reads settings.xml, looked up in this order:

  1. settings.xml next to the POM

  2. $HOME/.m2/settings.xml

From it, Updatecli applies:

  • mirrors - a repository whose id or URL matches a <mirrorOf> rule is replaced by the mirror, including the central shorthand,

  • server credentials - the <username> and <password> of the <server> whose id matches the repository.

The MAVEN_MIRROR_URL environment variable is honoured, and ${env.VARIABLE} expressions inside settings.xml are interpolated.

Version filtering

Unlike most crawlers, the version filter defaults to kind latest, because Maven coordinates do not reliably follow semantic versioning. Set an explicit versionfilter to constrain updates.

More details on the "Version Filtering" page.

Limitations

  • A dependency whose <version> is a property reference, such as ${junit.version}, is skipped. Updatecli does not resolve the property to find the literal it should rewrite.

  • Only files named exactly pom.xml are scanned.

Manifest

Parameters

NameTypeDescriptionRequired
ignorearray

“ignore” defines rules to exclude matching Maven dependencies from the autodiscovery.

remark:

  • a Maven dependency is ignored when it matches at least one rule.
    artifactidsobject

“artifactids” defines the Maven artifacts to match, keyed by artifact ID.

remark:

  • an empty value matches any version.
  • otherwise the value is a semantic version constraint, such as “>=1.0.0”.
  • when the version or the constraint cannot be parsed, the value must equal the version.
    groupidsarray

“groupids” defines the Maven group IDs to match.

remark:

  • a dependency matches when its group ID equals one of the values.
    pathstring

“path” defines a pom.xml path pattern.

remark:

  • the pattern must match the whole path, not just a substring.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
onlyarray

“only” defines rules to restrict the autodiscovery to matching Maven dependencies.

remark:

  • a Maven dependency is kept only when it matches at least one rule.
    artifactidsobject

“artifactids” defines the Maven artifacts to match, keyed by artifact ID.

remark:

  • an empty value matches any version.
  • otherwise the value is a semantic version constraint, such as “>=1.0.0”.
  • when the version or the constraint cannot be parsed, the value must equal the version.
    groupidsarray

“groupids” defines the Maven group IDs to match.

remark:

  • a dependency matches when its group ID equals one of the values.
    pathstring

“path” defines a pom.xml path pattern.

remark:

  • the pattern must match the whole path, not just a substring.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
rootdirstring

“rootdir” defines the directory where the crawler starts searching for pom.xml files.

default: the scm directory when “scmid” is set, otherwise the directory relative paths resolve from, by default the working directory.

remark:

  • a relative path is resolved from the default directory.
  • an absolute path is used as is, instead of the scm directory.
versionfilterobject

“versionfilter” defines the version filter used by the generated manifests.

default: kind “latest”, the latest version.

remark:

  • with kind “semver”, “pattern” accepts:
    • “prerelease”: the latest prerelease of the current version.
    • “patch”: patch updates only.
    • “minor”: patch and minor updates.
    • “minoronly”: minor updates only.
    • “major”: patch, minor and major updates.
    • “majoronly”: major updates only.
    • a version constraint, such as “>= 1.0.0”.
  • with kind “regex”, “pattern” accepts a regular expression.
  • more examples at https://www.updatecli.io/docs/core/versionfilter/

example:

versionfilter:
  kind: semver
  pattern: minor
    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”.

        patternstring

“pattern” defines the regular expression matching the text to replace.

example:

  • pattern: “_”
        replacementstring

“replacement” defines the text replacing each match of “pattern”.

remark:

  • capture groups can be referenced with $1, $2, and so on.

example:

  • replacement: “.”
    strictboolean

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

default: false

remark:

  • only used by the kinds “semver” and “regex/semver”.
⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli

Example

# updatecli.d/default.yaml
name: "Maven autodiscovery using git scm"
scms:
  default:
    kind: git 
    spec:
      url: https://github.com/olblak/jenkins-datadog-plugin.git
      branch: master
    
autodiscovery:
  # scmid is applied to all crawlers
  scmid: default
  crawlers:
    maven:
      # To ignore specific path
      #ignore:
      #  - path: <filepath relative to scm repository>
      #only:
      #  - path: <filepath relative to scm repository>
Last updated on September 26, 2026
Prev
Kubernetes
Next
Nomad