All jobs

Declare the Collections an Ansible Role Depends On

Yes. An agent finds every module your role uses outside ansible-core, writes a requirements.yml that pins their collections, installs it in CI and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the repository into its own cloud sandbox and reads every task file before it writes anything. In a role like geerlingguy/ansible-role-docker, tasks/main.yml loads OS vars with include_vars and first_found, includes setup-RedHat.yml, setup-Suse.yml or setup-Debian.yml, installs docker_packages with package, writes /etc/docker/daemon.json with copy, patches the unit file with ansible.builtin.systemd_service and ansible.builtin.replace, and reads the docker group with getent. setup-Debian.yml already uses fully qualified names (ansible.builtin.deb822_repository, ansible.builtin.apt, ansible.builtin.file); setup-RedHat.yml uses short names (rpm_key, get_url, ini_file), and setup-Suse.yml uses zypper_repository and ansible.legacy.zypper. meta/main.yml says min_ansible_version: 2.15.1 and lists no collections, the README says Requirements: None, and there is no requirements.yml anywhere.

It then resolves each short module name to the collection that ships it, using ansible-doc in the sandbox rather than memory: ini_file, zypper_repository and zypper live in community.general, while package, get_url, rpm_key, getent, user, copy, file, replace, service and systemd_service are ansible.builtin. That finding is the point of the job: a user who installs only ansible-core and runs this role on openSUSE or Fedora gets a couldn't resolve module/action error on the first task that needs community.general, and nothing in the repository tells them so. The agent also checks the two handlers in handlers/main.yml and the three Molecule playbooks under molecule/default/, whose verify.yml uses command and debug only.

With the list in hand it writes requirements.yml at the repository root with a collections entry for community.general, pinned with a version range the agent takes from the version ansible-doc resolved in the sandbox, and adds the same collection under a collections key in meta/main.yml so the short names resolve when the role is used from a playbook that does not list it. It changes the Requirements section of README.md from None to the collection and the ansible-galaxy collection install -r requirements.yml command, and it adds that install step to both jobs in .github/workflows/ci.yml, after pip3 install ansible molecule molecule-plugins[docker] docker in the Molecule job and alongside yamllint in the lint job. Because the CI job already installs the full ansible package, which bundles community.general, the step changes nothing for the matrix today, and the pull request says so; the step is there so the pin is exercised.

It leaves the short module names alone rather than rewriting them to fully qualified names, since that is a separate change with its own review, and notes in the pull request which files still use short names. It runs yamllint . with the repository's .yamllint (line length 200, warning level) and ansible-lint with the .ansible-lint skip list (yaml, risky-shell-pipe, role-name) to make sure the new files pass, and it runs ansible-galaxy collection install -r requirements.yml once in the sandbox to prove the file parses and the pin resolves.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Find every module and plugin this Ansible role uses that is not part of ansible-core, using ansible-doc in the sandbox to resolve each short name. Write a requirements.yml at the repository root that pins the collections they come from, add the same collections to meta/main.yml, replace the Requirements section of the README with the collection list and the install command, and add an `ansible-galaxy collection install -r requirements.yml` step to every CI job that runs the role. Do not rename modules to fully qualified names. Run yamllint and ansible-lint with the repository's configuration and open a pull request that lists which task file needs which collection.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. 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.
  2. 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.
  3. 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 on its own branch that adds requirements.yml, changes meta/main.yml, README.md and .github/workflows/ci.yml, and leaves every task file as it was. The description has a table of module name, task file and collection, built from the ansible-doc output in the sandbox, so a reviewer can see why community.general is there and that nothing else is needed.

The run's record keeps each command with its output: the ansible-doc calls that resolved the names, the yamllint and ansible-lint runs on the repository's own configuration, and the ansible-galaxy collection install that resolved the pin.

Before merging, a reviewer decides how tight the version pin should be for a role published to Galaxy, whether the Molecule job should install ansible-core plus the requirements instead of the full ansible package so CI matches what the README now promises, and whether the role's Galaxy metadata should mention the dependency as well.

Run it on every role released to Galaxy

The release workflow in a role like this one runs on every pushed tag and imports the role into Galaxy. A handler on your server that receives GitHub's release or push webhook for a tag sends one POST /o/{org}/sessions with this body and the repository in resources, with a request_id that is a UUID v5 of the delivery id, so a redelivered webhook does not start a second run. The run opens a pull request when a new task uses a module from a collection the requirements file does not list, and ends with a result that says nothing is missing otherwise.

For a team with many roles, GET /o/{org}/github lists every repository the Rush GitHub App installation can reach, and a script sends one request per role repository. Each run reads that role's own task files, so a role that uses community.docker or ansible.posix gets those collections in its own file.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The missing collection only shows up on a machine that does not happen to have it, which is never the author's laptop and usually a user's fresh ansible-core install. The agent resolves every module name with ansible-doc in a clean sandbox, where nothing is installed that the repository did not ask for, and the result is a list with a source for each line instead of a guess from memory.

The sandbox is its own computer with Python, Ansible and the linters the role's CI uses, and the record of every command stays with the run. Several roles can be checked at once in separate sandboxes, each ending in its own pull request with its own collection list.

Frequently asked questions

Will this change how the role behaves?

No. The task files are untouched and the short module names still resolve the same way. The change makes the dependency explicit in requirements.yml and meta/main.yml, adds an install step to CI, and corrects the README, so a user on ansible-core installs the collection before the first run instead of hitting an unresolved module on openSUSE or Fedora.

Why not also convert the short names to fully qualified ones?

That is a different change with a larger diff and its own lint rule, and the repository already does it file by file, for example in setup-Debian.yml. The prompt asks the agent not to, and the pull request lists which files still use short names so that work can be a follow-up.

How does the agent know which collection a module comes from?

It runs ansible-doc for each module name in the sandbox and reads the collection the output reports, then records the collection version that is installed. Modules that resolve to ansible.builtin are left out of the requirements file.

What about roles that use lookup or filter plugins from a collection?

The agent searches the task files, vars and templates for lookup(, query( and filters as well as modules, and resolves those with ansible-doc -t lookup and -t filter. In this role the only lookup is first_found, which is built in.

More Ansible jobs

More jobs like this: Hand off a long task

Keep reading