Tooling

The build, test, and CI infrastructure that supports the engine.

ansible-test

ansible-test is a peer to ansible-core. It's packaged separately at test/lib/ansible_test/, exported as a console script via pyproject.toml:

[project.scripts]
ansible-test = "ansible_test._util.target.cli.ansible_test_cli_stub:main"

When installed, ansible-test is a separate binary on $PATH. From the source tree, bin/ansible-test is a symlink that runs the stub directly.

The tool is discussed in Testing. Internally it's structured as:

Path	Role
test/lib/ansible_test/_util/target/cli/	Entry-point stubs and command dispatch
test/lib/ansible_test/_internal/	Core logic — sanity test plugins, container drivers, requirement resolvers
test/lib/ansible_test/_data/	Per-test data: requirements files, container manifests, sanity rules
test/lib/ansible_test/config/	Default config files copied into test environments
test/sanity/	Sanity test definitions outside the package, where each test has its own subdirectory

Sanity test plugins

Each sanity test is a small module under test/sanity/code-smell/ (Python-implemented) or has its data declared via test/sanity/ignore.txt and per-version variants. Common plugin types:

• AST-walking lint plugins (no smart quotes, boilerplate header, future imports).
• External-tool wrappers (pep8, pylint, mypy, validate-modules, yamllint).
• Structural validators (bin-symlinks, runtime-metadata).
• Manifest tests (pylint, pep8 per Python version).

test/sanity/ignore.txt is the structured allowlist of pre-existing failures. New errors aren't added to it; the canonical fix is to clean up the underlying code.

CI: Azure Pipelines

Continuous integration runs on Azure DevOps, configured by .azure-pipelines/azure-pipelines.yml. The pipeline definition pulls in templates from .azure-pipelines/templates/ and reusable scripts from .azure-pipelines/scripts/:

Pipeline area	Files
Top-level pipeline	.azure-pipelines/azure-pipelines.yml
Job templates	.azure-pipelines/templates/
Helper scripts (run inside jobs)	.azure-pipelines/scripts/
Per-platform integration commands	.azure-pipelines/commands/

The pipeline runs (in parallel where possible):

• Sanity Test 1 / 2 (sanity test set is split for parallelism).
• Units across each supported Python version.
• Integration tests across many distro containers.
• Windows integration via WinRM/PSRP.
• Network integration for in-tree smoke tests.

Builds run on every PR. Build IDs are visible via gh pr checks <pr>.

ansibot

ansibot is a GitHub bot that lives outside this repo (its source is in the ansible/ansibullbot project). It:

• Auto-assigns reviewers based on the PR's component name field and CODEOWNERS-style maps.
• Comments on PRs with structured CI-failure summaries (sanity errors with file:line, etc.).
• Adds and removes labels (bot_status/..., needs_revision, needs_ci).
• Triages stale PRs/issues.

When debugging a CI failure, the bot's comment is the first place to look. It includes file:line references and a link to the relevant sanity-test documentation.

Azure log fetcher

hacking/azp/download.py fetches Azure Pipelines build logs locally for grepping. Common invocation:

./hacking/azp/download.py <build_id> --console-logs

This drops the per-job console logs into <build_id>/. The script also supports filtering:

./hacking/azp/download.py <build_id> --console-logs --match-job-name "Sanity.*"
./hacking/azp/download.py <build_id> --all   # also pulls artifacts and metadata

The /azp-logs <pr_number> slash command (defined in .claude/skills/azp-logs/) wraps this for AI-assistant flows that want to triage CI from chat.

hacking/

The hacking/ directory is a grab-bag of contributor-facing scripts:

Script	Purpose
hacking/env-setup	Set $PATH, $PYTHONPATH, and $ANSIBLE_* env vars to run from a checkout
hacking/env-setup.fish	Same, for fish
hacking/test-module.py	Run a single module against a local target with a hand-built AnsiBallZ
hacking/ansible-profile.py	cProfile harness around the controller
hacking/return_skeleton_generator.py	Auto-generate a starting point for a module's RETURN block
hacking/update-sanity-requirements.py	Refresh pinned requirements files for sanity tests
hacking/create-bulk-issues.py	Maintainer tool for filing repetitive tickets
hacking/report.py	Code metrics for release planning
hacking/backport/	Helpers for cherry-picking commits to stable branches
hacking/azp/download.py	Azure Pipelines log fetcher (above)
hacking/ticket_stubs/	Templates for common bug-tracker responses

The hacking/ directory is intentionally not packaged; it's only for working in the source tree.

Build and packaging

Packaging is configured in pyproject.toml:

• Build backend: setuptools.build_meta with setuptools 77.0.3+ (lower bound for PEP 639 license metadata; upper bound 80.3.1 set per release).
• Version is dynamic via tool.setuptools.dynamic.version = {attr = "ansible.release.__version__"}.
• Dependencies are dynamic from requirements.txt.
• Console scripts (ansible, ansible-playbook, etc.) are declared under [project.scripts].
• The package-data block lists every non-Python file shipped (templates, YAML config, embedded PowerShell/C# helpers, Galaxy skeletons).

The MANIFEST.in controls source tarball contents; packaging/ holds extra packaging metadata for distros.

.github

.github/ contains GitHub-side configuration:

• .github/workflows/ — small GitHub Actions, mostly for issue management. The heavy lifting is on Azure Pipelines.
• .github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE/ — required form templates.
• .github/CONTRIBUTING.md — contributor entry doc.
• .github/BOTMETA.yml — ansibot's reviewer/component map.

Cross-links

• Testing for ansible-test flavors.
• Debugging for verbosity, leftover AnsiBallZ archives, and the debug strategy plugin.
• Reference → Configuration for the config option layer the CI exercises.