# Golang module<no value>

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

[cols="1^,1^,1^",options=header]
|===
| source | condition | target
| &#10004; | &#10004; | &#10007;
|===

== 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 link:/docs/plugins/resource/gomod/[`golang/gomod`].

== Parameters

{{< resourceparameters "sources" "golang/module" >}}

`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:

[source,yaml]
----
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

[source,yaml]
----
# updatecli.yaml
{{<include "assets/code_example/docs/plugins/resources/golang/module/updatecli.d/default.yaml">}}
----

== Links

* link:https://go.dev/ref/mod#module-proxy[Go module proxy protocol]
* link:/docs/core/versionfilter/["Version Filtering" page]