Templates

Several fields in GoReleaser’s config file support templating.

Those fields are often suffixed with _template, but sometimes they may not be. The documentation of each section should be explicit about which fields support templating.

Common Fields

In fields that support templates, these fields are always available:

Key	Description
`.ProjectName`	the project name
`.Version`	the version being released¹
`.Branch`	the current git branch
`.Tag`	the current git tag
`.PreviousTag`	the previous git tag, or empty if no previous tags
`.ShortCommit`	the git commit short hash
`.FullCommit`	the git commit full hash
`.Commit`	the git commit hash (deprecated)
`.CommitDate`	the UTC commit date in RFC 3339 format
`.CommitTimestamp`	the UTC commit date in Unix format
`.GitURL`	the git remote url
`.GitTreeState`	either ‘clean’ or ‘dirty’
`.IsGitClean`	whether or not current git state is clean
`.IsGitDirty`	whether or not current git state is dirty
`.Major`	the major part of the version²
`.Minor`	the minor part of the version²
`.Patch`	the patch part of the version²
`.Prerelease`	the prerelease part of the version, e.g. `beta.1`²
`.RawVersion`	composed of `{Major}.{Minor}.{Patch}` ²
`.ReleaseNotes`	the generated release notes, available after the changelog step has been executed
`.IsDraft`	`true` if `release.draft` is set in the configuration, `false` otherwise
`.IsSnapshot`	`true` if `--snapshot` is set, `false` otherwise
`.IsNightly`	`true` if `--nightly` is set, `false` otherwise
`.IsSingleTarget`	`true` if `--single-target` is set, `false` otherwise Since v2.3
`.Env`	a map with system’s environment variables
`.Date`	current UTC date in RFC 3339 format
`.Now`	current UTC date as `time.Time` struct, allows all `time.Time` functions (e.g. `{{ .Now.Format "2006" }}`)
`.Timestamp`	current UTC time in Unix format
`.ModulePath`	the go module path, as reported by `go list -m`
`.ReleaseURL`	the current release download url³
`.Summary`	the git summary, e.g. `v1.0.0-10-g34f56g3`⁴
`.TagSubject`	the annotated tag message subject, or the message subject of the commit it points out⁵
`.TagContents`	the annotated tag message, or the message of the commit it points out⁶
`.TagBody`	the annotated tag message’s body, or the message’s body of the commit it points out⁶
`.Runtime.Goos`	equivalent to `runtime.GOOS`
`.Runtime.Goarch`	equivalent to `runtime.GOARCH`
`.Outputs`	custom outputs Since v2.11

Common Fields (Pro)

This feature is exclusively available with GoReleaser Pro.

Key	Description
`.PrefixedTag`	the current git tag prefixed with the monorepo config tag prefix (if any)
`.PrefixedPreviousTag`	the previous git tag prefixed with the monorepo config tag prefix (if any)
`.PrefixedSummary`	the git summary prefixed with the monorepo config tag prefix (if any)
`.IsRelease`	`true` if regular release (not a nightly nor a snapshot) Since v2.8
`.IsMerging`	`true` if you are running with `--merge` Since v2.8
`.Artifacts`	the current artifacts list
`.Metadata`	project metadata fields Since v2.13

Metadata

This feature is exclusively available with GoReleaser Pro.

Since v2.13.

If you use the .Metadata field, it evaluates to the project metadata configuration. You can access all fields defined in the metadata section of your config:

Key	Description
`.Metadata.Description`	project description
`.Metadata.Homepage`	project homepage URL
`.Metadata.License`	project license
`.Metadata.Maintainers`	list of project maintainers
`.Metadata.ModTimestamp`	modification timestamp template

Artifacts

This feature is exclusively available with GoReleaser Pro.

If you use the .Artifacts field, it evaluates to an artifact.Artifact list. You should be able to use all its fields on each item:

