Production-grade Python tool for migrating Ansible Automation Platform (AAP) installations between versions, including large-scale environments (e.g. 80,000+ hosts).
Migrate from AAP 1.0–2.7 (or upstream AWX at an equivalent release level) to a same-or-newer target (2.6 or 2.7). Downgrade paths are not supported. See the compatibility matrix and AWX migration notes.
- Bulk API operations, checkpoint/resume, and idempotent imports
- Local host, optional containerized CLI, and optional Web UI workflows
- PostgreSQL-backed migration state
- Broad resource coverage (orgs, credentials, inventories, hosts, projects, job/workflow templates, schedules, classic and gateway RBAC, and more)
- Rich progress display with normal, quiet, CI/CD, and detailed output modes
Published docs: https://redhat-cop.github.io/aap-bridge/
Full docs live under docs/ and are built with MkDocs Material.
Procedures and reference material are not duplicated in this README —
use the guides below as the source of truth.
| Topic | Guide |
|---|---|
| Install (local, container CLI, Web UI) | Installation |
| First migration | Quick Start |
.env, tokens, config.yaml |
Configuration |
| Phases, resource order, resume | Migration Workflow |
| Commands | CLI Reference |
| Browser UI | Web UI |
| Version paths | Compatibility Matrix |
| Ephemeral AAP testing | Testing |
Browse the Markdown under docs/ on GitHub, or preview the MkDocs
site locally (contributor workflow — see
Contributing):
make docs-serve # http://127.0.0.1:8001
# or: mkdocs serve # http://127.0.0.1:8000git clone https://github.com/redhat-cop/aap-bridge.git
cd aap-bridge
make setup # local host: .venv, deps, seed .env
# Edit .env — see docs/getting-started/configuration.md
source .venv/bin/activate
aap-bridge config validate
aap-bridge # interactive TUI (recommended)The TUI walks prep → export → transform → import in steps so you can pause
for credential secrets (Vault or manual re-entry — $encrypted$ values cannot
be read from the source API) before import. A single aap-bridge migrate runs
the full pipeline unattended and is usually a poor first choice until secrets
are ready.
The quick path above is the local host install. For that path plus container CLI and Web UI options, see Installation.
Active development (0.1.0+). See CHANGELOG.md.
See CONTRIBUTING.md and docs/developer-guide/contributing.md.
GNU General Public License v3.0
Report vulnerabilities per SECURITY.md.
- Issues: GitHub Issues
- Security: SECURITY.md