Template fields

In order to provide flexible configuration, Renovate supports using "templates" for certain fields like addLabels, branchName, extractVersionTemplate, labels.

Renovate's templates use handlebars under the hood. You can recognize templates when you see strings like {{depName}} in configuration fields.

Below you can find lists of fields/values that you can use in templates. Some are configuration options passed through, while others are generated as part of Renovate's run.

logJSON and releases are only allowed in commitBody template.

Exposed config options

The following configuration options are passed through for templating: additionalBranchPrefix, addLabels, branchName, branchPrefix, branchTopic, commitBody, commitMessage, commitMessageAction, commitMessageExtra, commitMessagePrefix, commitMessageSuffix, commitMessageTopic, gitAuthor, group, groupName, groupSlug, labels, prBodyColumns, prBodyDefinitions, prBodyNotes, prTitle, semanticCommitScope, semanticCommitType, separateMajorMinor, separateMinorPatch, sourceDirectory.

Other available fields

The following runtime values are passed through for templating:

• baseBranch: The baseBranch for this branch/PR
• body: The body of the release notes
• categories: The categories of the manager of the dependency being updated
• currentValue: The extracted current value of the dependency being updated
• currentVersion: The version that would be currently installed. For example, if currentValue is ^3.0.0 then currentVersion might be 3.1.0.
• currentVersionAgeInDays: The age of the current version in days
• currentVersionTimestamp: The timestamp of the current version
• currentDigest: The extracted current digest of the dependency being updated
• currentDigestShort: The extracted current short digest of the dependency being updated
• datasource: The datasource used to look up the upgrade
• depName: The name of the dependency being updated
• depNameLinked: The dependency name already linked to its home page using markdown
• depNameSanitized: The depName field sanitized for use in branches after removing spaces and special characters
• depType: The dependency type (if extracted - manager-dependent)
• depTypes: A deduplicated array of dependency types (if extracted - manager-dependent) in a branch
• displayFrom: The current value, formatted for display
• displayPending: Latest pending update, if internalChecksFilter is in use
• displayTo: The to value, formatted for display
• hasReleaseNotes: true if the upgrade has release notes
• indentation: The indentation of the dependency being updated
• isGroup: true if the upgrade is part of a group
• isLockfileUpdate: true if the branch is a lock file update
• isMajor: true if the upgrade is major
• isMinor: true if the upgrade is minor
• isPatch: true if the upgrade is a patch upgrade
• isPin: true if the upgrade is pinning dependencies
• isPinDigest: true if the upgrade is pinning digests
• isRollback: true if the upgrade is a rollback PR
• isReplacement: true if the upgrade is a replacement
• isRange: true if the new value is a range
• isSingleVersion: true if the upgrade is to a single version rather than a range
• isVulnerabilityAlert: true if the upgrade is a vulnerability alert
• logJSON: ChangeLogResult object for the upgrade
• manager: The (package) manager which detected the dependency
• newDigest: The new digest value
• newDigestShort: A shorted version of newDigest, for use when the full digest is too long to be conveniently displayed
• newMajor: The major version of the new version. e.g. "3" if the new version is "3.1.0"
• newMinor: The minor version of the new version. e.g. "1" if the new version is "3.1.0"
• newPatch: The patch version of the new version. e.g. "0" if the new version is "3.1.0"
• newName: The name of the new dependency that replaces the current deprecated dependency
• newValue: The new value in the upgrade. Can be a range or version e.g. "^3.0.0" or "3.1.0"
• newVersion: The new version in the upgrade, e.g. "3.1.0"
• newVersionAgeInDays: The age of the new version in days
• packageFile: The filename that the dependency was found in
• packageFileDir: The directory with full path where the packageFile was found
• packageName: The full name that was used to look up the dependency
• packageScope: The scope of the package name. Supports Maven group ID only
• parentDir: The name of the directory that the dependency was found in, without full path
• parentOrg: The name of the parent organization for the current repository
• platform: VCS platform in use, e.g. "github", "gitlab", etc.
• prettyDepType: Massaged depType
• prettyNewMajor: The new major value with v prepended to it.
• prettyNewVersion: The new version value with v prepended to it.
• project: ChangeLogProject object
• recreateClosed: If true, this PR will be recreated if closed
• references: A list of references for the upgrade
• releases: An array of releases for an upgrade
• releaseNotes: A ChangeLogNotes object for the release
• releaseTimestamp: The timestamp of the release
• repository: The current repository
• semanticPrefix: The fully generated semantic prefix for commit messages
• sourceRepo: The repository in the sourceUrl, if present
• sourceRepoName: The repository name in the sourceUrl, if present
• sourceRepoOrg: The repository organization in the sourceUrl, if present
• sourceRepoSlug: The slugified pathname of the sourceUrl, if present
• sourceUrl: The source URL for the package
• topLevelOrg: The name of the top-level organization for the current repository
• updateType: One of digest, pin, rollback, patch, minor, major, replacement, pinDigest
• upgrades: An array of upgrade objects in the branch
• url: The url of the release notes
• version: The version number of the changelog
• versioning: The versioning scheme in use
• versions: An array of ChangeLogRelease objects in the upgrade
• vulnerabilitySeverity: The severity for a vulnerability alert upgrade (LOW, MEDIUM, MODERATE, HIGH, CRITICAL, UNKNOWN)

