All jobs

Add pre-commit Hooks to an Ansible Role

Yes. An agent adds a pre-commit config with yamllint and ansible-lint on the role's own settings, makes CI run the same hooks, runs them once 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 what already lints the role before it adds a hook. In a role like geerlingguy/ansible-role-docker, the tasks are split across tasks/main.yml, setup-Debian.yml, setup-RedHat.yml, setup-Suse.yml, docker-compose.yml and docker-users.yml, with per-distribution variables under vars/ and defaults in defaults/main.yml. A .yamllint extends the default rules with a line-length of 200 at warning level and ignores .github/workflows/stale.yml. A .ansible-lint skips yaml, risky-shell-pipe and role-name, but nothing runs ansible-lint: the lint job in .github/workflows/ci.yml installs only yamllint and runs yamllint ., and the molecule job runs molecule test across a matrix of seven distributions with the Docker driver. There is no .pre-commit-config.yaml. The tasks mix short module names such as include_vars, package, copy and service with fully qualified ones such as ansible.builtin.systemd_service, and one command task carries a # noqa 303 comment, so the agent expects ansible-lint to have something to say.

It writes a .pre-commit-config.yaml with three repositories: pre-commit/pre-commit-hooks for end-of-file-fixer, trailing-whitespace and check-yaml, adrienverge/yamllint so the hook reads the role's .yamllint unchanged, and ansible/ansible-lint, which reads .ansible-lint and runs with the role checked out under its own name, the way ci.yml checks it out into a geerlingguy.docker directory. Each rev is pinned to the tag the agent reads from the hook repository, and default_language_version names the Python the CI job uses, 3.13, so the hooks and CI agree on an interpreter. The molecule/ directory is left to Molecule: its playbooks use apt: update_cache=yes key-value syntax and a role: reference that ansible-lint would flag outside a Molecule run, so the config excludes that path for the ansible-lint hook and says so in a comment.

Then the agent makes CI run the same thing. The lint job's pip3 install yamllint and yamllint . steps become pip3 install pre-commit and pre-commit run --all-files, with a cache on ~/.cache/pre-commit keyed on the config file so hook environments are not rebuilt on every push; the molecule and release workflows are not touched. A short Development section in README.md tells a contributor to run pip install pre-commit and pre-commit install once. Rules ansible-lint reports that the agent is not asked to fix, such as the fqcn findings on the short module names, go into warn_list in .ansible-lint with a comment, so the hook passes while still printing them, and the pull request lists every finding by file and line for a follow-up.

In the sandbox the agent installs pre-commit, runs pre-commit run --all-files, which builds each hook's own environment and needs no Docker, reads the output, fixes what the hooks fix on their own, trailing whitespace and missing final newlines, and runs the hooks a second time to show a clean pass. Molecule is not run, since it needs Docker and the distribution images, and the pull request says so.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add pre-commit hooks to this Ansible role. Read .yamllint, .ansible-lint, .github/workflows/ci.yml, the tasks and the molecule directory first. Write a .pre-commit-config.yaml with the pre-commit-hooks basics, yamllint using the existing .yamllint, and ansible-lint using the existing .ansible-lint, with each rev pinned to the current tag and the Python version CI uses. Exclude the molecule directory from the ansible-lint hook and explain why in a comment. Change the lint job in ci.yml to install pre-commit and run pre-commit run --all-files with a cache, leave the molecule and release workflows alone, and add a Development section to README.md. Do not rewrite tasks to fix ansible-lint rules; put any rule you did not fix in warn_list with a comment and list the findings in the pull request. Install pre-commit in the sandbox, run all hooks until they pass, and open a pull request.",
  "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 that adds .pre-commit-config.yaml, changes .github/workflows/ci.yml, .ansible-lint and README.md, and includes whatever whitespace fixes the hooks applied to the YAML files. The description pastes the final pre-commit run --all-files output, lists the ansible-lint findings that were moved to warn_list with file and line, and names the hook versions it pinned.

The run's record keeps the first hook run with every finding and the second with the clean pass, so a reviewer can see what the hooks changed and what they merely reported.

Before merging, a reviewer decides which warn_list entries should become real fixes in a second pull request, checks that the CI cache key suits the organization's runner setup, and confirms the lint job still runs before molecule the way the workflow's job list orders them.

Run it on every new role in the organization

In the console, an automation in the Project that has the repository, with a github trigger on pull_request.opened and branch_patterns for your default branch, starts one run per pull request with the pull request as its context; the prompt tells the run to add the hooks when the repository has no .pre-commit-config.yaml and to run the existing hooks on the changed files otherwise. A team with one Project per role can start the same automation in each.

From your own server, the same work is one POST /o/{org}/sessions per role repository with this body and the repository in resources, with a request_id that is a UUID v5 of the repository name so a retried call returns the run already started. A webhook URL on the API key reports run.completed with the session_url to read the pull request link from.

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

Why run it on Rush?

Adding ansible-lint to a role that has never run it produces a wall of findings, and the usual outcome is either a pull request that rewrites every task or a hook nobody enables. The agent reads the role's existing lint settings, keeps them, separates what the hooks fix on their own from what a human should decide, and makes CI run exactly the hooks a contributor runs, so the two never drift.

The sandbox is its own computer where every hook environment installs cleanly without touching anyone's Python, and both hook runs stay in the run's record with their full output. An organization with dozens of roles can start one run per role at once, each ending in its own pull request with its own list of findings.

Frequently asked questions

Will this rewrite my tasks to fully qualified module names?

No. The prompt forbids it, so the fqcn findings on include_vars, package, copy and service go into warn_list in .ansible-lint and into the pull request as a list. Converting them is a separate job with its own review.

Does the ansible-lint hook also lint the Molecule playbooks?

The agent excludes molecule/ for that hook, because converge.yml uses key-value module arguments and a role: reference that only resolve inside a Molecule run, and the role's own CI already runs molecule test across seven distributions. yamllint still covers those files.

Why pin the hook revisions?

pre-commit requires a rev per repository, and a moving tag would change the rules under contributors' feet. The agent reads the current tag of each hook repository and pins it; pre-commit autoupdate moves them later, and a weekly run with that command is a one-line prompt.

Does the run need Docker for Molecule?

No, and it does not run Molecule. The hooks install into their own virtual environments through pre-commit, which is all the sandbox needs. The molecule job in CI is unchanged and still runs on every pull request, including this one.

More Ansible jobs

The same job on other stacks

Keep reading