Docs

Golang go.mod

sourceconditiontarget

✔

✔

✔

Description

The golang/gomod resource reads and writes a version inside a go.mod file. It works in two modes depending on whether module is set:

module unset

The Go language version - the go directive.

module set

The version of that dependency in the require block.

source

Returns the version found.

condition

Checks that the file records the expected version.

target

Writes the version. A file already holding it is reported as go.mod already set Golang version to "x" (or go.mod already has Module "m" set to version "v") and left untouched.

Parameters

NameTypeDescriptionRequired
filestring

File defines the go.mod file, default to “go.mod”

compatible:

  • source
  • condition

remark:

  • scheme “https://”, “http://”, and “file://” are supported in path for source and condition
indirectboolean

Indirect specifies if we manipulate an indirect dependency

compatible:

  • source
  • condition
modulestring

Module defines the module path

compatible:

  • source
  • condition

remark:

  • scheme “https://”, “http://”, and “file://” are supported in path for source and condition
replaceboolean

Replace specifies if we manipulate a replaced dependency

compatible:

  • source
  • condition
  • target
replaceversionstring

ReplaceVersion specifies the specific Go module version to replace

compatible:

  • source
  • condition
  • target

default: unset, which will match any version of the module being replaced.

Example: For the following Go replace instruction: moduleA v1.2.3 => moduleB v1.0.0

  • The ‘module’ field should be set to ‘moduleA’ (the module being replaced, left-hand side).
  • The value of ReplaceVersion should be ‘v1.2.3’, corresponding to the version of moduleA (the module being replaced, left-hand side).
versionstring

Version Defines a specific golang version

compatible:

  • source
  • condition
file

Defaults to go.mod.

module

The module path, e.g. github.com/sirupsen/logrus. Leave unset to act on the go directive.

indirect

Set it to act on a dependency marked // indirect.

version

Overrides the source output.

Replace directives

replace and replaceversion address a replace instruction rather than a require one. Given:

replace moduleA v1.2.3 => moduleB v1.0.0

set module: moduleA (the module being replaced, on the left) and replaceversion: v1.2.3 to pin which replace instruction is meant. Leaving replaceversion unset matches any version of that module.

Limitations

Important

A golang/gomod target updates go.mod and does not touch go.sum. The repository is left in a state where go build fails until the checksums are refreshed, so pair the target with a shell target running go mod tidy (as the example below does).

Remote files

For a source and a condition, file accepts https://, http:// and file://. A target must write locally.

Example

# updatecli.yaml
name: "Interact with go.mod"

scms:
  updatecli:
    kind: github
    spec:
      owner: updatecli
      repository: updatecli
      username: '{{ requiredEnv "GITHUB_ACTOR" }}'
      token: '{{ requiredEnv "GITHUB_TOKEN" }}'

sources:
  default:
    kind: golang/gomod
    name: Get module version used in go.mod
    scmid: updatecli
    spec:
      module: github.com/Masterminds/semver/v3

  golang:
    kind: golang/gomod
    name: Get Golang version used in go.mod
    scmid: updatecli
    spec:
      kind: golang

conditions:
  default:
    disablesourceinput: true
    kind: golang/gomod
    name: Ensure github.com/Masterminds/semver/v3 module version is v3.2.0
    scmid: updatecli
    spec:
      module: github.com/Masterminds/semver/v3
      file: pkg/plugins/resources/go/gomod/testdata/go.mod
      version: "v3.2.0"

  goversion:
    kind: golang/gomod
    name: Ensure golang version is set to value retrieved from source golang
    scmid: updatecli
    sourceid: golang
    spec:
      kind: golang

targets:
  default:
    disablesourceinput: true
    kind: golang/gomod
    name: Ensure github.com/Masterminds/semver/v3 module is set to v3.2.0
    scmid: updatecli
    spec:
      module: github.com/Masterminds/semver/v3
      file: pkg/plugins/resources/go/gomod/testdata/go.mod
      version: "v3.2.0"

  goversion:
    kind: golang/gomod
    name: Ensure Golang version is set based on source "default"
    scmid: updatecli
    sourceid: golang
    spec:
      file: pkg/plugins/resources/go/gomod/testdata/go.mod
      kind: golang

  # Its' important to notice that the gomod plugin do not run the command 
  # `go mod tidy` which need to be handled in a different stage such as
  goModTidy:
    dependson:
      - goversion
      - default
    disablesourceinput: true
    kind: shell
    name: Run `go mod tidy`
    spec:
      changedif:
        kind: file/checksum
        spec:
          files:
            - go.mod
            - go.sum
      command: go mod tidy
      environments:
        - name: HOME
        - name: PATH
    scmid: updatecli

Links

Last updated on July 30, 2026
Prev
Golang
Next
Golang module