What's the future of the local platform?

[jamietanna]

Tell us more.

Renovate's local platform is a powerful capability, and one that Renovate has that other competing other tools do not.

The platform=local mode can be very useful when testing Renovate config changes locally, as an alternative to using the reconfigure branch approach.

Although not as widely used compared to our remote platforms (like platform=github or platform=forgejo), this may be due to known limitations.

Right now, the local platform only allows running in dryRun=extract or dryRun=lookup modes.

Because the local platform doesn't need to be running against a Git repository, but can instead run against a local directory without a .git folder, running in dryRun=full currently throws an error.

As per user feedback, and utility to the maintainers, we've been thinking about what the future of the local platform could be, and what improvements we can make that benefit the general community.

Making it possible for the local platform to run in dryRun=full, or even making changes to the local filesystem would be useful.

Additionally, given the new agentic world we live in, it may be useful to give a way for Renovate to run on a local repo so an agent loop can test config changes.

Below are the considerations I'd see for where we can go next with platform=local, and what it will unlock.

For improved configuration development

As noted above, using platform=local can be very useful when testing Renovate configuration changes locally, to get a more in-depth feel for the changes that Renovate will make.

Separately, I'm (still) working on writing a blog post about the different approaches I take to testing configuration changes, and platform=local does feature heavily.

Adding support for dryRun=full would give additional options for fully understanding what Renovate is going to do, without the additional network hop(s) of needing to push changes to a remote Git repository and wait for Renovate to run.

Changes on a local Git repo

In cases where Renovate knows it's running in --platform=local --dry-run=null, and there is a Git repository found locally, it could then make changes, as if it were operating against another Platform.

(Because dryRun=lookup by default when using platform=local, this would be something a user would opt-in for with dryRun=null, and so we shouldn't need additional flags to allow this - perhaps a check to make sure that the work tree isn't dirty, and if so, error out)

Renovate would process the repository, as if it had cloned it from another Platform, create the relevant branches, and then switch back to the default branch.

This would not attempt to push the branches to a remote, if there is one.

Changes on a directory/file without a Git repo

This would need to be even more cautious than when running against a Git repo, as there's no way to undo changes that Renovate's performed.

This would require an explicit opt-in via an additional flag.

This would allow for cases where you want to i.e. say "update this go.mod or Makefile to the latest versions of everything, given this configuration".

Operating on platforms Renovate doesn't yet support

In cases where folks are using platforms that Renovate doesn't (yet) support, it would be possible to use platform=local to at least drive the code changes.

This would at least allow a Git repo to receive the changes, and then it would be up to the user to push them to the remote and/or create a Pull Request (or their platform equivalent)

Not at the cost of maintainability of other platforms

We should not add this functionality at the cost of other platforms Renovate supports.

Although there are some areas that this would improve usage for users of Renovate, platform=local is - currently - very low on the usage scale (based on the "gut feel" we get based on Discussions/Issues - Renovate has no telemetry) compared to other platforms.

Suggested roadmap items

• Mark the platform=local as "experimental"
  • As a way of indicating that we may change/break things over time, rather than "this shouldn't be relied upon"
• Allow configuring where local> presets should come from
  • A platform=local specific lookup, with a specific flag i.e. --platform-local-presets-platform which allows for using Host Rules to then look it up based on hostType=${platform-local-presets-platform}
  • This would then make it so it was possible to use an existing repo that uses local> presets, and redirect them to the right Platform
• Throw an error if platform=local dryRun=null but the Git work tree is dirty
  • To protect against accidentally clobbering someone's existing repo checkout
• Allow platform=local dryRun=null to perform code changes when there is a Git repository
  • Q: How would it determine the default branch? Explicitly require basebranchpatterns? Use whatever the branch name was when it started?
• Allow platform=local dryRun=null to perform code changes when there is not a Git repository
  • This would need a separate flag to be used to specify that "I'm very sure that I'm about to clobber a directory that doesn't have Git set up by performing changes"
• Allow platform=local dryRun=full to run when there is a Git repository
• Allow platform=local dryRun=full to run when there is not a Git repository
  • If this is straightforward to do so
