Ansible Policy & Modernization Engine — a multi-validator static analysis platform for Ansible content. It parses playbooks, roles, collections, and task files into a structured hierarchy, then fans validation out in parallel across independent backends to produce a single, unified list of violations.
APME is a multi-validator static and semi-static analysis platform for Ansible content. It parses YAML once, fans validation out across independent backends (policy, modernization, secrets, dependency health, and more), and can remediate findings — without running tasks or executing against target hosts.
It answers questions like:
- Will this playbook parse on ansible-core 2.19?
- Are any modules I use removed, deprecated, or redirected?
- Do my module arguments match the argspec for the version I'm targeting?
- Does my code follow organizational style and security policies?
- Are there hardcoded credentials in my project?
- What migration work is required to move from one ansible-core version to another?
APME is not a test framework, a deployment tool, or a runtime verification system.
It cannot tell you whether a playbook will achieve its desired outcome on your infrastructure — that depends on target host state, inventory variables, network reachability, and runtime facts that only exist during execution. A clean APME scan means no known incompatibilities were detected — not that every runtime path will succeed.
What still requires execution-time tools:
| Concern | Tool |
|---|---|
| Does the playbook produce the correct end state? | Molecule, integration tests |
| Is the playbook idempotent? | --check mode, Molecule |
| Do templates render correctly with real variables? | Integration tests |
| Does it work with my specific inventory and vault? | Staging dry-run |
APME and these tools are complementary. APME runs in seconds without infrastructure; execution-time tools validate behavior against real systems. Use both.
Not today. Keep using ansible-lint for day-to-day style and best-practice linting in local and CI workflows. APME is not a drop-in replacement.
APME's current focus is the hosted service experience and getting rules, remediation, and AI escalation right — not becoming a substitute for ansible-lint. Deeper GitHub Actions and IDE integration may come later; treat that as aspirational, not a commitment.
The first wave of APME's lint-style rules was informed by a close look at ansible-lint's rule set. APME reimplements those checks itself (it does not run ansible-lint as a subprocess). See rule coverage vs ansible-lint for the matrix.
If you already run ansible-lint, keep it. Evaluate APME for modernization, organizational policy, secrets, dependency health, remediation, and the service path — and revisit whether anything can consolidate later, when the product and integrations warrant it.
APME provides a compatibility and quality floor. It catches the preventable mistakes — the removed module, the broken include:, the wrong argument name, the committed secret — before they reach staging or production.
| When discovered | Cost |
|---|---|
| APME scan in CI | Developer fixes it in their branch |
| Syntax check in staging | Deployment blocked, team context-switches |
| Production run fails | Outage, incident response, postmortem |
For organizations managing hundreds of roles and collections across ansible-core version upgrades, this shift-left is the difference between a planned migration and an emergency one.
- Single parse, multiple validators — parse once, fan out to independent backends
- Parallel validation — Native (Python), OPA (Rego), Ansible (runtime), Gitleaks (secrets), Collection Health, and Dependency Audit run concurrently; latency = max, not sum
- 100+ rules — lint (L), modernize (M), risk (R), policy (P), and secrets (SEC) categories
- Secret scanning — 800+ patterns via Gitleaks with vault/Jinja filtering
- Dependency health — collection quality checks + Python CVE audit via pip-audit
- Multi ansible-core version support — session-scoped venvs per target version
- Automated remediation — deterministic Tier 1 transforms with multi-pass convergence
- AI-assisted fixes — optional Tier 2 escalation via Abbenay for violations without deterministic transforms
- YAML formatter — normalize indentation, key ordering, Jinja spacing with comment preservation
- Structured diagnostics — per-rule timing data (
-vsummary,-vvfull breakdown) - Unified gRPC contract — adding a validator means implementing one RPC
┌─────────┐ gRPC ┌────────────┐ gRPC (parallel) ┌────────────┐
│ CLI │ ──────────────► │ Primary │ ──────────────────────► │ Native │
│ │ │ (orchestr) │ │ OPA │
└─────────┘ │ Engine │ │ Ansible │
│ parse → │ │ Gitleaks │
│ annotate →│ │ Coll.Hlth │
│ fan-out │ │ Dep.Audit │
└─────┬──────┘ └────────────┘
│
┌─────┴─────┐
│ Galaxy │
│ Proxy │ (PEP 503)
└───────────┘
Validator fan-out uses gRPC; Galaxy Proxy is HTTP (PEP 503). The engine parses content once, then validators consume the hierarchy independently and in parallel. See the architecture series for the full pipeline walkthrough.
| Method | Best for | Guide |
|---|---|---|
CLI (pip install) |
Quick evaluation, CI pipelines, single-user | CLI Guide |
| Podman pod | Development, full feature set (UI, AI, persistence) | Deployment Guide |
| bootc VM | Production single-node, atomic upgrades, systemd lifecycle | bootc Guide |
| Helm chart | Kubernetes / OpenShift production | Helm Guide (helm repo add apme https://ansible.github.io/apme) |
pip install apme-engine@git+https://github.com/ansible/apme.git@v2026.4.1
apme check /path/to/your/projectThe CLI automatically starts a local daemon with core validators (Native, OPA, Ansible) and Galaxy Proxy — no full pod required. OPA uses a Podman container by default; set OPA_USE_PODMAN=0 to use a local opa binary, or it is skipped if neither is available. Optional validators (Gitleaks, Collection Health, Dep Audit) are not started by the daemon. See the CLI Guide for full usage, CI integration, and limitations compared to deployment methods.
# Deterministic transforms (Tier 1)
apme remediate /path/to/project
# Include AI-assisted fixes (Tier 2, requires Abbenay)
apme remediate --ai /path/to/projectproto/ gRPC protobuf definitions (.proto files)
src/apme/v1/ Generated Python gRPC stubs (do not edit by hand)
src/apme_engine/
├── cli/ CLI (check, format, remediate, health-check, sbom, suppress)
├── engine/ Project loader (parse, annotate, hierarchy, graph)
├── validators/ Rule implementations (native/, opa/, ansible/, gitleaks/, collection_health/, dep_audit/)
├── daemon/ gRPC server implementations
├── remediation/ Tier 1 transforms + AI escalation
└── venv_manager/ Session-scoped venv lifecycle
src/apme_gateway/ API gateway (FastAPI, REST/WebSocket, SQLite)
src/galaxy_proxy/ Galaxy → PEP 503 wheel proxy
frontend/ React operator UI (Vite + TypeScript)
deploy/ Helm chart + bootc VM image
containers/ Containerfiles + Podman pod config
docs/ Architecture, design, guides, rule reference
| Document | Description |
|---|---|
| CLI Guide | Installation, commands, daemon mode, CI usage, limitations |
| Deployment Guide | Podman, bootc, Helm, and CLI daemon deployment |
| bootc Deployment | Atomic VM image with systemd quadlets |
| Helm Chart | Kubernetes/OpenShift deployment |
| Architecture series | Pipeline walkthrough, container topology, gRPC contracts, scaling |
| Design docs | Remediation engine, AI escalation, validator abstraction |
| Rule reference | Rule catalog, ID mapping, ansible-lint coverage |
| Development guide | Local setup, tox environments, testing |
| ADRs | Architecture Decision Records |
See CONTRIBUTING.md for development workflow, coding standards, and PR process.
Apache-2.0