What the agent does
The agent reads how the role is tested before it adds a dimension. In a role like geerlingguy/ansible-role-docker, .github/workflows/ci.yml has a lint job that runs yamllint . on Python 3.13 and a molecule job on ubuntu-latest with a distro matrix of rockylinux10, ubuntu2404, ubuntu2204, debian13, debian12, fedora43 and opensuseleap15, installing ansible, molecule, molecule-plugins[docker] and docker with pip and running molecule test with MOLECULE_DISTRO set per entry, on pull requests, pushes to master and a Sunday schedule. molecule/default/molecule.yml uses the Docker driver with image: geerlingguy/docker-${MOLECULE_DISTRO:-rockylinux9}-ansible:latest, pre_build_image: true, privileged: true and cgroupns_mode: host; converge.yml waits for systemd to report running before applying the role; verify.yml runs docker version, checks systemctl is-active docker and pulls hello-world, with the docker run step commented out because of Docker-in-Docker quirks on GitHub Actions.
It then reads what in the role is architecture-sensitive. defaults/main.yml installs docker-ce, docker-ce-cli, docker-ce-rootless-extras, containerd.io and docker-buildx-plugin from download.docker.com, which tasks/setup-Debian.yml adds as a deb822_repository with the distribution release as the suite, so the package architecture follows the host. The optional standalone Compose download uses docker_compose_arch: "{{ ansible_facts.architecture }}" in the release URL docker-compose-linux-{{ docker_compose_arch }}, which on an arm64 host becomes aarch64, the name the Compose project publishes. meta/main.yml lists Debian, Ubuntu, Fedora, Alpine, Arch and SUSE platforms with no architecture claim, and README.md documents the variables without saying the role has been run on arm.
The change is a second matrix axis and the checks that make it safe. The molecule job gains runner: [ubuntu-latest, ubuntu-24.04-arm] with runs-on: ${{ matrix.runner }}, and the job name shows both values. Before adding a distro to the arm side, the agent inspects each image's manifest with docker buildx imagetools inspect and adds a matrix exclude for any image that publishes no linux/arm64 variant, listing the result in the pull request. verify.yml gains a task that asserts the architecture docker version reports matches ansible_facts.architecture, so a run that silently pulled an amd64 image under emulation fails. The README gets a line under the CI badge saying the role is tested on both architectures, and meta/main.yml is unchanged because Galaxy has no field for it.
The proof is split between the sandbox and the pull request's own checks. In the sandbox the agent installs Docker with sudo apt-get install -y docker.io, starts dockerd, and runs molecule test for one amd64 distro to show the new verify.yml task passes and that nothing else in the scenario changed. It cannot run an arm64 systemd container locally, so the arm64 half is proven by the workflow runs the pull request itself triggers, and the description links the checks and says which combinations were excluded and why.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add arm64 CI to this Ansible role. Read the CI workflow, the Molecule scenario, the role's defaults, tasks, vars and meta, and the README first. Add an arm64 GitHub-hosted runner as a second matrix axis for the Molecule job, inspect the manifest of every test image and exclude from the arm64 side any that has no linux/arm64 variant, listing the result. Add a verify task that asserts the Docker daemon's reported architecture matches the host's so an emulated image cannot pass unnoticed. Note in the README that the role is tested on both architectures. Install Docker in the sandbox, run molecule test for one amd64 distro to show the scenario still passes, and include the output; say that the arm64 runs are proven by the pull request's own checks. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 changes .github/workflows/ci.yml (the runner axis, runs-on, the job name and any exclude entries), molecule/default/verify.yml (the architecture assertion) and README.md (one line). The role's tasks, defaults and meta/main.yml are unchanged, because the role already follows the host architecture.
The description lists each test image with the platforms its manifest publishes, the exclusions that follow, and the molecule test output for the amd64 distro run in the sandbox. The pull request's checks then show the matrix running on both runners. The commands and full output are in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a reviewer reads the arm64 job logs for the distros that ran, decides whether the weekly scheduled run should include the arm side or only pull requests, and whether an image without an arm64 variant is worth an upstream request. A follow-up message to the same session can add a second scenario that sets docker_install_compose: true to exercise the Compose download on arm.
Run it on every Ansible role you maintain
A maintainer with many roles, like the author of this one, starts one run per repository with one POST /o/{org}/sessions each, the repository in resources and this prompt as input. Each run reads its own matrix and images, so a role tested on Podman or with a different image family gets the same treatment on its own terms, and each opens its own pull request.
A key runs at most max_concurrent runs at once, four by default; a run past that answers 202 with status: "queued" and starts when a slot frees. Send a request_id, a UUID v5 of the repository's full name, so a retried call returns the run it already started.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Adding an arm64 runner is one line; knowing which test images will fail to pull, which role variables depend on the architecture and how to catch an emulated image is the work. The agent reads the scenario and the role, inspects every image manifest, and runs the scenario once with Docker installed in a sandbox of its own, with the output kept.
The pull request carries the manifest table and the amd64 run, and its own checks carry the arm64 proof, so the review is a read of the job logs. Many roles can be done at once, each in its own sandbox, each with its own pull request.
Frequently asked questions
Are arm64 GitHub-hosted runners available for my repository?
GitHub offers arm64 Ubuntu runners as a runs-on label; the agent uses the public label and the pull request's checks show whether the job was picked up. If the repository's plan has no arm runners, the job stays queued and the description says what to change, such as a self-hosted runner label.
What if a test image has no arm64 variant?
The agent inspects every image manifest before adding it to the arm side and writes an exclude entry for each image that only publishes linux/amd64, listing them in the pull request. Running such an image on arm64 would either fail to pull or run under emulation, which the new verify task would catch.
Does the role itself need changes for arm64?
Not in a role like this one, where the packages come from the distribution's repository for the host architecture and the Compose download URL uses ansible_facts.architecture. The agent reads the tasks and vars to confirm that and says so; a role that hard-codes amd64 in a URL would get that fixed in the same pull request.
Why run one distro locally instead of the whole matrix?
The sandbox can run amd64 systemd containers once Docker is installed, so one distro proves the scenario and the new verify task work. Arm64 containers would need emulation, which is what the verify task is designed to reject, so the arm half is proven by the workflow the pull request triggers.
More Ansible jobs
More jobs like this: Hand off a long task
- Add Build Provenance Attestations to a Rust CLI's Release Workflow (Rust CLI)
- Add Are the Types Wrong to CI for a TypeScript Library (TypeScript library)
- Add an Audit Log to a Fastify API (Fastify)