What the agent does
The agent lists every file that pins a version before writing a config, because Renovate's managers are chosen by what the repository contains. In a project like spring-projects/spring-petclinic there are two builds of the same application: build.gradle declares plugins inline, org.springframework.boot at 4.1.0, io.spring.dependency-management at 1.1.7, org.graalvm.buildtools.native, org.cyclonedx.bom, io.spring.javaformat and io.spring.nohttp, and ext properties such as checkstyleVersion = "12.3.1" and webjarsBootstrapVersion = "5.3.8" that the dependency block interpolates; pom.xml inherits from spring-boot-starter-parent 4.1.0 and keeps the same tools as properties, checkstyle.version, jacoco.version 0.8.15 and the webjars versions. gradle/wrapper/gradle-wrapper.properties pins Gradle 9.5.1 and .mvn/wrapper/maven-wrapper.properties Maven 3.9.16. Three workflows under .github/workflows/ use actions/checkout at v4 and, in deploy-and-test-cluster.yml, at v2, with actions/setup-java@v4, gradle/actions/setup-gradle@v4 and helm/kind-action@v1. docker-compose.yml runs mysql:9.7 and postgres:18.4, k8s/db.yml runs postgres:18.4 again and k8s/petclinic.yml an untagged dsyer/petclinic, and .devcontainer/devcontainer.json uses mcr.microsoft.com/devcontainers/base:ubuntu. There is no renovate.json and no .github/dependabot.yml.
The config is one file, renovate.json at the root, with the $schema line and "extends": ["config:recommended"], the preset Renovate's documentation builds from the dependency dashboard, semantic commit prefixes, curated groupings for monorepos and known package families, replacement rules and workarounds. Most of the managers the project needs turn on by that alone: gradle matches .gradle files and gradle.properties, gradle-wrapper matches the wrapper properties, maven matches pom.xml, maven-wrapper matches .mvn/wrapper/maven-wrapper.properties and the mvnw scripts, github-actions matches the workflows, and docker-compose matches the compose file. The exception is kubernetes, which the documentation says matches no files by default because checking every YAML file would be wrong; the agent adds "kubernetes": {"managerFilePatterns": ["/^k8s/.+\\.yml$/"]} so only the two manifests under k8s/ are read. The untagged dsyer/petclinic image has no version to track, and the pull request says so rather than pretending Renovate will update it.
packageRules are where the two builds are kept in step. The agent adds a rule that groups org.springframework.boot:spring-boot-starter-parent from the pom with the org.springframework.boot Gradle plugin under one groupName, so a Spring Boot upgrade is one pull request that changes both files rather than two that pass CI separately and disagree after merge; a second rule does the same for spring-javaformat, nohttp and checkstyle, which appear in both builds under different coordinates. A schedule of early Monday morning in the team's time zone and the dashboard from the preset keep the volume readable, and postgres gets a rule that pins its major version, because a database major is a migration, not a dependency bump. The agent does not add the digest pinning from config:best-practices, and explains in the pull request what that preset would change, since pinned action digests alter how every workflow line reads.
Then the agent checks the file the way Renovate would. It runs npx --yes --package renovate -- renovate-config-validator renovate.json, the validator the Renovate package ships, and fixes anything it reports. It reads back the managerFilePatterns against the real paths with a shell glob so the k8s/ pattern matches db.yml and petclinic.yml and nothing else, and writes a short section in the README on what Renovate will open first: the actions/checkout@v2 in the cluster workflow, which is three majors behind the other two, is the kind of thing the first run surfaces. One step stays with the reader: installing the Renovate GitHub App on the repository, or pointing a self-hosted Renovate at it, which the agent cannot do from a sandbox and which the pull request puts first.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Renovate to this repository. First list every file that pins a version: Gradle and Maven build files, both wrappers, GitHub Actions workflows, Docker Compose files, Kubernetes manifests and dev container config. Write renovate.json at the root with the $schema line and extends config:recommended, enable the kubernetes manager only for the directory that holds the manifests through managerFilePatterns, and add packageRules that group the Spring Boot version across the Maven parent and the Gradle plugin, group the shared code-quality tools that appear in both builds, pin the major version of database images, and set a weekly schedule. Do not enable digest pinning; describe what config:best-practices would add instead. Validate the file with the renovate-config-validator from the renovate npm package and confirm each file pattern matches the intended paths. Say in the pull request that the Renovate app must be installed on the repository by a maintainer, name the first updates Renovate is likely to open, and link the issue.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds renovate.json and a README section and changes no build file; the versions in build.gradle, pom.xml and the workflows are exactly what they were, because Renovate will propose the bumps in its own pull requests once it runs. The description quotes the validator's output, lists each manager with the files it will read, states that dsyer/petclinic is untagged and will not be tracked, and ends with the one action for the maintainer: install the Renovate app, after which the onboarding pull request and the dependency dashboard issue appear.
A reviewer checks the grouping rules against how they want to review upgrades, since a group means one pull request touching both builds, and the schedule against when CI has room. After the app is installed, the first Renovate pull requests are the test of the config: an actions/checkout bump in the cluster workflow, a Gradle wrapper bump in gradle-wrapper.properties, and a grouped Spring Boot pull request that changes pom.xml and build.gradle together.
Run it on every Linear issue labelled dependencies
A team that triages in Linear adds an automation to the Project with a linear trigger on linear.issue.labeled, the label dependencies and plan mode, so the agent reads the issue and the repository and posts the managers it would enable, the grouping rules and the schedule as a comment on the issue. Only a change by a member of the Rush org fires it, and the comment is the whole result: an automation's runs are read-only and push nothing.
When the plan is agreed, a handler on the team's own server starts the run that pushes: it sends this body with the Linear issue URL added to resources, which puts the issue text in front of the agent through the team's Linear connection, and a request_id that is a UUID v5 of the issue id, so a redelivered event returns the run already started rather than a second pull request.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A Renovate config is small and its mistakes are slow to show: a manager that never matched its files is noticed months later, a missing group produces two pull requests that each pass and together break the build, and a broad YAML pattern turns every manifest in the repository into a dependency. The agent reads every version-bearing file first, writes the patterns against the real paths, validates the config with Renovate's own validator in its own sandbox and keeps the commands and output in the run's record, so the pull request shows which files Renovate will read rather than hoping the defaults cover them.
A project that maintains the same application in Gradle and Maven is where the config earns its keep, and the agent reads both builds to find the coordinates that must move together. Several repositories with their own mix of build tools get a pull request each, with the managers and rules their files call for.
Frequently asked questions
Why Renovate rather than Dependabot?
Dependabot does not track the Gradle or Maven wrappers or Kubernetes manifests, and cannot group a Maven parent with a Gradle plugin into one pull request. For a repository with one build tool and no containers, Dependabot is enough, and the pull request says so; this one has two builds, two wrappers, Compose and Kubernetes.
Does Renovate need anything installed in the repository?
Only the renovate.json the pull request adds. Renovate itself runs as the Mend-hosted GitHub App, which a maintainer installs on the repository, or as a self-hosted job; the agent cannot install an app from its sandbox, so that step is the first line of the pull request.
Will it update the untagged container image?
No. Renovate tracks versions, and dsyer/petclinic with no tag has none; config:best-practices would pin it to a digest and then update the digest, and the pull request describes that option without turning it on.
Why group Spring Boot across both builds?
Because the Maven parent and the Gradle plugin are the same release, and two separate pull requests can each pass CI and leave the two builds on different versions after merge. The groupName rule puts both changes in one pull request, which is what a reviewer wants to look at once.
What does the validator check?
renovate-config-validator loads the file the way Renovate does and reports unknown options, bad regular expressions in managerFilePatterns and deprecated keys. It does not know your repository, so the agent also checks each pattern against the real paths with a shell glob before opening the pull request.
More Gradle jobs
The same job on other stacks
- Set Up Renovate for a Temporal TypeScript Monorepo (Temporal)
- Add Renovate to a Terraform Module Repository (Terraform)
- Set Up Renovate for an Ansible Role (Ansible)