Set up

Three steps. Five minutes if your bench is already running.

Install the app

Standard bench get-app then install-app.

Fill in Migrator Settings

GitHub PAT, remote name, target app, base branch.

Test Connection

Green pill = the PAT can reach the remote. You're done.

1. Install

bench get-app https://github.com/Tacten/custom_migrator.git
bench --site <your-site> install-app custom_migrator

You start with eight DocTypes tracked out of the box: DocType (custom only), Custom Field, Property Setter, Client Script, Server Script, Workflow, Workflow State, Notification. Add more from Settings any time.

2. Configure

Open /app/migrator-settings.

Git Configuration

Field	What to enter
GitHub PAT	A Fine-Grained PAT with contents:write and pull_requests:write scopes on the target repo
Remote Name	upstream for apps installed via bench get-app, origin for cloned repos
Remote URL	Auto-detected from the repo. Edit to override

Target Configuration

Field	What to enter
Target App	The app whose repo receives the customisation files
Base Branch	The branch your PRs merge into (usually develop or main)

DocType Configuration

The Migrator DocTypes child table controls what types appear in the sidebar tree on /app/custom_migrator. Add rows for anything beyond the eight defaults.

IMPORTANT

Hydra User can run migrations but can't open Settings. Settings is restricted to System Manager and Hydra Admin.

If the target app has no .git directory

Common in Docker deployments. An Initialize Git Repository button appears under Target App. Fill in Remote URL first, then click. Your existing files aren't touched.

3. Test Connection

Click Test Connection on the form.

Pill	Means
Green ✓	Auth works, remote reachable
Red ✗	Detail in the banner: auth failed / remote not found / target app not selected / no PAT

Where you'll find things after install

Page	URL
Migrator desk page	/app/custom_migrator
Migrator Settings	/app/migrator-settings
Audit log	/app/migration-log

Export your first change →