What the agent does
The agent first finds everything in the role that names a version. In a role laid out like geerlingguy/ansible-role-docker, .github/workflows/ci.yml runs a lint job and a molecule job over a matrix of seven distributions, both on actions/checkout@v4 and actions/setup-python@v5 with Python 3.13 and a comment that 3.14 must wait for Ansible 13; release.yml imports the role into Galaxy on a tag with the same two actions; stale.yml closes inactive issues on a schedule. The pip line in CI installs ansible molecule molecule-plugins[docker] docker with no versions, there is no requirements.yml, meta/main.yml lists no dependencies, and .github/ holds no dependabot.yml and no Renovate config.
The version Renovate's built-in managers cannot see is the one that matters most. defaults/main.yml sets docker_compose_version: "v2.32.1" and builds docker_compose_url from it, pointing at the release download on github.com/docker/compose, and tasks/docker-compose.yml fetches that file with get_url whenever docker_install_compose is true and the installed binary is older. A variable in a YAML defaults file matches no manager, so the agent adds a custom regex manager scoped to defaults/main.yml whose pattern captures the value after docker_compose_version: with datasourceTemplate set to github-releases and depNameTemplate to docker/compose. The molecule/default/molecule.yml image, geerlingguy/docker-${MOLECULE_DISTRO:-rockylinux9}-ansible:latest, has a shell variable in its tag and the latest tag, so no manager can pin it; the agent leaves it and says so in the pull request.
The config it writes to renovate.json extends config:recommended and helpers:pinGitHubActionDigests, so actions/checkout and actions/setup-python get a commit SHA with a version comment, and adds a package rule that groups the GitHub Actions updates into one pull request and a schedule that lands them before the Sunday morning CI cron in ci.yml. It sets no semantic-commit preset, because the role's history does not use that style. .yamllint ignores stale.yml and warns past 200 columns; the new file is JSON, so neither lint reads it, and .ansible-lint's skip list is untouched.
The agent checks the file two ways in its sandbox before opening the pull request. renovate-config-validator, run with npx from the renovate package, parses the config and reports an unknown key or a bad regex. Then renovate --platform=local, which runs against the checked-out directory in dry-run mode and never writes to GitHub, prints which dependencies each manager found and which updates it would open, so the record shows the custom manager matching v2.32.1 and the two actions resolving to digests. Molecule itself is not run: it needs Docker, which the sandbox lacks, and the change touches no task.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Set up Renovate for this Ansible role. Read every file under .github/workflows, meta/main.yml, defaults/main.yml, tasks/docker-compose.yml, molecule/default/molecule.yml, .ansible-lint and .yamllint first. Write renovate.json extending config:recommended with GitHub Action digests pinned, the actions grouped into one pull request, a weekly schedule, and a custom regex manager that tracks docker_compose_version in defaults/main.yml against docker/compose releases on GitHub. Do not try to pin the molecule image tag that contains a shell variable; name it in the pull request instead. Validate the file with renovate-config-validator and run renovate with the local platform in dry-run mode to show which updates it would open, then open a pull request that quotes both outputs and tells the reader the Renovate GitHub App must be installed on the repository.",
"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
What comes back is a pull request with one new file, renovate.json, and no change to tasks, defaults, workflows or molecule files. The description quotes the validator's output and the dry run's list of detected dependencies and pending updates, so the reviewer sees the custom manager found docker_compose_version and that the two actions would move to digests, before Renovate has run once on GitHub.
The record keeps the full dry-run log, including which managers ran and which files each one read, and the description names the two things the config cannot cover: the molecule image tag with a variable in it, and the unpinned pip install in CI, which has no requirements file for a manager to read.
Before merging, a reviewer installs the Renovate GitHub App on the repository, a step a person does on github.com, and decides whether the Compose update should open its own pull request or wait for the next release of the role. Because a config file already exists when the app is installed, Renovate skips its onboarding pull request and uses this one.
Run it on every Ansible role repository
A maintainer with a shelf of roles starts one run per repository from a script: GET /o/{org}/github lists every repository the installation reaches, the script keeps the ones with a meta/main.yml, and each gets this body with its own resources entry and a request_id that is a UUID v5 of the repository's full name, so a second run of the script returns the runs already started rather than doubling them.
Each run reads its own role. One that pins a Compose release in defaults/main.yml gets the custom manager; one with a requirements.yml gets Renovate's ansible-galaxy manager instead; one whose CI already pins actions to digests gets a config without the pinning preset. The pull requests arrive one per role, each with its own dry run in the record.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A Renovate config written from a template without reading the role misses the version that actually goes stale, the Compose binary the role downloads for every host, and either pins nothing or writes a regex that never matches. In a Rush sandbox the agent runs Renovate's own validator and a local dry run against the real files, and reads what the managers found before it opens anything.
The validator and dry-run output stay with the run, so the reviewer reads what Renovate will do rather than guessing from the JSON. Running the same job across every role a maintainer keeps costs one script and an afternoon of reviewing, because each run has its own sandbox, its own log and its own pull request.
Frequently asked questions
Why a custom manager for the Compose version?
Because the version lives in defaults/main.yml as a role variable, not in a lockfile or a Dockerfile, and none of Renovate's built-in managers reads Ansible defaults. The regex manager captures the value after docker_compose_version: and asks the github-releases datasource about docker/compose, so a new Compose release becomes a one-line pull request.
Will Renovate change the molecule image?
No. The image tag in molecule/default/molecule.yml is latest with a shell variable choosing the distribution, and no manager can pin a tag it cannot read. The pull request names it so the maintainer knows it is deliberately left alone.
Why not Dependabot?
Dependabot has no custom manager, so it could update the two GitHub Actions and nothing else in this role. Renovate covers the actions and the Compose release in one config and groups them the way the maintainer wants.
Will the first run open a flood of pull requests?
The dry run in the record shows how many updates are pending before anything is merged, and the config groups the actions into one. A maintainer who wants fewer can lower the open pull request limit or widen the schedule in the same file.
Does the agent run the Molecule tests?
No. Molecule drives Docker, which the sandbox does not have, and the change adds a config file without touching a task, a default or a workflow. CI on the pull request runs the lint job as it always does.
More Ansible jobs
The same job on other stacks
- Add Renovate to Keep Docker Compose Image Tags Current (Docker Compose)
- Add Renovate to a Gradle and Maven Project (Gradle)
- Set Up Renovate for a Temporal TypeScript Monorepo (Temporal)