diff --git a/Documentation/Renovate.md b/Documentation/Renovate.md new file mode 100644 index 00000000000..a938d639583 --- /dev/null +++ b/Documentation/Renovate.md @@ -0,0 +1,82 @@ +# Renovate Dependency Update Tool + +## Introduction + +This document outlines the integration of [Renovate](https://github.com/renovatebot/renovate) into Arcade to automate dependency updates. +Renovate is an automated dependency update tool that generates PRs for updating dependencies from a wide variety of sources. + +Renovate is similar to Dependabot in its purpose. +Dependabot should be used when possible. +However, Renovate supports a much broader range of [dependency types](https://docs.renovatebot.com/modules/datasource/), most notably Docker and GitHub releases. +For example, Renovate can automatically generate a PR to update a referenced Docker image when a newer version is available. + +### Example Scenarios + +Here are two scenarios demonstrating the usefulness of Renovate automatically making dependency updates: + +#### Container Tags + +Repos that reference container tags from the [dotnet/dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repo need to maintain those tags to ensure they are supported. + +This can be as simple as automatically updating to a new major version of Linux distro: + +```diff +-mcr.microsoft.com/dotnet-buildtools/prereqs:debian-11-helix-amd64 ++mcr.microsoft.com/dotnet-buildtools/prereqs:debian-12-helix-amd64 +``` + +Or automatically pinning to the latest version of a tag by it's digest value: + +```diff +-mcr.microsoft.com/dotnet-buildtools/prereqs:debian-12-helix-amd64@sha256:b99da50c4cb425e72ee69c2b8c1fdf99e0f71059aee19798e2f9310141ea48fb ++mcr.microsoft.com/dotnet-buildtools/prereqs:debian-12-helix-amd64@sha256:6bb6fef390e6f09a018f385e346b0fe5999d7662acd84ca2655e9a3c3e622b71 +``` + +Renovate can detect when these new container images are available and submit PRs to update sources accordingly. + +Related issue: [Automatically update image references in consuming repos (#1321)](https://github.com/dotnet/dotnet-buildtools-prereqs-docker/issues/1321) + +#### GitHub Release + +There are many cases where a version of OSS published via GitHub releases is being referenced by a .NET repository. +Those versions can be kept updated automatically as new releases occur. + +For example, there are Dockerfiles in the [dotnet/dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repo which reference the LLVM version that can be maintained by having Renovate automatically check for new [LLVM releases](https://github.com/llvm/llvm-project/releases). + +```diff +-LLVM_VERSION=19.1.7 ++LLVM_VERSION=20.1.0 +``` + +## Design + +### Fork Mode + +Protecting GitHub repositories in the dotnet organization from direct access by the Renovate tool is crucial. +Renovate will be used in fork mode, limiting its permissions to forked repositories. +This avoids giving write permissions to Renovate on any dotnet repository. +This means that Renovate acts as though it's any other outside contributor, not requiring any special permissions in the dotnet organization or repositories. + +A GitHub bot account, `dotnet-renovate-bot`, is used to manage the Renovate operations. +This account has the ability to create forks from dotnet repositories, which will be the source of the head branch for PRs that are created. +The PRs generated by Renovate will be done using this bot account. +Renovate also handles synchronization from the upstream branch automatically. +GitHub scopes required by this account: `repo`, `workflow`. + +### Repo Usage + +Arcade provides an Azure DevOps pipeline YAML job template that repositories should utilize when making use of Renovate. +This template handles the execution of Renovate, ensuring a standardized approach across all repositories. +Repositories wishing to make use of Renovate can reference this template from a pipeline YAML file, setting the schedule trigger as desired. +Consuming repositories are responsible for providing their own [Renovate configuration file](https://docs.renovatebot.com/configuration-options/) that describes which dependencies should be updated. + +Repositories are in control of how often Renovate will run via the pipeline schedule trigger (once a day, once a week, etc). +Typically, a pipeline would be configured to update all dependencies at once in which case all dependencies are described in one Renovate config file. +But in some cases, it may be desired to have certain dependencies updated on a different schedule than others. +In that case, the repo maintainer would define multiple pipelines with those separate schedules, all configured to run Renovate. +Importantly, each of those pipelines would need to reference a separate Renovate config file which defines the scope of the updates that will be targeted. +Lastly, a maintainer is free to manually run the pipeline if an expected update is needed right away. + +## Renovate Configuration Patterns + +TBD