Skip to content

Datasources

After Renovate's manager scanned the files and extracted the dependencies, it assigns a datasource to each extracted package file or dependency. The datasource tells Renovate how to search for new versions.

You don't need to configure or override datasources. But you may use datasources in a packageRules array to configure Renovate's behavior, for example:

{
  "packageRules": [
    {
      "matchDatasources": ["npm"],
      "matchPackageNames": ["lodash"],
      "automerge": true
    }
  ]
}

Supported Datasources

Supported values for datasource are: adoptium-java, artifactory, aws-machine-image, aws-rds, azure-pipelines-tasks, bitbucket-tags, cdnjs, clojure, conan, conda, cpan, crate, dart, deno, docker, dotnet, flutter-version, galaxy, galaxy-collection, git-refs, git-tags, github-releases, github-tags, gitlab-packages, gitlab-releases, gitlab-tags, go, golang-version, gradle-version, helm, hermit, hex, hexpm-bob, jenkins-plugins, kubernetes-api, maven, node, npm, nuget, orb, packagist, pod, puppet-forge, pypi, repology, ruby-version, rubygems, sbt-package, sbt-plugin, terraform-module, terraform-provider.

Adoptium Java Datasource

Identifier: adoptium-java

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.

Description:

This datasource returns releases from the Adoptium API.

It uses image_type=<jre|jdk>&project=jdk&release_type=ga&sort_method=DATE&sort_order=DESC as filter parameters. This means that the datasource finds:

  • JRE or JDK images
  • with a JDK project
  • which have the General Availability status

And finally, the results are sorted in descending order.

When Renovate contacts the Adoptium API, it fetches 50 pages. Each page has 50 items. So 2500 items are fetched from the API in total.

If you want to get releases which come with the JDK, set the packageName to java-jdk or java.

If you want to get releases which come with the JRE, set the packageName to java-jre. LTS releases of Java will have a version that comes with the JRE. Non-LTS releases may not always include the JRE.


Artifactory Datasource

Identifier: artifactory

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.

Description:

Artifactory is the recommended registry for Conan packages.

This datasource returns releases from given custom registryUrl(s).

The target URL is composed by the registryUrl and the packageName, which defaults to depName when packageName is not defined.

The release timestamp is taken from the date in the directory listing, and is assumed to be in UTC time.


Aws Machine Image Datasource

Identifier: aws-machine-image

Default versioning: aws-machine-image

Custom registry support:

✅ Custom registries are supported.

Description:

Warning

This datasource is experimental. Its syntax and behavior may change at any time!

This datasource returns the latest Amazon Machine Image via the AWS API.

Because the datasource uses the AWS-SDK for JavaScript, you can configure it like other AWS Tools. You can use common AWS configuration options, for example (partial list):

  • Setting the region via AWS_REGION (environment variable) or your ~/.aws/config file
  • Provide credentials via AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (environment variable) or your ~/.aws/credentials file
  • Select the profile to use via AWS_PROFILE environment variable

Read the Developer guide for more information on configuration options.

The least IAM privileges required for this datasource are:

{
  "Sid": "AllowEc2ImageLookup",
  "Effect": "Allow",
  "Action": ["ec2:DescribeImages"],
  "Resource": "*"
}

Read the AWS IAM Reference for more information.

Because there is no general packageName, you have to use the describe images filter as minified JSON as a packageName.

Example:

# Getting the latest official EKS image from AWS (account '602401143452' for eu-central-1) for EKS 1.21 (name matches 'amazon-eks-node-1.21-*') would look as a describe images filter like:

[
  {
    "Name": "owner-id",
    "Values": [ "602401143452" ]
  },
  {
    "Name": "name",
    "Values": [ "amazon-eks-node-1.21-*" ]
  }
]

# In order to use it with this datasource, you have to minify it:

