Feedback wanted: Getting started + "week 1" problems

[jamietanna]

We (the Renovate maintainers) are looking to understand the point-of-view for early users of Renovate.

(if you have some feedback from the first few weeks of using Renovate, that's also welcome!)

For instance:

• how is Renovate's onboarding process?
• did you use any specific presets when onboarding such as config:js-app or config:js-lib?
• once onboarded, did you understand what was needed from PRs/MRs raised by Renovate?
• as you looked to make configuration changes, how did you approach it? What documentation, blog posts, IDE autocomplete, or AI tools did you use?
• was there anything you felt was under/over-documented?
• how would you say the "getting started" flow works for you as a new user to our documentation site?
• what barriers did you find slowed your onboarding or adoption?
• if you were able to go back in time and do it again with what you know now, would you do anything differently?

Feel free to share anything that's relevant, including the above questions, or anything else.

We're looking for free-form responses.

[davidandreoletti]

@jamietanna

Submission:This is definitely a week 1 problem: #28164 (summary: #28164 (reply in thread))

[drornir]

Hi Renovate maintainers,

This text was written by ChatGPT with Cursor as a summary of a setup/debug session.

Main onboarding pain point in a self-hosted GitHub App + renovatebot/github-action setup was discovering the exact App permissions through runtime failures/edge cases.

Permissions that had to be added (and how each was discovered):

1. Issues: Read & write

• Renovate touches issue-related flows (for example dependency dashboard/checks).
• Without this, requests failed with Resource not accessible by integration during init/check phases.

2. Workflows: Read & write

• Required when Renovate updates files under .github/workflows/* via the github-actions manager.
• Without this, workflow dependency updates fail due to integration permissions.

3. Commit statuses: Read & write

• This was discovered via an edge case in the branch renovate-bot/npm-run-all-replacement.
• A pnpm artifact-update failure triggered Renovate's branch status handling.
• Renovate then attempted GET/POST /commits/{ref}/statuses, which failed with integration-unauthorized until Commit statuses permission was granted.
• Without this permission, Renovate aborted repository processing before PR flow could complete.

Not granted:

• Administration: Read-only was intentionally not granted.
• We did hit the branch-protection read path (403), but instead of granting Administration we configured behavior explicitly:
  • rebaseWhen: "conflicted"
  • automerge: false

Caching changes needed for stability/performance:

• We also had to modify repository-cache handling in the workflow to actually benefit from cached external lookups.
• Initially, cache restore/upload targeted the wrong directory (.../repository) while Renovate was writing cache under .../renovate-cache-v1, so uploads were tiny and runs were effectively cold.
• We switched cache path handling to the parent cache directory and fixed reset semantics so reset does not restore old cache.
• After that, cache artifacts became useful, reducing repeated HTTP metadata fetches across runs.

NPM registry host tuning that was unexpectedly required:

• We also had to add explicit hostRules for the public npm registry:
  • matchHost: "https://registry.npmjs.org"
  • timeout: 120000
  • concurrentRequestLimit: 8
  • abortOnError: false
• This was surprising because it is the default shared npm endpoint, but without this we still hit timeout-driven external-host-error runs in this repo.

Failure signaling was confusing:

• Broadly, critical processing errors did not always make the GitHub Action result clearly fail in a way that matched impact.
• Example: a pnpm artifact/update error could abort repository processing early, which then prevented other ecosystems (for example Maven updates) from being processed in that run.
• In that situation, expectation is that the action should be marked as failed (or at least clearly non-success) so the missed work is obvious.

Suggestion:

• Add a concise “minimum GitHub App permissions by feature/manager” table to onboarding docs for self-hosted users.

[jamietanna]

When you were looking for the permissions, did you find the docs on what permissions to use for a GitHub App? I've captured renovatebot/github-action#1020 for an explicit mention + update of the token docs for the GitHub Action

[Vringe]

For me, I had two things that were pretty surprising to me when I started with renovate:

1. Renovate always wants to clone the repository. In my case I'm running renovate inside a pipeline and so the repository is already checked out. There is no need to clone it separately. In my case it was a bit more difficult because my gitlab instance has no HTTPS enabled for cloning. So I had to setup cloning via SSH which required me to create an ssh keypair, setup a deploy key and pass the private key to the pipeline.

2. The workflow for setting up a repository with renovate is not that straight forward for me, because renovate always clones the main branch. It would be helpful to have a config option for defining the target branch to run on. Currently, I have to merge my untested changes into main or change the default branch inside gitlab/github to my development branch as a workaround. This was already proposed here and got a lot of upvotes: Run renovate in dry-run against specific branch? #16108 (reply in thread)

EDIT: Almost forgot:

3. GitLab automatically creates a $CI_JOB_TOKEN for every pipeline. It would be nice to be able to use that token for Renovate. But this does not work because Renovate tries to use API Endpoints that are not allowed by the token: See this discussion.

[arjan-s]

Still in my first week of self-hosting (working together with a self-hosted Forgejo).
I mostly found it easy to set up and get the basics going. There are some things that weren't/aren't clear to me:

• The difference between lock files and pinned versions. It took me a while to figure out that lock file updating is a different function within Renovate than pinned version updating. So I think lock file maintenance is underdocumented at the moment, especially since it's disabled by default.
• Specific to nix packages: updating the hashes as part of the process requires a custom script in postUpgradeTasks, something I didn't understand at first.
• Still unable to understand: "lock file maintenance" PRs are never updated unless there is a conflict or a new commit (and rebaseWhen=behind-base-branch). This is different from pinned versions (for instance in pyproject.toml) PRs which are always updated when a newer version is found. This has cost me quite a few hours figuring out. Found some old discussions and issues on this tracker about it, but as far as I can see there's no way to configure it to update any open lock file PRs at every run or on a schedule. One of my repos has multiple lock files with multiple inputs/packages in it, and it's very annoying that once a PR has been created for a single package update in a lock file, it won't be updated for more updates without manual action.

[vickysgd]

First: I absolutely love the idea of having a chapter called "Getting started", when I first came to Renovate and was overwhelmed by the documentation.
When I started with Renovate, it was already set up by some other team and our repos already had renovate configs in place. It was my task to improve them. So "Getting started" did not help my case. Today, I would say, reading "Configuration" and "Key concepts" would have been sufficient for me.
I still struggle with the configuration options though. None of the options behaved the way I expected it, right away. Took a lot of reading the logs in debug mode, to find out, what I have been missing ;-).