# Migrate an Ansible Role to Fully Qualified Collection Names

Yes. An agent rewrites every short module name in your Ansible role to its fully qualified collection name, records the collections it now needs and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-to-fqcn/ansible/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the role file by file and sorts each module reference into one of three groups. In a role shaped like geerlingguy/ansible-role-docker the picture is mixed: tasks/setup-Debian.yml is already fully qualified, using `ansible.builtin.file`, `ansible.builtin.apt`, `ansible.builtin.deb822_repository` and `ansible.builtin.meta`, and handlers/main.yml uses `ansible.builtin.service` and `ansible.builtin.apt`. But tasks/main.yml still calls `include_vars`, `include_tasks`, `package`, `file`, `copy`, `service`, `meta`, `getent` and `set_fact` by their short names while the block that patches docker.service uses `ansible.builtin.systemd_service` and `ansible.builtin.replace`, and tasks/setup-RedHat.yml, tasks/setup-Suse.yml, tasks/docker-compose.yml and tasks/docker-users.yml are entirely short: `rpm_key`, `get_url`, `ini_file`, `zypper_repository`, `command`, `systemd`, `user`.

The first group is everything that lives in ansible.builtin, and those become `ansible.builtin.<name>` with no other change. The second group is the reason this job needs care: `ini_file` in setup-RedHat.yml and `zypper_repository` in setup-Suse.yml are not builtin modules, they ship in the community.general collection, and the odd `ansible.legacy.zypper` reference in setup-Suse.yml resolves to community.general.zypper too. Writing those names out makes a dependency visible that the short names hid: the role works today because the molecule job in .github/workflows/ci.yml runs `pip3 install ansible`, the package that bundles community collections, while meta/main.yml says `min_ansible_version: 2.15.1` and lists no collections. The agent adds a meta/requirements.yml, or a `collections` entry, naming community.general, and a sentence in README.md's Requirements section, which currently says None, so a user on ansible-core alone knows to install it.

The third group is the action plugins and keywords that look like modules but are not renamed the same way: `meta: flush_handlers` and `meta: reset_connection` become `ansible.builtin.meta`, `include_tasks` and `include_vars` keep working as `ansible.builtin.include_tasks` and `ansible.builtin.include_vars`, and `set_fact` becomes `ansible.builtin.set_fact`. The agent does not touch the `when`, `notify`, `register` or `with_items` lines, and it leaves molecule/default/converge.yml alone unless asked, since the `apt` and `command` there are test scaffolding. It then runs `ansible-lint` in the sandbox before and after with the repository's .ansible-lint, which skips only `yaml`, `risky-shell-pipe` and `role-name`, so the fqcn rules are live, and reports the counts of `fqcn[action-core]`, `fqcn[action]` and `fqcn[canonical]` findings each way.

Proof comes from the tools the repository already uses. `yamllint .` with the repository's .yamllint, which is what the lint job in ci.yml runs, must stay clean; `ansible-playbook --syntax-check` on a play that applies the role confirms every fully qualified name resolves with the community.general collection installed; and `ansible-lint` should report no fqcn findings after the change. The molecule matrix across seven distributions needs privileged Docker containers and runs on the pull request's own CI, where it runs today; the agent does not claim to have run it in the sandbox.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Migrate this Ansible role to fully qualified collection names. Read meta/main.yml, defaults/main.yml, handlers/main.yml, every file under tasks/ and vars/, molecule/default/molecule.yml and converge.yml, .ansible-lint, .yamllint, README.md and .github/workflows/ci.yml first, and list every module reference with its file and whether it is already qualified. Rewrite every short name to ansible.builtin where the module lives there, and to community.general for ini_file, zypper_repository and the ansible.legacy.zypper reference, changing nothing else on those tasks. Add a meta/requirements.yml naming community.general and update the Requirements section of README.md to say it is needed on ansible-core alone. Leave molecule/default/converge.yml unchanged. Run ansible-lint with the repository config before and after and report the fqcn finding counts, run yamllint ., and run ansible-playbook --syntax-check on a play that applies the role with community.general installed. Do not run molecule; say that the matrix runs on the pull request. Open a pull request with the file-by-file list and the lint counts.",
  "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 edits tasks/main.yml, tasks/setup-RedHat.yml, tasks/setup-Suse.yml, tasks/docker-compose.yml and tasks/docker-users.yml, adds meta/requirements.yml, and changes one line in README.md. tasks/setup-Debian.yml and handlers/main.yml are untouched because they were already qualified, and the description says which files needed nothing.

