# 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 Rush](https://cloud.getrush.ai/run/add-pre-commit-hooks/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 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`

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

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

- [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/)
- [Fix a Failing Molecule CI Run for an Ansible Role](https://getrush.ai/run/fix-failing-ci/ansible/)

## The same job on other stacks

- [Add pre-commit Hooks to a CMake C++ Project](https://getrush.ai/run/add-pre-commit-hooks/cmake/)
- [Add dbt-checkpoint Pre-commit Hooks to a dbt Project](https://getrush.ai/run/add-pre-commit-hooks/dbt/)
- [Add Pre-commit Hooks to a Kubernetes Manifest Repository](https://getrush.ai/run/add-pre-commit-hooks/kubernetes/)

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