Additional Handlebars helpers

and

Returns true only if all expressions are true.

{{#if (and isMajor hasReleaseNotes)}}Backwards Incompatible release! Check out the Release notes.{{/if}}

In the example above, it will only show a text if isMajor=true and hasReleaseNotes=true.

containsString

Returns true if a given string is a substring.

{{#if (containsString depName 'python')}}Python{{else}}Other{{/if}}

decodeURIComponent

If you want to decode a percent-encoded string, use the built-in function decodeURIComponent like this:

{{{decodeURIComponent depName}}}

In the example above depName is the string you want to decode.

Read the MDN Web Docs, decodeURIComponent() to learn more.

distinct

Removes duplicate elements from an array.

{{#each (distinct (lookupArray (lookupArray upgrades "prBodyDefinitions") "Issue"))}} {{{.}}}{{/each}}

encodeBase64

If you want to convert a string to Base64, use the built-in function encodeBase64 like this:

{{{encodeBase64 body}}}

In the example above body is the string you want to transform into a Base64-encoded value.

encodeURIComponent

If you want to convert a string to a valid URI, use the built-in function encodeURIComponent like this:

{{{encodeURIComponent baseDir}}}

In the example above baseDir is the string you want to transform into a valid URI.

Read the MDN Web Docs, encodeURIComponent() to learn more.

equals

Returns true if two values equals (checks strict equality, i.e. ===).

{{#if (equals datasource 'git-refs')}}git-refs{{else}}Other{{/if}}

lookupArray

Similar to the built-in lookup helper, but performs lookups in every element of an array, instead of just one object.

For example:

{{#each (lookupArray upgrades "prBodyDefinitions")}} {{{Issue}}}{{/each}}

will produce the same output as:

{{#each upgrades}}{{#with prBodyDefinitions}} {{{Issue}}}{{/with}}{{/each}}.

The return value of lookupArray can be passed to other helpers - for example, to distinct.

lowercase

The lowercase helper converts a given string to lower case.

{{{ lowercase depName }}}

or

Returns true if at least one expression is true.

{{#if (or isPatch isSingleVersion}}Small update, safer to merge and release.{{else}}Check out the changelog for all versions before merging!{{/if}}

replace

The replace helper replaces all found strings matching the given regex with the replacement string. If you want to replace some characters in a string, use the built-in function replace like this:

{{{replace '[a-z]+\.github\.com' 'ghc' depName}}}

In the example above all matches of the regex [a-z]+\.github\.com will be replaced by ghc in depName.

Read the MDN Web Docs, String.prototype.replace() to learn more.

split

Splits a string into an array of substrings.

This example splits a package name by - and gets the second part: {{ lookup (split packageName '-') 1 }} An input of foo-bar-test therefor would return bar.

stringToPrettyJSON

If you want to print pretty JSON with Handlebars you can use the built-in function stringToPrettyJSON like this:

{{{stringToPrettyJSON myvar}}}

In the example above myvar is a variable/field, that has valid JSON.

toArray

If you want to convert elements to an array, use toArray, e.g.,

{{{ toJSON (toArray 'value1' 'value2' 'value3') }}} will render ["value1","value2","value3"].

toJSON

If you want to convert an object to a JSON string, you can use the built-in function toJSON like this:

{{{ toJSON upgrades }}}

toObject

If you want to convert key-value pairs to an object, use toObject, e.g.,

{{{ toJSON (toObject 'key1' 'value1' 'key2' 'value2') }}} will render {"key1":"value1","key2":"value2"}.

Environment variables

By default, you can only access a handful of basic environment variables like HOME or PATH. This is for security reasons.

HOME is {{env.HOME}}

If you're self-hosting Renovate, you can expose more variables with the customEnvVariables config option.

You can also use the exposeAllEnv config option to allow all environment variables in templates, but make sure to consider the security implications of giving the scripts unrestricted access to all variables.