Skip to content

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.

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
  • 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.
  • 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)
  • 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
  • isLockfileUpdate: true if the branch is a lock file update
  • isMajor: true if the upgrade is major
  • 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
  • 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 if "3.1.0"
  • newMinor: The minor version of the new version. e.g. "1" if the new version if "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"
  • 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
  • parentDir: The name of the directory that the dependency was found in, without full path
  • 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
  • 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
  • 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

Additional Handlebars helpers

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.

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.

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.

replace

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

{{{replace 'github.com' 'ghc' depName}}}

In the example above all matches of github.com will be replaced by ghc in depName.

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

lowercase

The lowercase helper converts a given string to lower case.

{{{ lowercase depName }}}

containsString

Returns true if a given string is a substring.

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

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.

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}}

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 additional 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.