All jobs

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 RushOpens 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 with this body:

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

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

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

More jobs like this: Hand off a long task

Keep reading