appmaker-git-remote-origin-fixer

A small recovery CLI that repairs a local git origin remote after a GitHub organization migration.

When repositories are moved from one GitHub organization to another — and the old copy is then deleted or archived — every developer's local clone still points at the old remote, so git push fails. Run this tool once, after that first failed push, and it repoints origin at the new organization for you.

git push                            # ❌ fails — repo was moved out of the old org
appmaker-git-remote-origin-fixer    # 🔧 diagnoses and fixes origin
git push                            # ✅ works

Who this is for: the package ships with Appmaker.xyz's migration configuration by default, so Appmaker developers can just install and run it. It is not Appmaker-specific, though — the migration rules are pure data, so any team can reuse it by editing the bundled config (see Configuration).

Install

npm install -g appmaker-git-remote-origin-fixer
# or run without installing:
npx appmaker-git-remote-origin-fixer

Usage

Run it from inside the affected repository:

appmaker-git-remote-origin-fixer [options]

  -n, --dry-run         Diagnose only; do not modify the remote
  -h, --help            Show help
  -v, --version         Show version

If the tool can't safely resolve your remote, it will tell you to contact the team — please do that rather than trying to fix the remote by hand.

How it works

Read origin URL  →  parse org + repo
       │
       ▼
Is the org a "source" in the migration config?
       │  no → "No migration configured" → exit
       ▼ yes
What state is the repo in the SOURCE org?
       ├─ healthy (push works)       → "still exists, nothing to do"
       ├─ archived (read-only)       → migrate ↓
       └─ deleted (not found)        → migrate ↓
                                         │
                                         ▼
Is the repo reachable in the DESTINATION org?      (git ls-remote)
       ├─ reachable      → rewrite origin → "run git push"
       ├─ no permission  → "exists, contact admin" (remote left unchanged)
       └─ not found      → "not found in either org"

Detection uses your existing git credentials — no GitHub token or API access:

• Existence is checked with git ls-remote (a read).
• Archived/read-only is detected with a git push --dry-run probe: it sends nothing and creates nothing, but the server still reports if the repo is archived. (An archived repo reads fine, so a read alone can't detect it.)

The remote is only rewritten once the destination is confirmed reachable. When the tool can't determine the situation safely, it stops and tells the developer to contact the team rather than guessing.

Note: detection is most reliable with SSH remotes ([email protected]:Org/repo.git), where GitHub returns clear messages. Over HTTPS without cached credentials git may be unable to determine state; in that case the tool leaves your remote untouched and points the developer at the team.

For maintainers: --force

There is an undocumented --force flag that rewrites origin to the destination unconditionally, skipping both the source and destination checks. It exists for cases the tool can't verify on its own — most often a private destination the developer can't yet see (GitHub reports it as "Repository not found").

It is intentionally not advertised to end users: run blindly, it can repoint a remote into a wrong/broken state. Only direct a developer to run it when you (the team) have confirmed the destination is correct:

appmaker-git-remote-origin-fixer --force

Configuration

Migrations are data-driven — a simple map of source-org → destination-org, bundled with the package as migrations.json:

{
  "migrations": {
    "AppMakerHQ": "Appmaker-xyz",
    "AppMakerPartnersHQ": "Appmaker-Partners"
  }
}

The tool loads only this bundled config — it does not read a migrations.json from your current directory or home folder. (It runs inside arbitrary repos, and migrations.json is a common filename for unrelated things like DB migrations; reading those would break the tool.)

To change the mappings, edit the bundled migrations.json and publish a new version. Another team can adapt the tool the same way — fork it, edit the config, and publish their own build.

Development

npm install
npm run build      # compile TypeScript -> dist/
npm start          # run dist/cli.js

License

MIT