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
- Checking if Renovate's internal manual metadata 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¶
off if changelog fetching is causing a problem.
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.
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
npmpackages don't have
- For example, Docker images regularly do not have the required
- 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
- Use the
semantic-releasebot to automate the release process
Try to avoid things like:
- Stripping out the trailing
.0unnecessarily (e.g. having a package
3.1.0on a registry but using only
3.1in your changelogs)
- Using "Release names" in a way which makes the actual version hard to discern (e.g. instead of
3.0.0you 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
maven package maintainers¶
Docker image maintainers¶
Read the Docker datasource docs.