# 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 Rush](https://cloud.getrush.ai/run/add-collection-requirements/ansible/). Opens 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`

```json
{
  "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.

## 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

- [Add pre-commit Hooks to an Ansible Role](https://getrush.ai/run/add-pre-commit-hooks/ansible/)
- [Set Up Renovate for an Ansible Role](https://getrush.ai/run/add-renovate/ansible/)
- [Fix "The 'ansible.builtin.include' action plugin has been removed" in an Ansible playbook](https://getrush.ai/run/fix-ansible-include-action-removed/ansible/)

## More jobs like this: Hand off a long task

- [Add Command Palette Commands to a Textual App](https://getrush.ai/run/add-command-palette/textual/)
- [Generate compile_commands.json for a Bazel C++ Project](https://getrush.ai/run/add-compile-commands/bazel/)
- [Add the Mandatory Compliance Webhooks to a Shopify App](https://getrush.ai/run/add-compliance-webhooks/shopify-app/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
