Renovate and changelogs

This page explains how Renovate fetches changelogs, when it can display them, and more.

How Renovate detects changelogs¶

Renovate detects and populates changelogs by:

Identifying a source URL from the datasource response for a package, and saving that internally as sourceUrl if found
Checking if Renovate's internal sourceUrl data for the package includes a source URL
Looking up the source URL, if it resides on a supported platform (e.g. GitHub)
Checking for both "Releases" metadata in the repository and any commonly known "changelog" file names
Filtering the found releases to only include those versions being updated by the current PR
Formatting and embedding the results into the PR body

Changelogs for private packages¶

For private packages, the algorithm is mostly the same as described above, with the additional considerations:

Renovate must be able to access the private package in the first place
The private registry must include the source URL in its response
Renovate must be able to detect and authenticate with whatever private repository corresponds to the source URL

For more details, see Private packages, looking up changelogs.

Relevant configuration options¶

`fetchChangelogs`¶

Set to off if changelog fetching is causing a problem.

Set to branch if you have an advanced use case where you're embedding changelogs in the Git commit itself, we don't recommend this due to its potential size.

`changelogUrl`¶

This doesn't help with fetching the changelogs, but if you configure it then Renovate will include a link to this URL in the PR body, so users can click through to read the changelog.

Platforms that Renovate can fetch changelogs from¶

See the list of platforms in the fetchChangelogs config option docs.

Running Renovate on a non-GitHub platform¶

Most Open Source packages are hosted on github.com, which means most changelogs are hosted there too. Fetching changelogs from github.com requires a GitHub token because GitHub blocks unauthenticated GraphQL API use.

This means that if you run Renovate on self-hosted GitHub Enterprise Server, or any non-GitHub platform which Renovate supports, then you need to configure a github.com Personal Access Token in Renovate in order to fetch changelogs.

Read Running Renovate, GitHub.com token for changelogs to learn more.

Troubleshooting missing changelogs¶

Follow these steps to find out why Renovate does not find a changelog:

The datasource for this package does not support sourceUrls.
If the registry fundamentally does not provide this data, then the only possibility is for it to be manually populated through PRs to Renovate's source code
If the registry provides source URLs in its response but Renovate does not understand the required fields, then raise a feature request with examples, or better yet a Pull Request to implement support for the source URL parsing/mapping yourself
Sometimes self-hosted versions of registries don't include the full metadata compared to what the public registries do
The package was published without source URL information being included.
For example, occasionally npm packages don't have repository fields included
For example, Docker images regularly do not have the required LABEL entry
Renovate cannot access the source repository
This is typically a concern for private repositories only
Check if the token Renovate uses has access rights to the repository you need it to access
Renovate cannot detect the file names or release name convention within the repository
In this case an enhancement to Renovate might be needed to better detect the releases/formats, assuming the package/repository has a reasonable convention to follow

If none of this helps, search the Renovate issues and discussions to see if this is a known problem.

Advice for package maintainers¶

This section is for package maintainers that want to make sure Renovate can see their changelogs.

There isn't much information to add other than what's already written above.

Make sure that you have the required source URL in your package metadata, not just in your repository but also in the final data which the registry returns. For example, we have seen cases where the repository field in npm's package.json is populated correctly in the repository, but stripped out as part of the publishing process.

Let Renovate understand your versioning and changelogs¶

In general, Renovate can understand your versions and changelogs best when you:

Use SemVer versioning, so major.minor.patch
Use the semantic-release bot to automate the release process

Try to avoid things like:

Stripping out the trailing .0 unnecessarily (e.g. having a package 3.1.0 on a registry but using only 3.1 in your changelogs)
Using "Release names" in a way which makes the actual version hard to discern (e.g. instead of 3.0.0 you title your release notes Big news! v3 is here

npm package maintainers¶

As maintainer, make sure the package.json has a filled in repository field, read the npm Docs, configuring npm repository field to learn more. If your repository uses the monorepo pattern make sure each package.json file has a repository field.