.Name
.Path
.Goos
.Goarch
.Goarm
.Gomips
.Goamd64
.Goarm64
Since v2.4
.Gomips64
Since v2.4
.Goppc64
Since v2.4
.Goriscv64
Since v2.4
.Go386
Since v2.4
.Target
Since v2.5
.Type
.Extra

Single-artifact extra fields

On fields that are related to a single artifact (e.g., the binary name), you may have some extra fields:

Key	Description
`.Os`	`GOOS`
`.Arch`	`GOARCH`
`.Arm`	`GOARM`
`.Mips`	`GOMIPS`
`.Amd64`	`GOAMD64`
`.Arm64`	`GOARM64` Since v2.4
`.Mips64`	`GOMIPS64` Since v2.4
`.Ppc64`	`GOPPC64` Since v2.4
`.Riscv64`	`GORISCV64` Since v2.4
`.I386`	`GO386` Since v2.4
`.Target`	the whole target Since v2.5
`.Binary`	artifact name (without the extension)
`.ArtifactID`	artifact id Since v2.3 GoReleaser Pro
`.ArtifactName`	artifact name
`.ArtifactPath`	absolute path to artifact
`.ArtifactExt`	artifact extension (e.g. `.exe`, `.dmg`, etc)

nFPM extra fields

In the nFPM name template field, you can use those extra fields:

Key	Description
`.Release`	release from the nfpm config
`.Epoch`	epoch from the nfpm config
`.PackageName`	package the name. Same as `ProjectName` if not overridden.
`.ConventionalFileName`	conventional package file name as provided by nFPM.⁷
`.ConventionalExtension`	conventional package extension as provided by nFPM
`.Format`	package format

Release body extra fields

In the release.body field, you can use these extra fields:

Key	Description
`.Checksums`	the current checksum file contents, or a map of filename/checksum contents if `checksum.split` is set. Only available in the release body

Functions

On all fields, you have these available functions:

Usage	Description
`replace "v1.2" "v" ""`	replaces all matches. See ReplaceAll
`split "1.2" "."`	split string at separator. See Split
`time "01/02/2006"`	current UTC time in the specified format (this is not deterministic, a new time for every call)
`contains "foobar" "foo"`	checks whether the first string contains the second. See Contains
`tolower "V1.2"`	makes input string lowercase. See ToLower
`toupper "v1.2"`	makes input string uppercase. See ToUpper
`trim " v1.2 "`	removes all leading and trailing white space. See TrimSpace
`trimprefix "v1.2" "v"`	removes provided leading prefix string, if present. See TrimPrefix
`trimsuffix "1.2v" "v"`	removes provided trailing suffix string, if present. See TrimSuffix
`dir .Path`	returns all but the last element of path, typically the path’s directory. See Dir
`base .Path`	returns the last element of path. See Base
`abs .ArtifactPath`	returns an absolute representation of path. See Abs
`filter "text" "regex"`	keeps only the lines matching the given regex, analogous to `grep -E`
`reverseFilter "text" "regex"`	keeps only the lines not matching the given regex, analogous to `grep -vE`
`title "foo"`	“titlenize” the string using english as language. See Title
`mdv2escape "foo"`	escape characters according to MarkdownV2, especially useful in the Telegram integration
`envOrDefault "NAME" "value"`	either gets the value of the given environment variable, or the given default
`isEnvSet "NAME"`	returns true if the env is set and not empty, false otherwise
`$m := map "KEY" "VALUE"`	creates a map from a list of key and value pairs. Both keys and values must be of type `string`
`indexOrDefault $m "KEY" "value"`	either gets the value of the given key or the given default value from the given map
`incpatch "v1.2.4"`	increments the patch of the given version⁸
`incminor "v1.2.4"`	increments the minor of the given version⁸
`incmajor "v1.2.4"`	increments the major of the given version⁸
`urlPathEscape "foo/bar"`	escapes URL paths. See PathEscape Since v2.5
`blake2b .ArtifactPath`	`blake2b` checksum of the artifact. See Blake2b Since v2.9
`blake2s .ArtifactPath`	`blake2s` checksum of the artifact. See Blake2s Since v2.9
`blake3 .ArtifactPath`	`blake3` checksum of the artifact. See Blake3 Since v2.15 (unreleased)
`crc32 .ArtifactPath`	`crc32` checksum of the artifact. See CRC32 Since v2.9
`md5 .ArtifactPath`	`md5` checksum of the artifact. See MD5 Since v2.9
`sha224 .ArtifactPath`	`sha224` checksum of the artifact. See SHA224 Since v2.9
`sha384 .ArtifactPath`	`sha384` checksum of the artifact. See SHA384 Since v2.9
`sha256 .ArtifactPath`	`sha256` checksum of the artifact. See SHA256 Since v2.9
`sha1 .ArtifactPath`	`sha1` checksum of the artifact. See SHA1 Since v2.9
`sha512 .ArtifactPath`	`sha512` checksum of the artifact. See SHA512 Since v2.9
`sha3_224 .ArtifactPath`	`sha3_224` checksum of the artifact. See SHA3-224 Since v2.9
`sha3_384 .ArtifactPath`	`sha3_384` checksum of the artifact. See SHA3-384 Since v2.9
`sha3_256 .ArtifactPath`	`sha3_256` checksum of the artifact. See SHA3-256 Since v2.9
`sha3_512 .ArtifactPath`	`sha3_512` checksum of the artifact. See SHA3-512 Since v2.9
`mustReadFile "/foo/bar.txt"`	reads the file contents or fails if it can’t be read Since v2.12
`readFile "/foo/bar.txt"`	reads the file contents if it it can be read, or return empty string Since v2.12
`englishJoin`	will join multiple items in english Since v2.14
`list "a" "b" "c"`	makes a list of strings

