Updatecli
Docs

Golang module

sourceconditiontarget

✔

✔

✗

Description

The golang/module resource queries a Go module proxy for the published versions of a module.

source

Returns the version matching versionfilter.

condition

Checks that version is published for the module.

target

Not supported - a target fails with Target not supported for the plugin GO module. To write the version into a go.mod, use golang/gomod.

Parameters

NameTypeDescriptionRequired
ageobject

“age” defines the minimum or maximum age of a release to be considered valid.

compatible:

  • source
  • condition

remark:

  • in a source, when every published version is discarded by the age filter, the source is skipped.

example:

  age:
    minimum: 7d
    maximumstring

“maximum” defines the maximum age a release may have to be considered.

remark:

  • accepted units are “d” for days, “w” for weeks, “mo” for months and “y” for years, plus the Go duration units such as “h”, “m” and “s”.
  • a unit is required.
  • a month counts as 1/12 of a year and a year as 365 days.

example:

  • maximum: 6mo
  • maximum: 1y
    minimumstring

“minimum” defines the minimum age a release must have to be considered.

remark:

  • accepted units are “d” for days, “w” for weeks, “mo” for months and “y” for years, plus the Go duration units such as “h”, “m” and “s”.
  • a unit is required.
  • a month counts as 1/12 of a year and a year as 365 days.

example:

  • minimum: 24h
  • minimum: 7d
  • minimum: 3w
modulestring

“module” defines the name of the Go module.

compatible:

  • source
  • condition

example:

  • module: github.com/sirupsen/logrus
proxystring

“proxy” defines the Go proxy to query, similar to the GOPROXY environment variable.

compatible:

  • source
  • condition

default: the GOPROXY environment variable when set, otherwise https://proxy.golang.org

remark:

  • the schemes “https://” and “http://” are supported. “file://” is not supported yet.
  • a URL without a scheme uses https.
  • several proxies can be listed, separated by commas.

example:

  • proxy: https://proxy.golang.org
versionstring

“version” defines the module version to check.

compatible:

  • condition

default: the output of the associated source.

example:

  • version: v1.9.3
versionfilterobject

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

compatible:

  • source

default: kind: semver pattern: “*”

example:

  versionfilter:
    kind: semver
    pattern: "~1.9"
    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”.
module

Mandatory - the full module path, e.g. github.com/updatecli/updatecli.

proxy

Overrides the proxy, the same way GOPROXY does. https and http schemes are accepted, and a URL without a scheme is assumed to be https. file:// proxies are not supported.

version

Condition only.

Pseudo-versions (the v0.0.0-20230101120000-abcdef123456 form Go generates for untagged commits) are understood.

Filtering by release age

age restricts which releases count as valid, which is the usual way to let a release settle before adopting it:

spec:
  module: github.com/sirupsen/logrus
  age:
    minimum: "7d"

minimum and maximum accept h, d, w, mo and y; a bare number means hours. An unparsable value fails with invalid MinimumReleaseAge "<value>".

Warning

age is not free here either. The proxy returns the version list without dates, so Updatecli issues one additional request per version to fetch each release date. On a module with a long history that is a lot of round trips, and the whole list is walked before any filtering happens.

Versions whose date cannot be fetched or parsed are skipped silently - visible only with --debug, as ignoring version "x" from proxy "y" due to …​. A proxy that rate-limits you therefore shows up as versions quietly disappearing rather than as an error.

Example

# updatecli.yaml
name: "Golang module example"

sources:
  default:
    kind: golang/module
    name: Get the latest Golang module version for github.com/Masterminds/semver/v3
    spec:
      module: "github.com/Masterminds/semver/v3"
      
  semver:
    kind: golang/module
    name: Get Golang module version for github.com/Masterminds/semver/v3 matching version 3.2
    spec:
      module: "github.com/Masterminds/semver/v3"
      versionfilter:
        kind: semver
        pattern: "3.2"

conditions:
  default:
    # The version is set by the sourceid "default"
    kind: golang/module
    name: Checks if version v3.2.0 exists for Golang module github.com/Masterminds/semver/v3
    sourceid: default
    spec:
      module: "github.com/Masterminds/semver/v3"

  noSourceInput:
    disablesourceinput: true
    kind: golang/module
    name: Checks if version v3.2.0 exists for Golang module github.com/Masterminds/semver/v3
    spec:
      module: "github.com/Masterminds/semver/v3"
      version: "v3.2.0"

Links

Last updated on August 2, 2026
Prev
Golang go.mod
Next
HCL