The description carries a table of every renamed module with its file, old name and new name, with the community.general rows marked, and quotes the ansible-lint counts before and after, the yamllint result and the syntax check. It explains in one paragraph why `zypper_repository` and `ini_file` make community.general a stated dependency, and that `pip3 install ansible` in ci.yml already provides it.

A reviewer reads the community.general rows first, decides whether the role should declare the collection in meta/main.yml, in requirements.yml or both, and waits for the molecule matrix on the pull request to pass on all seven distributions, because a misspelled fully qualified name fails at task load time and that run is where it would show.

## Run it on every role still on short module names

A maintainer of many roles starts one run per repository: a `POST /o/{org}/sessions` with this prompt and that repository in `resources`, with a `request_id` per repository so a retried request returns the run it already started. Each run reads its own tasks, so a role that only uses builtin modules gets no new dependency and a role that uses `community.docker` or `community.general` gets it named.

Give the key a webhook URL and Rush posts `run.completed` or `run.failed` when each turn ends, with the `session_url` for the record. A team can also run this as a schedule on one Project, once a quarter, so new tasks written with short names are caught before ansible-lint's fqcn rules turn into errors in a future release.

## Why run it on Rush?

The rename itself is mechanical; the judgement is in the modules that are not builtin. Writing `ansible.builtin.ini_file` would pass a text review and fail at task load, and the only way to know which collection owns a module is to resolve it against installed collections and run the linter. The agent does that in its own sandbox with ansible-core, community.general and ansible-lint installed, and the before-and-after counts come from the tool, not from a reading of the diff.

The record stays with the pull request: the per-file list, both ansible-lint runs, yamllint and the syntax check are in the run's transcript with their output. The molecule matrix stays where it is, on the repository's own CI, and the agent says so instead of claiming a container test it did not run.

## Frequently asked questions

### Which modules in this role are not in ansible.builtin?

ini_file and zypper_repository, used in tasks/setup-RedHat.yml and tasks/setup-Suse.yml, and the ansible.legacy.zypper reference, which resolves to community.general.zypper. They have worked because the CI installs the ansible package, which bundles community.general; the pull request makes that dependency explicit.

### Does this change what the role does on any distribution?

No. A fully qualified name resolves to the same module the short name did, and the agent changes nothing else on those tasks. The molecule matrix on the pull request, across the seven distributions in ci.yml, is the check that nothing was mistyped.

### Will it edit the molecule playbooks too?

Not by default. molecule/default/converge.yml uses apt and command as test scaffolding and is left alone unless the prompt asks, so the diff stays within the role's own tasks and metadata.

### Why does ansible-lint matter here?

Its fqcn rules are what flag short names, and the repository's .ansible-lint does not skip them. Running it before and after gives a count that goes to zero for those rules, which is a cleaner proof than reading the diff, and it also catches a module that was renamed to a collection that is not installed.

### Can it run the molecule tests in the sandbox?

The molecule scenario uses the Docker driver with privileged containers and a host cgroup namespace, which is what the pull request's CI provides. The agent runs ansible-lint, yamllint and a syntax check in the sandbox and leaves the matrix to the pull request, and says so in its description.

## More Ansible jobs

- [Review Pull Requests on an Ansible Role](https://getrush.ai/run/review-pull-requests/ansible/)
- [Upgrade Ansible Collections and Fix Lint](https://getrush.ai/run/upgrade-ansible-collections/ansible/)
- [Write Molecule Tests for an Ansible Role](https://getrush.ai/run/write-molecule-tests/ansible/)

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

- [Migrate an Echo App From GORM v1 to GORM v2](https://getrush.ai/run/migrate-to-gorm-v2/echo/)
- [Migrate a Gradle Build to the Kotlin DSL](https://getrush.ai/run/migrate-to-kotlin-dsl/gradle/)
- [Migrate a Gatsby Blog from Markdown to MDX](https://getrush.ai/run/migrate-to-mdx/gatsby/)

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