All jobs

Add ansible-lint to CI for an Ansible Role

Yes. An agent runs ansible-lint on your role, fixes what the production profile flags, adds a lint job beside yamllint in CI and opens a PR with the output.

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 how the role is already checked before it adds a tool. In a role shaped like geerlingguy/ansible-role-docker, .github/workflows/ci.yml has a lint job that installs only yamllint on Python 3.13 and runs yamllint ., and a molecule job that installs ansible, molecule, molecule-plugins[docker] and docker and runs molecule test across a matrix of distributions from rockylinux10 to opensuseleap15. A .ansible-lint file already exists with a skip_list of yaml, risky-shell-pipe and role-name, but no job runs ansible-lint, so the file is a promise nobody checks. .yamllint extends default with a 200-character line limit.

It installs ansible-lint in the sandbox and runs it on the role with the production profile to see what the role looks like to the tool today. The tasks files give it plenty to read: tasks/main.yml uses short module names such as include_vars, package, file, copy, service, getent, set_fact and meta, which the fqcn rules ask to be written as ansible.builtin.*; the include_tasks entries that pull in the per-distribution setup files carry no name; mode: 0755 and mode: 0644 are unquoted octal values; ignore_errors: "{{ ansible_check_mode }}" is what the ignore-errors rule is about; and molecule/default/converge.yml has a free-form apt: update_cache=yes cache_valid_time=600 task and a # noqa 303 comment in the old numeric form. tasks/setup-Debian.yml already uses ansible.builtin.file, ansible.builtin.apt and ansible.builtin.deb822_repository, so the role is part way there.

The agent fixes what the role's own conventions allow: it rewrites short module names to their ansible.builtin names, quotes the octal modes, names the unnamed includes, replaces the free-form apt with its key-value form, and updates the noqa comment to the rule's current id. Where a finding is a design choice, such as ignore_errors tied to check mode, it leaves the code and adds the rule to skip_list in .ansible-lint with a comment saying why. Then it adds an ansible-lint job to ci.yml beside lint, installing ansible-lint with pip and running it on the role with the same working-directory the other jobs use.

It runs yamllint . and ansible-lint once more to show both pass, runs molecule test for one distribution to show the renamed modules still converge, and opens a pull request with the lint output before and after, so a reviewer sees exactly which rules fired and which were skipped on purpose.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add ansible-lint to this role's CI. Run ansible-lint with the production profile first and keep the output. Fix the findings that are mechanical: fully qualified module names, unnamed tasks, unquoted octal modes, free-form module arguments and outdated noqa comments. For findings that reflect a deliberate choice, add the rule to skip_list in .ansible-lint with a one-line reason instead of changing the code. Add an ansible-lint job to the CI workflow next to the yamllint job. Run yamllint and ansible-lint again to show they pass and run molecule test for one distribution to show the role still converges. Open a pull request with the before and after lint output.",
  "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. The diff touches the tasks, handlers and Molecule playbooks for the mechanical fixes, .ansible-lint for any rule skipped on purpose with its reason, and .github/workflows/ci.yml for the new job. The description pastes the first ansible-lint run, grouped by rule, and the final run that reports no violations, so the reviewer sees what changed and what was accepted.

The run's record keeps every command: the pip install with the ansible-lint version it used, both lint runs, yamllint ., and the molecule test session for the distribution it picked, with the converge and verify steps. A new CI job on the pull request runs the same lint on GitHub's runner, and the pull request is not done until that job passes there too.

Before merging, a reviewer reads the skip_list additions, because each one is a rule the team is choosing not to enforce, checks that the renamed modules are still ones the role's min_ansible_version in meta/main.yml supports, and decides whether the production profile or a looser one is the right bar for the repository.

Run it on every pull request

Once the job is in ci.yml, GitHub runs it on every pull request without Rush. To have an agent fix what it finds, add an automation in the console with a github trigger on pull_request.opened and pull_request.synchronize: one run per push, with the pull request as its context, which runs ansible-lint on the branch and pushes the mechanical fixes to it, as the prompt says.

From your own server, the same work is one POST /o/{org}/sessions with the repository, or the pull request URL, in resources. A webhook on the API key posts run.completed or run.failed when the turn finishes, with the session_url to read the lint output and the pull request link.

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

Why run it on Rush?

Lint fixes on a role are only safe if the role still converges afterwards, and that takes a container with systemd and a Docker install, which is what Molecule's geerlingguy/docker-*-ansible images provide. The sandbox runs Docker, so the agent can run molecule test the same way CI does and keep the log, instead of asking the reviewer to trust a rename.

The first ansible-lint run on an older role is long, and most of it is mechanical. Handing that run to an agent produces a pull request where every rule either has a fix in the diff or a reason in skip_list, with the before and after output as proof, and leaves the judgement calls to the reviewer.

Frequently asked questions

Which profile does it use?

The prompt says production, which is the strictest of ansible-lint's built-in profiles. If the first run turns up findings the team does not want to hold the role to, the pull request can switch the job to shared or safety; the agent writes the profile into .ansible-lint so CI and local runs agree.

Will it rename modules my minimum Ansible version does not have?

No. ansible.builtin.* names exist in every version the role's min_ansible_version of 2.15.1 allows. A rule that would require a newer collection goes to skip_list with a note rather than into the diff.

Does the new job slow CI down?

It runs in parallel with the existing lint and molecule jobs, installs one Python package and lints a few dozen YAML files, so it finishes well before the Molecule matrix does.

Can it run on a playbook repository instead of a role?

Yes. The same rules apply to playbooks and collections, and the agent points ansible-lint at the repository root. The pull request shape is the same: fixes, a skip_list with reasons, and a CI job.

More Ansible jobs

More jobs like this: Hand off a long task

Keep reading