Functions (Pro)

This feature is exclusively available with GoReleaser Pro.

Usage	Description
`in (list "a" "b" "c") "b"`	checks if a slice contains a value
`reReplaceAll "(.*)" "foo" "bar-$1"`	compiles the first argument with `regexp.Compile`, then uses `ReplaceAllString` with the following arguments Since v2.8

With all those fields, you may be able to compose the name of your artifacts pretty much the way you want:

example_template: '{{ tolower .ProjectName }}_{{ .Env.USER }}_{{ time "2006" }}'

For example, if you want to add the go version to some artifact:

foo_template: "foo_{{ .Env.GOVERSION }}"

And then you can run:

GOVERSION=$(go version | awk '{print $3;}') goreleaser

Warning

Note that those are hypothetical examples and the fields foo_template and example_template are not valid GoReleaser configurations.

Custom variables

This feature is exclusively available with GoReleaser Pro.

You can also declare custom variables. This feature is specially useful with includes, so you can have more generic configuration files.

Usage is as simple as you would expect:

.goreleaser.yaml

variables:
  description: my project description
  somethingElse: yada yada yada
  empty: ""

And then you can use those fields as {{ .Var.description }}, for example.

The v prefix is stripped, and it might be changed in snapshot and nightly builds. ↩︎
Assuming Tag is a valid a SemVer, otherwise empty/zeroed. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎
Composed of the current SCM’s download URL and current tag. For instance, on GitHub, it’ll be https://github.com/{owner}/{repo}/releases/tag/{tag}. ↩︎
It is generated by git describe --dirty --always --tags, the format will be {Tag}-$N-{CommitSHA} If using Pro with a monorepo.tag_prefix, it will be passed to describe as --match={prefix}*. ↩︎
As reported by git tag -l --format='%(contents:subject)' ↩︎
As reported by git tag -l --format='%(contents)' ↩︎ ↩︎
Please beware: some OSs might have the same names for different ARM versions, for example, for Debian both ARMv6 and ARMv7 are called armhf. Make sure that’s not your case otherwise you might end up with colliding names. It also does not handle multiple GOAMD64 versions. ↩︎
Will panic if not a semantic version. ↩︎ ↩︎ ↩︎

Last updated on March 23, 2026

Includes Template Files