Skip to content

Quick Start

Get AAP Bridge running in a few minutes after installation.

Install first

Complete Installation (local host, container CLI, or Web UI) before continuing. That guide covers PostgreSQL, make setup / compose, and seeding .env.

1. Configure Environment

Edit .env with your AAP credentials and database URL (created by make setup or make init-env):

# Source AAP instance (read-only token)
SOURCE__URL=https://source-aap.example.com
SOURCE__VERSION=2.4
SOURCE__TOKEN=your_source_read_token

# Target AAP instance (read/write token)
TARGET__URL=https://target-aap.example.com
TARGET__VERSION=2.6
TARGET__TOKEN=your_target_write_token

# PostgreSQL state database
MIGRATION_STATE_DB_PATH=postgresql://user:password@localhost:5432/aap_migration

For version-driven API routing, token scopes, Vault, and full settings, see Configuration. For AWX sources, see AWX Migration.

2. Validate Configuration

aap-bridge config validate

This checks connectivity to both AAP instances and the database.

3. Run Preparation Phase

aap-bridge prep

This:

  • Fetches schemas from both AAP instances
  • Compares field differences
  • Generates transformation rules

4. Export from Source

aap-bridge export

Exports all resources from the source AAP to the exports/ directory.

5. Transform Data

aap-bridge transform

Applies schema transformations for the target AAP version.

6. Import to Target

aap-bridge import

Imports transformed data to the target AAP.

7. Validate Migration

aap-bridge validate

Compares source and target to verify migration success.

Run without arguments for the interactive menu:

aap-bridge

Use this for most migrations. The menu runs prep, export, transform, and import in separate steps so you can pause after export/transform to load credential secrets into Vault (or recreate them on the target) before import. Encrypted fields appear as $encrypted$ on the source API and cannot be migrated without that step — see Compatibility Matrix and Configuration.

Unattended full pipeline

When Vault (or manual secrets) is already in place and you want a single unattended run:

aap-bridge migrate

This runs prep → export → transform → import sequentially. Prefer the TUI until that secret path is ready.

Next Steps