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, azure-pipelines-tasks, bitbucket-tags, cdnjs, clojure, conan, conda, cpan, crate, dart, docker, 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, jenkins-plugins, 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

Description:

This datasource returns releases from Adoptium API.

It uses image_type=<jre|jdk>&project=jdk&release_type=ga&sort_method=DATE&sort_order=DESC&vendor=adoptium as filter parameters.

It only uses the first 50 pages with 50 items per page.

Use java-jdk or java as packageName to get releases which come with the Java Development Kit.

Use java-jre as packageName if you only want releases which come with the Java Runtime Environment. Currently only the LTS releases of Java come with the JRE.


Artifactory Datasource

Identifier: artifactory

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

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

Azure Pipelines Tasks Datasource

Identifier: azure-pipelines-tasks

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


Cdnjs Datasource

Identifier: cdnjs


Clojure Datasource

Identifier: clojure


Conan Datasource

Identifier: conan


Conda Datasource

Identifier: conda

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


Crate Datasource

Identifier: crate


Dart Datasource

Identifier: dart


Docker Datasource

Identifier: docker

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 isMajor}}{{{prettyNewMajor}}}{{else}}{{{prettyNewVersion}}}{{/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"
    }
  },
  "group": {
    "commitMessageTopic": "{{{groupName}}} Docker tags"
  }
}

Flutter Version Datasource

Identifier: flutter-version


Galaxy Datasource

Identifier: galaxy


Galaxy Collection Datasource

Identifier: galaxy-collection


Git Refs Datasource

Identifier: git-refs


Git Tags Datasource

Identifier: git-tags


Github Releases Datasource

Identifier: github-releases


Github Tags Datasource

Identifier: github-tags


Gitlab Packages Datasource

Identifier: gitlab-packages

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


Gitlab Tags Datasource

Identifier: gitlab-tags


Go Datasource

Identifier: go


Golang Version Datasource

Identifier: golang-version


Gradle Version Datasource

Identifier: gradle-version


Helm Datasource

Identifier: helm

Default configuration:

{
  "commitMessageTopic": "Helm release {{depName}}",
  "group": {
    "commitMessageTopic": "{{{groupName}}} Helm releases"
  }
}

Hermit Datasource

Identifier: hermit

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


Jenkins Plugins Datasource

Identifier: jenkins-plugins


Maven Datasource

Identifier: maven

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

Description:

This datasource returns NodeJS releases from nodejs.org API.


Npm Datasource

Identifier: npm


Nuget Datasource

Identifier: nuget


Orb Datasource

Identifier: orb


Packagist Datasource

Identifier: packagist


Pod Datasource

Identifier: pod


Puppet Forge Datasource

Identifier: puppet-forge


Pypi Datasource

Identifier: pypi


Repology Datasource

Identifier: repology

Description:

Repology supports looking up package versions from a wide variety of package repositories 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 packageName has to have the repository identifier and the package name itself, separated by a slash. As an 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 determine the correct identifier, click on a repository of your choice and make note of the identifier in the URL: https://repology.org/repository/<identifier>

As an example, the Alpine Linux 3.12 repository points to https://repology.org/repository/alpine_3_12 and therefor has the repository identifier alpine_3_12.

Usage Example

A real world example for this specific datasource would be maintaining system packages within a Dockerfile, as this allows to specifically pin each dependency without having to manually keep the versions up-to-date. This can be achieved by configuring a generic regex manager in renovate.json for files named 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}}"
    }
  ]
}

Now you may use regular comments in your Dockerfile to automatically update dependencies, which could look like this:

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

It is often wise to use the loose versioning for distribution packages as the version number usually does not strictly match the semver specification which is used by default. Now whenever the OS package for gcc of Alpine Linux 3.12 is being updated, Renovate will automatically adjust the value of the environment variable to the newest version.


Ruby Version Datasource

Identifier: ruby-version


Rubygems Datasource

Identifier: rubygems


Sbt Package Datasource

Identifier: sbt-package


Sbt Plugin Datasource

Identifier: sbt-plugin


Terraform Module Datasource

Identifier: terraform-module


Terraform Provider Datasource

Identifier: terraform-provider