• Do not change default dryRun=lookup mode when in platform=local
  • To be clear, we will keep the default as dryRun=lookup, so it's then explicitly requested to run in dryRun=full or dryRun=null
• Ensure that OpenTelemetry instrumentation works when using platform=local
  • This should already be the case, but I'd like to make sure it's set
• Set the repository=$(basename $PWD)
  • Instead of repository=local, it would show as the directory being run from, for slightly more impactful output
• platform=local: print branch information #27600
• Allow platform=local to only operate on a single package file
  • I.e. to allow us to say "I want to look at what update(s) this mcp.json has"

Related issues/discussions

• How do we debug/test configuration options #14215
• How to update local branch only, on-demand? #16238
• Support local presets for local platform #22650
• Cannot read properties of undefined (reading '') #22953
• Run renovate on the current git repository #23803
• How can I test a config change without merging it? #24180
• Running Renovate in local mode with missing configuration file produces unhelpful error message #24429
• Run renovate locally without using any platform #24846
• `local` platform cannot override `requireConfig` #25202
• How to run entirely locally to try it out on a checked out repo? #25595
• How to run entirely locally to try it out on a checked out repo? #25595
• Cannot read properties of undefined (reading '') #26731
• Feature request: make PR creation dry-runs possible on local environment #27315
• Apply changes with `--platform=local` #27458
• Full dry run on local platform #27498
• Performing updates using --platform=local #27814
• TypeError: Cannot read properties of undefined (reading '')\n at getBranchCommit #28329
• Let renovate create PRs / file modifications in local mode #33682
• Optionally print diffs when running locally #34164 -> Dry Run general improvement
• Running in local mode does really strange things #35042
• Is there a way to run renovate in local mode but also have it edit the files? #35716
• Errors are thrown when using platform=local #36538
• Local platform mode that applies update the the current working directory #36764
• Running locally doesn't work on the simplest of examples #37869
• platform=local: print branch information #27600
• feat: allow local platform to make changes #40827
• `local` platform must be onboarded #25203
• renovate --platform local does not work #29194
• Can renovate work with git repository directly? #29675
• Support for making local filesystem changes (with `platform=local`) #39182
• Q: how to run renovate cli locally and apply the changes without github prs/interaction? #39259

Also related:

• https://github.com/renovatebot/renovate/discussions?discussions_q=%22Cannot+read+properties+of+undefined%22+

[secustor]

Based on your description I think this should be two different platforms e.g.

• local --> apply all enabled upgrades to the current path.
• local-git ---> behavior like any platform we have today including preset resolution, but only with optional push

The flag combination could IMO be rather confusing and splitting up the platforms would give us cleaner code.

dry-run would work the same as the normal platforms.

Local

Would be in some sense a catch it all for use cases where people want to update package manager. Similar to CLIs which are focused right now on that.

This would be basically your --platform=local --dry-run=null.

Local-git

Would cover the unsupported platform case and debugging then.

[nielsbasjes]

My common usecase: I have a tricky renovate rule I need to write (regex matching is a common example) and I want to be able to repeatedly run it on my local machine and I only need to SEE what changes would be made.

Wanted behavior: I throw 1 or 2 test files in a directory, add a renovate.json5 file and quickly and repeatedly have the ability to see what would happen. My preferred form is to have renovate run from docker because that would avoid any need to install it at all.

Suggestion: Add --dry-run=patch with the intended behavior of generating the changes it would have done as a patch/diff outputted to the console.

[jamietanna]

As per #41718 we'll now output the full commit's diff as part of --dry-run=full

Edit: but this doesn't work on platform=local

[nielsbasjes]

Thanks!

However when doing this in combination with platform=local I'm not seeing any diffs (or similar) in the output. I'm using the 43.101.2 via docker, mount the project directory, set the environment variable to enable the debug logging and do renovate --platform=local --dry-run=full

I get some found changes, proposed branches (all of these LGTM) followed by errors "Cannot sync git when platform=local". Yet no diff (or similar) output to the console.

Did I misunderstand?

[jamietanna]

Ah, sorry no - that was my bad. This won't work on platform=local 🫣

[nielsbasjes]

Ok, understood.