Custom Migrator

Move customizations between sites the way you move code — versioned, sanitized, and security-checked.

Custom Migrator exports Frappe/ERPNext customizations from the desk into a git repo: JSON is cleaned of site metadata, scripts are scanned with Semgrep against Frappe standards, and AI drafts a commit message from the selection and its diffs — then you promote Dev → QA → Prod without hand-copying fixtures or guessing what changed.

Set up

Install, configure Git, verify in 5 minutes.

Export to Git

Pick items, preview the diff, push a branch.

Settings reference

Every Migrator Settings field explained.

Migration Log

Action and status enums; the audit trail.

Troubleshooting

The problem it solves

ERPNext teams build customizations on one site and need them on another. That promotion path is usually painful:

• Dev has the change; QA and Prod do not. Custom Fields, Property Setters, Client Scripts, Workflows — they live in the database, not in your app repo, so a bench update does not carry them.
• Raw exports are noisy and fragile. A normal customization dump carries site metadata (created_by, creation, modified, …) that does not belong in another environment and makes diffs and merges harder than they should be.
• Unsafe code can ride along. Server Scripts and Client Scripts written on Dev can introduce SQL injection or other Frappe anti-patterns; promoting them without a static check is how bugs and vulnerabilities land in QA/Prod.
• No review gate. Someone applies a customization on Prod with no PR, no diff, and no audit trail — until something breaks.

Custom Migrator treats customizations like code: sanitize the JSON, Semgrep-check the scripts, preview the diff, push a branch, open a PR, merge into the target environment's app — with a Migration Log of every step.

What makes it different

Capability	Why it matters
Versioned	Every export lands on a named git branch (and optional release tag). History, blame, rollback, and PR review work the same as for app code.
Clean	Exported JSON is sanitized — site noise like created_by, creation, modified, modified_by, and similar metadata is stripped so fixtures stay portable across environments, not tied to who touched them on Dev.
Secure	Exported scripts and customizations are checked with Semgrep against Frappe coding standards and common risks (SQL injection and related vulnerabilities) so a migration does not ship unsafe Server Scripts, Client Scripts, or other code into QA/Prod.
AI commit messages	Migrator forwards the selected customizations and their diffs into the commit-message prompt. Related items are correlated into one coherent intent; unrelated changes stay separate — so history describes the feature you shipped, not a dump of filenames.
Environment-ready	Same workflow for Dev → QA → Prod: export from the source site, merge the PR into the branch that deploys to the next environment, pull/migrate there.

Typical flow across environments

1. Build and validate customizations on Dev.
2. Open Custom Migrator → select items → preview diff → push a migration/… branch.
3. Open a PR into the base branch that feeds QA (or your release branch).
4. After review and merge, deploy/pull that app on QA and run migrate.
5. Promote the same commit (or a release tag) to Prod through your normal release process.

You get one source of truth in git — not three divergent databases of hand-applied customizations.

What it moves

Custom Fields, Property Setters, Client Scripts, Server Scripts, Workflows, Workflow States, custom DocTypes, Notifications. You can add more DocType types to track in Settings.

It does not move business records (Customers, Invoices) or app code. Those belong in your data and your repo respectively.

Who can use it

Role	Open the page, export, view logs	Edit Settings
System Manager	✓	✓
Hydra Admin	✓	✓
Hydra User	✓	✗

NOTE

Hydra User is functional-only access. They can run migrations but can't touch the Git PAT or target app config.

Quick start

Install the app

Configure Migrator Settings

PAT, target app, base branch. Click Test Connection.

Export your first change

Tick items → preview diff → push branch → open PR.

Full setup guide →