[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.21-*"]}]

At the moment, this datasource has no "manager". You have to use the regex manager for this.

Usage Example

Here's an example of using the regex manager:

module.exports = {
  regexManagers: [
    {
      fileMatch: ['.*'],
      matchStrings: [
        '.*amiFilter=(?<packageName>.*?)\n(.*currentImageName=(?<currentDigest>.*?)\n)?(.*\n)?.*?(?<depName>[a-zA-Z0-9-_:]*)[ ]*?[:|=][ ]*?["|\']?(?<currentValue>ami-[a-z0-9]{17})["|\']?.*',
      ],
      datasourceTemplate: 'aws-machine-image',
      versioningTemplate: 'aws-machine-image',
    },
  ],
};

Or as JSON:

{
  'regexManagers':
    [
      {
        'fileMatch': ['.*'],
        'matchStrings':
          [
            ".*amiFilter=(?<packageName>.*?)\n(.*currentImageName=(?<currentDigest>.*?)\n)?(.*\n)?.*?(?<depName>[a-zA-Z0-9-_:]*)[ ]*?[:|=][ ]*?[\"|']?(?<currentValue>ami-[a-z0-9]{17})[\"|']?.*",
          ],
        'datasourceTemplate': 'aws-machine-image',
        'versioningTemplate': 'aws-machine-image',
      },
    ],
}

This would match every file, and would recognize the following lines:

# With AMI name mentioned in the comments
# amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.21-*"]}]
# currentImageName=unknown
my_ami1: ami-02ce3d9008cab69cb
# Only AMI, no name mentioned
# amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.20-*"]}]
# currentImageName=unknown
my_ami2: ami-0083e9407e275acf2
const myConfigObject = {
  // With AMI name mentioned in the comments
  // amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.21-*"]}]
  // currentImageName=unknown
  my_ami1: 'ami-02ce3d9008cab69cb',
};

/**
 * Only AMI, no AMI name mentioned
 * amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.20-*"]}]
 * currentImageName=unknown
 */
const my_ami2 = 'ami-0083e9407e275acf2';
resource "aws_instance" "web" {

    # Only AMI, no name mentioned
    # amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.20-*"]}]
    # currentImageName=unknown
    ami = "ami-0083e9407e275acf2"

    count = 2
    source_dest_check = false

    connection {
        user = "root"
    }
}

Default configuration:

{
  "commitMessageExtra": "to {{{newVersion}}}",
  "prBodyColumns": [
    "Change",
    "Image"
  ],
  "prBodyDefinitions": {
    "Image": "```{{{newDigest}}}```"
  },
  "digest": {
    "commitMessageExtra": "to {{{newDigest}}}",
    "prBodyColumns": [
      "Image"
    ],
    "prBodyDefinitions": {
      "Image": "```{{{newDigest}}}```"
    }
  }
}

Aws Rds Datasource

Identifier: aws-rds

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.

Description:

This datasource returns the database engine versions available for use on AWS RDS via the AWS API. Generally speaking, all publicly released database versions are available for use on RDS. However, new versions may not be available on RDS for a few weeks or months after their release while AWS tests them. In addition, AWS may pull existing versions if serious problems arise during their use.

AWS API configuration

Since the datasource uses the AWS SDK for JavaScript, you can configure it like other AWS Tools. You can use common AWS configuration options, for example:

  • Set the region via the AWS_REGION environment variable or your ~/.aws/config file
  • Provide credentials via the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables or your ~/.aws/credentials file
  • Select the profile to use via AWS_PROFILE environment variable

Read the AWS Developer Guide - Configuring the SDK for JavaScript for more information on these configuration options.

The minimal IAM privileges required for this datasource are:

{
  "Sid": "AllowDBEngineVersionLookup",
  "Effect": "Allow",
  "Action": ["rds:DescribeDBEngineVersions"],
  "Resource": "*"
}

Read the AWS RDS IAM reference for more information.

Usage

Because Renovate has no manager for the AWS RDS datasource, you need to help Renovate by configuring the regex manager to identify the RDS dependencies you want updated.

When configuring the regex manager, you have to pass a filter as minified JSON as the packageName. For example:

# Getting the latest supported MySQL 5.7 version from RDS as a filter would look like:

[
  {
    "Name": "engine",
    "Values": [ "mysql" ]
  },
  {
    "Name": "engine-version",
    "Values": [ "5.7" ]
  }
]

# In order to use it with this datasource, you have to minify it:

[{"Name":"engine","Values":["mysql"]},{"Name":"engine-version","Values":["5.7"]}]

Here's an example of using the regex manager to configure this datasource:

{
  "regexManagers": [
    {
      "fileMatch": ["\\.yaml$"],
      "matchStrings": [
        ".*amiFilter=(?<lookupName>.+?)[ ]*\n[ ]*(?<depName>[a-zA-Z0-9-_:]*)[ ]*?:[ ]*?[\"|']?(?<currentValue>[.\\d]+)[\"|']?.*"
      ],
      "datasourceTemplate": "aws-rds"
    }
  ]
}

The configuration above matches every YAML file, and recognizes these lines:

spec:
  # amiFilter=[{"Name":"engine","Values":["mysql"]},{"Name":"engine-version","Values":["5.7"]}]
  engineVersion: 5.7.34

Azure Pipelines Tasks Datasource

Identifier: azure-pipelines-tasks

Default versioning: loose

Custom registry support:

❌ No custom registry support.

Description:

This datasource returns versions of the built-in Azure Pipelines tasks. It does not yet support Azure Pipelines tasks from the Visual Studio Marketplace


Bitbucket Tags Datasource

Identifier: bitbucket-tags

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Cdnjs Datasource

Identifier: cdnjs

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.


Clojure Datasource

Identifier: clojure

Default versioning: maven

Custom registry support:

✅ Custom registries are supported.


Conan Datasource

Identifier: conan

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Conda Datasource

Identifier: conda

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.

Description:

This datasource returns releases from the specified conda registry.

The default registry is https://api.anaconda.org/package/, which queries a specific conda channel for a specific package.

Use channel/packageName as your depName when using this datasource.


Cpan Datasource

Identifier: cpan

Default versioning: perl

Custom registry support:

❌ No custom registry support.


Crate Datasource

Identifier: crate

Default versioning: cargo

Custom registry support:

✅ Custom registries are supported.


Dart Datasource

Identifier: dart

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.


Deno Datasource

Identifier: deno

Default versioning: semver

Custom registry support:

✅ Custom registries are supported.

Description:

This datasource extracts dependencies from a denoland/apiland compatible registry server.

By default, Renovate uses the official Deno registry. You can override this by setting your own registryUrl.


Docker Datasource

Identifier: docker

Default versioning: docker

Custom registry support:

✅ Custom registries are supported.

Description:

This datasource identifies an image's source repository according to the pre-defined annotation keys of the OCI Image Format Specification.

This datasource looks for the metadata of the latest stable image found on the Docker registry and uses the value of the label org.opencontainers.image.source and org.label-schema.vcs-url as the sourceUrl. Additionally, it uses the value of the label org.opencontainers.image.revision as the gitRef.

The Label Schema is superseded by OCI annotations, use the org.opencontainers.image.source label if possible.

If you maintain a Docker image and want Renovate to find your changelogs, add a org.opencontainers.image.source field to your Dockerfile. The link must point to your GitHub or GitLab repository. Here's an example from our renovate/renovate Dockerfile:

LABEL org.opencontainers.image.source="https://github.com/renovatebot/renovate"

Default configuration:

{
  "commitMessageTopic": "{{{depName}}} Docker tag",
  "commitMessageExtra": "to {{#if isPinDigest}}{{{newDigestShort}}}{{else}}{{#if isMajor}}{{{prettyNewMajor}}}{{else}}{{{prettyNewVersion}}}{{/if}}{{/if}}",
  "digest": {
    "branchTopic": "{{{depNameSanitized}}}-{{{currentValue}}}",
    "commitMessageExtra": "to {{newDigestShort}}",
    "commitMessageTopic": "{{{depName}}}{{#if currentValue}}:{{{currentValue}}}{{/if}} Docker digest",
    "group": {
      "commitMessageTopic": "{{{groupName}}}",
      "commitMessageExtra": ""
    }
  },
  "pin": {
    "commitMessageExtra": "",
    "groupName": "Docker digests",
    "group": {
      "commitMessageTopic": "{{{groupName}}}",
      "branchTopic": "digests-pin"
    }
  }
}

Dotnet Datasource

Identifier: dotnet

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.

Description:

This datasource returns releases of the .NET Runtime and SDK. It only accepts dependencies with the name dotnet-sdk or dotnet-runtime.


Flutter Version Datasource

Identifier: flutter-version

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.


Galaxy Datasource

Identifier: galaxy

Default versioning: pep440

Custom registry support:

❌ No custom registry support.


Galaxy Collection Datasource

Identifier: galaxy-collection

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.


Git Refs Datasource

Identifier: git-refs

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.


Git Tags Datasource

Identifier: git-tags

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.


Github Releases Datasource

Identifier: github-releases

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Github Tags Datasource

Identifier: github-tags

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Gitlab Packages Datasource

Identifier: gitlab-packages

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.

Description:

GitLab Packages API supports looking up package versions from all types of packages registry supported by GitLab and can be used in combination with regex managers to keep dependencies up-to-date which are not specifically supported by Renovate.

To specify which specific repository should be queried when looking up a package, the depName should be formed with the project path first, then a : and finally the package name.

As an example, gitlab-org/ci-cd/package-stage/feature-testing/new-packages-list:@gitlab-org/nk-js would look for the@gitlab-org/nk-js packages in the generic packages repository of the gitlab-org/ci-cd/package-stage/feature-testing/new-packages-list project.

If you are using a self-hosted GitLab instance, please note the following requirements:

  • If you are on the Free edition, this datasource requires at least GitLab 13.3
  • If you are on the Premium or the Ultimate edition, this datasource requires at least GitLab 11.8, but GitLab 12.9 or more is recommended if you have a lot of packages with different names in the same project

Usage Example

A real-world example for this specific datasource would be maintaining package versions in a config file. This can be achieved by configuring a generic regex manager in renovate.json for files named versions.ini:

{
  "regexManagers": [
    {
      "fileMatch": ["^versions.ini$"],
      "matchStrings": [
        "# renovate: datasource=(?<datasource>.*?) depName=(?<depName>.*?)( versioning=(?<versioning>.*?))?( registryUrl=(?<registryUrl>.*?))?\\s.*?_VERSION=(?<currentValue>.*)\\s"
      ],
      "versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}"
    }
  ]
}

Now you may use comments in your versions.ini files to automatically update dependencies, which could look like this:

# renovate: datasource=gitlab-packages depName=gitlab-org/ci-cd/package-stage/feature-testing/new-packages-list:@gitlab-org/nk-js versioning=semver registryUrl=https://gitlab.com
NKJS_VERSION=3.4.0

By default, gitlab-packages uses the docker versioning scheme.


Gitlab Releases Datasource

Identifier: gitlab-releases

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Gitlab Tags Datasource

Identifier: gitlab-tags

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Go Datasource

Identifier: go

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.


Golang Version Datasource

Identifier: golang-version

Default versioning: semver

Custom registry support:

✅ Custom registries are supported.


Gradle Version Datasource

Identifier: gradle-version

Default versioning: gradle

Custom registry support:

✅ Custom registries are supported.


Helm Datasource

Identifier: helm

Default versioning: helm

Custom registry support:

✅ Custom registries are supported.

Default configuration:

{
  "commitMessageTopic": "Helm release {{depName}}"
}

Hermit Datasource

Identifier: hermit

Default versioning: hermit

Custom registry support:

✅ Custom registries are supported.

Description:

By default Hermit looks up packages from the open source project https://github.com/cashapp/hermit-packages.

Hermit supports private packages. To get Renovate to find your private packages, follow these steps:

  1. perform hermit search --json with your private Hermit distribution and save the file to index.json
  2. make a GitHub release in your private packages repository named index with the asset index.json generated in step 1.
  3. setup a CI pipeline to repeat step 1 & 2 on new commits to the private packages repository.
  4. Add a package rule for the Hermit manager, so that Renovate knows where to find your private packages:
{
  "packageRules": [
    {
      "matchManagers": ["hermit"],
      "defaultRegistryUrls": [
        "https://github.com/your/private-hermit-packages"
      ]
    }
  ]
}

Hex Datasource

Identifier: hex

Default versioning: hex

Custom registry support:

❌ No custom registry support.


Hexpm Bob Datasource

Identifier: hexpm-bob

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.

Description:

This datasource returns releases from Bob the builder.

Supported values for packageName:

Read the Bob the builder docs, Erlang builds for a list of supported operating systems and versions.


Jenkins Plugins Datasource

Identifier: jenkins-plugins

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Kubernetes Api Datasource

Identifier: kubernetes-api

Default versioning: kubernetes-api

Custom registry support:

✅ Custom registries are supported.

Description:

Kubernetes API upgrade versions are manually transcribed from the Kubernetes API deprecation guide. The Kubernetes API deprecation guide is updated regularly, so this list may be out of date.


Maven Datasource

Identifier: maven

Default versioning: maven

Custom registry support:

✅ Custom registries are supported.

Description:

Making your changelogs fetchable

In case you are publishing artifacts and you want to ensure that your changelogs are fetchable by Renovate, you need to configure the scm section on their pom.xml file.

For example:

<scm>
    <url>scm:git:https://github.com/path_to_repository</url>
</scm>

This is what allows Renovate to determine the sourceUrl, that it then uses to fetch the changelogs.

Note

This also works for private repositories. It can leverage the same token that you had to configure in order to be able to reach the private Artifactory.


Node Datasource

Identifier: node

Default versioning: node

Custom registry support:

❌ No custom registry support.

Description:

This datasource returns NodeJS releases from nodejs.org API.


Npm Datasource

Identifier: npm

Default versioning: npm

Custom registry support:

✅ Custom registries are supported.


Nuget Datasource

Identifier: nuget

Default versioning: nuget

Custom registry support:

✅ Custom registries are supported.


Orb Datasource

Identifier: orb

Default versioning: no default versioning

Custom registry support:

❌ No custom registry support.


Packagist Datasource

Identifier: packagist

Default versioning: composer

Custom registry support:

✅ Custom registries are supported.


Pod Datasource

Identifier: pod

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Puppet Forge Datasource

Identifier: puppet-forge

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.


Pypi Datasource

Identifier: pypi

Default versioning: pep440

Custom registry support:

✅ Custom registries are supported.


Repology Datasource

Identifier: repology

Default versioning: no default versioning

Custom registry support:

✅ Custom registries are supported.

Description:

With Repology you can look up package versions from many package repositories. You can combine Repology with regex managers to update dependencies which are not supported by Renovate.

The packageName field should be constructed using the repository identifier and the actual package name separated by a slash. For example: alpine_3_12/gcc would look for a binary (or source package) called gcc within the alpine_3_12 repository.

A list of all supported repositories can be found on the Repology homepage.

To find the correct identifier, select the repository you want and copy the identifier in the URL: https://repology.org/repository/<identifier>. For example, the Alpine Linux 3.12 repository has this URL: https://repology.org/repository/alpine_3_12 and has this repository identifier: alpine_3_12.

Usage Example

Say you're using system packages in a Dockerfile and want to update them with Repology. With the Repology datasource you can "pin" each dependency, and get automatic updates.

First you would set a generic regex manager in your renovate.json file for Dockerfile:

{
  "regexManagers": [
    {
      "fileMatch": ["^Dockerfile$"],
      "matchStrings": [
        "#\\s*renovate:\\s*datasource=(?<datasource>.*?) depName=(?<depName>.*?)( versioning=(?<versioning>.*?))?\\sENV .*?_VERSION=\"(?<currentValue>.*)\"\\s"
      ],
      "versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}"
    }
  ]
}

Then you would put comments in your Dockerfile, to tell Renovate where to find the updates:

FROM alpine:3.12.0@sha256:a15790640a6690aa1730c38cf0a440e2aa44aaca9b0e8931a9f2b0d7cc90fd65

# renovate: datasource=repology depName=alpine_3_12/gcc versioning=loose
ENV GCC_VERSION="9.3.0-r2"
# renovate: datasource=repology depName=alpine_3_12/musl-dev versioning=loose
ENV MUSL_DEV_VERSION="1.1.24-r8"

RUN apk add --no-cache \
    gcc="${GCC_VERSION}" \
    musl-dev="${MUSL_DEV_VERSION}"

When the operating system package for gcc of Alpine Linux 3.12 is updated, Renovate updates the environment variable.

Tip

We recommend you try loose versioning for distribution packages first. This is because the version number usually doesn't match Renovate's default semver specification.


Ruby Version Datasource

Identifier: ruby-version

Default versioning: ruby

Custom registry support:

❌ No custom registry support.


Rubygems Datasource

Identifier: rubygems

Default versioning: ruby

Custom registry support:

✅ Custom registries are supported.


Sbt Package Datasource

Identifier: sbt-package

Default versioning: ivy

Custom registry support:

✅ Custom registries are supported.


Sbt Plugin Datasource

Identifier: sbt-plugin

Default versioning: ivy

Custom registry support:

✅ Custom registries are supported.


Terraform Module Datasource

Identifier: terraform-module

Default versioning: hashicorp

Custom registry support:

✅ Custom registries are supported.


Terraform Provider Datasource

Identifier: terraform-provider

Default versioning: hashicorp

Custom registry support:

✅ Custom registries are supported.