github-username-rename
A GitHub login change breaks some things at once and others later.
- GitHub does not redirect
uses: references to actions and reusable workflows.
They can fail as soon as the rename lands. Fix them first.
- Profile links return 404 at once.
- GitHub redirects repository pages,
git remotes and the API from the old login.
That redirect ends if someone registers the old login and creates a repo with
the same name. After that, a reference that still names the old login points at
their code. A workflow uses: line is the worst case, because it runs that code.
So the job has a deadline you cannot see. Do it soon, and do it in bulk.
What the rename touches
| Place |
Behaviour after the rename |
git remotes, clone URLs |
Redirect while the old login stays free. Fix them anyway, with git remote set-url. |
gh login and token |
The token keeps working. gh api user shows the new login. The keyring label may keep the old name. |
uses: owner/repo@ref |
Not redirected. Can fail now. Runs foreign code if the old login is claimed. Fix first. |
| GitHub Pages |
The old owner.github.io URL stops. Update it. |
Packages on ghcr.io/<owner> |
The old path is not redirected. Check each image. |
| GitHub Apps and installations |
They follow the account. The App slug does not change. |
| Self-hosted runners and brokers |
Registered to owner/repo. Check the registration and any owner constant in the broker. |
MCP registry names io.github.<owner>/* |
Tied to the login. They need a re-publish. Do not edit them in a rename PR. |
Marketplaces, npx skills add owner/repo, docs |
Update the text. Repository redirects keep old text working for now. |
Step 1: survey with a clone, not code search
Code search lags a rename. A search for the old name returned zero hits for a
fleet that had thousands. Do not trust it.
- List the repos:
gh repo list <new-owner> --limit 300 --json name,isArchived,isFork.
- Shallow-clone each one:
gh repo clone <new-owner>/<repo> <dir> -- --depth 1.
- Count hits, without lockfiles:
git grep -I -c -i <old> -- . ':!*lock*'.
- Run clones in parallel (12 at a time works). Retry failures once; they are
rate limits, not missing repos.
Write the counts to a file. You need it to split the work and to prove the end state.
Step 2: sort the hits
Most hits are not GitHub references. Tally the shapes before you write a rule.
A rename across 140 repos found these classes:
Change
github.com/<old>, github.com:<old>, api.github.com/repos/<old>,
raw.githubusercontent.com/<old>, <old>.github.io
uses: <old>/<repo>@ref (keep the ref)
owner/repo slugs: gh -R, --repo, --owner, repository: fields
- package metadata URLs (
repository, homepage, bugs)
ghcr.io/<old> image paths, only after the image exists under the new owner and a
pull works (see Step 6). Until then leave the reference and report it.
- GitHub user mentions and
CODEOWNERS entries
Leave
- your own domain, and emails on it
- npm scopes and published package names
- GitHub App slugs and the folders that hold their keys
- cloud project IDs, Cloudflare, Stripe, Firebase and bucket names
- environment variable and secret names, bundle IDs
- local paths such as
~/Documents/<old>
- social handles and bio text
io.github.<old> registry names (re-publish separately)
- lockfiles, changelog history, snapshots and fixtures that quote old text
When a hit is unclear, leave it and list it with file:line. A skipped hit costs
one more PR. A wrong change can take a deploy down.
Never run sed s/<old>/<new>/ over a repo. The domain and the App slug both
contain the old name.
Step 3: brief the workers
Write one shared brief file. Each worker reads it and gets a list of repos.
The brief holds the change list, the leave list, the PR rules, and the report format.
Keep the brief in a file, not in each prompt, so the rules cannot drift.
Batch by size:
- Repos with a few hits each: 25 to 30 repos per worker.
- Medium repos: about 10 per worker.
- Each large repo: its own worker. Large repos need several PRs.
Use a mid-tier model for the edits. Use a different, stronger model for review.
Step 4: one PR per repo
Each repo gets its own issue and PR. Follow the repo's PR standard: issue first,
branch <prefix>-<issue>-rename-github-owner, one concern, under 500 counted
lines. Read the prefix from the repo's config. Do not guess it.
Split a large repo by top-level directory. Each PR gets its own issue.
Put evidence under "How I verified": the count of GitHub-form hits before and
after, and the list of hits you left on purpose.
Workers open PRs. Workers do not merge.
Step 5: review and merge
- One reviewer reads each PR diff. A batch reviewer can cover many identical PRs.
The reviewer checks that no "leave" class was changed.
- Read the review and the CI result at the head commit.
- Merge from your own session with the head SHA pinned:
gh pr merge <n> --squash --match-head-commit <sha>. Merge one PR at a time per repo.
Parallel merges into one repo fail with "Base branch was modified". Retry those one by one.
A body edit re-runs the PR-standards check, so add the review section first and wait.
- A repo that deploys on every push to
main needs a green deploy check first.
- Never edit a
release branch in a rename PR. Promote main to release the
normal way afterwards.
Step 6: prove nothing is left
Re-run the survey on a fresh clone of each default branch. The only hits left
should be the "leave" class. Save the final list of skipped hits. Then handle the
parts that no PR can fix:
- re-publish MCP registry entries under the new login
- re-register runners and check broker owner constants
- move
ghcr.io images first, check a pull, then change the references that use them
- update the
gh keyring label and any saved config that names the old login
- keep the old login unclaimed, if GitHub allows it, until all of this is done
Check the diff with a script, not only by eye
Workers report what they meant to do. Check what they did. For each PR, pair every removed
line with its added line. A pure rename means the added line equals the removed line with
only the owner changed. Flag every PR where it does not. Also flag any changed occurrence
that sits next to .com, -name, _, @, io.github. or a path. This found, in one run:
a registry name changed after the worker had reported it as skipped, formatter noise that a
pre-commit hook added to six PRs, and whole-file rewrites of historical records.
Then check every <new-owner>/<repo> string the PRs add: gh api repos/<new-owner>/<repo>.
A name that fails is one of three things. A placeholder or fixture (ignore it). A repo that
never existed (it was dead before the rename). Or an alias: the old name was a redirect to a
repo that was renamed earlier. For an alias, the simple substitution breaks the link. Use the
real repo name. Check the old form to tell the cases apart: gh api repos/<old-owner>/<repo>.
Failure modes seen
- Code search returned zero hits while thousands existed. Clone and grep.
- A blind replace would have changed a domain, a cloud project ID and an App slug.
- A pre-push hook crashed under a newer Node than the repo uses. Report it; do not skip it silently.
- A repo's pre-commit formatter reformatted tables and quotes inside a rename PR. Fix such a PR
by writing the exact file content through the contents API, which runs no hooks.
- A running service stored the old owner in state (a lease file, a saved repo name). The new
owner check rejected it. For a live system, accept both owners for a fixed period and write the
removal date next to the code. Check saved state before you merge a change to an owner constant.
- Two agents opened rename PRs for one repo in the same minute. List open PRs before you start,
and close the duplicate.
- Some repos had no PR-standards file. Open a prefix-less PR on the default branch there.
Do not invent a prefix.
- A repo with an invalid PR prefix cannot take a PR until its config is fixed. Fix that first, in its own PR.
- A repo whose
main already fails lint shows a red check that the rename did not cause. Say so in the PR.
1---2name: github-username-rename3description: "Use when a GitHub login changes and every repo, workflow, script and doc that names the old owner must be updated, in bulk, with agents. Covers what the rename breaks and when, how to survey every repo (code search lags, so shallow-clone and grep), the list of strings to change and the longer list that must not change (domains, npm scopes, App slugs, cloud resource names, local paths, registry namespaces), a shared brief for parallel workers, one PR per repo under the size cap, review, merge order, and the checks that prove nothing is left. Triggers: 'I changed my GitHub username', 'rename GitHub org references', 'update all repos to the new owner', 'old username still in workflows', 'fleet rename PRs'."4metadata:5 source: https://skillmd.com/skills/pooriaarab/github-username-rename6---78# github-username-rename910A GitHub login change breaks some things at once and others later.1112- GitHub does not redirect `uses:` references to actions and reusable workflows.13 They can fail as soon as the rename lands. Fix them first.14- Profile links return 404 at once.15- GitHub redirects repository pages, `git` remotes and the API from the old login.16 That redirect ends if someone registers the old login and creates a repo with17 the same name. After that, a reference that still names the old login points at18 their code. A workflow `uses:` line is the worst case, because it runs that code.1920So the job has a deadline you cannot see. Do it soon, and do it in bulk.2122## What the rename touches2324| Place | Behaviour after the rename |25| --- | --- |26| `git` remotes, clone URLs | Redirect while the old login stays free. Fix them anyway, with `git remote set-url`. |27| `gh` login and token | The token keeps working. `gh api user` shows the new login. The keyring label may keep the old name. |28| `uses: owner/repo@ref` | Not redirected. Can fail now. Runs foreign code if the old login is claimed. Fix first. |29| GitHub Pages | The old `owner.github.io` URL stops. Update it. |30| Packages on `ghcr.io/<owner>` | The old path is not redirected. Check each image. |31| GitHub Apps and installations | They follow the account. The App slug does not change. |32| Self-hosted runners and brokers | Registered to `owner/repo`. Check the registration and any owner constant in the broker. |33| MCP registry names `io.github.<owner>/*` | Tied to the login. They need a re-publish. Do not edit them in a rename PR. |34| Marketplaces, `npx skills add owner/repo`, docs | Update the text. Repository redirects keep old text working for now. |3536## Step 1: survey with a clone, not code search3738Code search lags a rename. A search for the old name returned zero hits for a39fleet that had thousands. Do not trust it.40411. List the repos: `gh repo list <new-owner> --limit 300 --json name,isArchived,isFork`.422. Shallow-clone each one: `gh repo clone <new-owner>/<repo> <dir> -- --depth 1`.433. Count hits, without lockfiles: `git grep -I -c -i <old> -- . ':!*lock*'`.444. Run clones in parallel (12 at a time works). Retry failures once; they are45 rate limits, not missing repos.4647Write the counts to a file. You need it to split the work and to prove the end state.4849## Step 2: sort the hits5051Most hits are not GitHub references. Tally the shapes before you write a rule.52A rename across 140 repos found these classes:5354**Change**55- `github.com/<old>`, `github.com:<old>`, `api.github.com/repos/<old>`,56 `raw.githubusercontent.com/<old>`, `<old>.github.io`57- `uses: <old>/<repo>@ref` (keep the ref)58- `owner/repo` slugs: `gh -R`, `--repo`, `--owner`, `repository:` fields59- package metadata URLs (`repository`, `homepage`, `bugs`)60- `ghcr.io/<old>` image paths, only after the image exists under the new owner and a61 pull works (see Step 6). Until then leave the reference and report it.62- GitHub user mentions and `CODEOWNERS` entries6364**Leave**65- your own domain, and emails on it66- npm scopes and published package names67- GitHub App slugs and the folders that hold their keys68- cloud project IDs, Cloudflare, Stripe, Firebase and bucket names69- environment variable and secret names, bundle IDs70- local paths such as `~/Documents/<old>`71- social handles and bio text72- `io.github.<old>` registry names (re-publish separately)73- lockfiles, changelog history, snapshots and fixtures that quote old text7475When a hit is unclear, leave it and list it with `file:line`. A skipped hit costs76one more PR. A wrong change can take a deploy down.7778Never run `sed s/<old>/<new>/` over a repo. The domain and the App slug both79contain the old name.8081## Step 3: brief the workers8283Write one shared brief file. Each worker reads it and gets a list of repos.84The brief holds the change list, the leave list, the PR rules, and the report format.85Keep the brief in a file, not in each prompt, so the rules cannot drift.8687Batch by size:8889- Repos with a few hits each: 25 to 30 repos per worker.90- Medium repos: about 10 per worker.91- Each large repo: its own worker. Large repos need several PRs.9293Use a mid-tier model for the edits. Use a different, stronger model for review.9495## Step 4: one PR per repo9697Each repo gets its own issue and PR. Follow the repo's PR standard: issue first,98branch `<prefix>-<issue>-rename-github-owner`, one concern, under 500 counted99lines. Read the prefix from the repo's config. Do not guess it.100101Split a large repo by top-level directory. Each PR gets its own issue.102103Put evidence under "How I verified": the count of GitHub-form hits before and104after, and the list of hits you left on purpose.105106Workers open PRs. Workers do not merge.107108## Step 5: review and merge1091101. One reviewer reads each PR diff. A batch reviewer can cover many identical PRs.111 The reviewer checks that no "leave" class was changed.1122. Read the review and the CI result at the head commit.1133. Merge from your own session with the head SHA pinned:114 `gh pr merge <n> --squash --match-head-commit <sha>`. Merge one PR at a time per repo.115 Parallel merges into one repo fail with "Base branch was modified". Retry those one by one.116 A body edit re-runs the PR-standards check, so add the review section first and wait.1174. A repo that deploys on every push to `main` needs a green deploy check first.1185. Never edit a `release` branch in a rename PR. Promote main to release the119 normal way afterwards.120121## Step 6: prove nothing is left122123Re-run the survey on a fresh clone of each default branch. The only hits left124should be the "leave" class. Save the final list of skipped hits. Then handle the125parts that no PR can fix:126127- re-publish MCP registry entries under the new login128- re-register runners and check broker owner constants129- move `ghcr.io` images first, check a pull, then change the references that use them130- update the `gh` keyring label and any saved config that names the old login131- keep the old login unclaimed, if GitHub allows it, until all of this is done132133## Check the diff with a script, not only by eye134135Workers report what they meant to do. Check what they did. For each PR, pair every removed136line with its added line. A pure rename means the added line equals the removed line with137only the owner changed. Flag every PR where it does not. Also flag any changed occurrence138that sits next to `.com`, `-name`, `_`, `@`, `io.github.` or a path. This found, in one run:139a registry name changed after the worker had reported it as skipped, formatter noise that a140pre-commit hook added to six PRs, and whole-file rewrites of historical records.141142Then check every `<new-owner>/<repo>` string the PRs add: `gh api repos/<new-owner>/<repo>`.143A name that fails is one of three things. A placeholder or fixture (ignore it). A repo that144never existed (it was dead before the rename). Or an alias: the old name was a redirect to a145repo that was renamed earlier. For an alias, the simple substitution breaks the link. Use the146real repo name. Check the old form to tell the cases apart: `gh api repos/<old-owner>/<repo>`.147148## Failure modes seen149150- Code search returned zero hits while thousands existed. Clone and grep.151- A blind replace would have changed a domain, a cloud project ID and an App slug.152- A pre-push hook crashed under a newer Node than the repo uses. Report it; do not skip it silently.153- A repo's pre-commit formatter reformatted tables and quotes inside a rename PR. Fix such a PR154 by writing the exact file content through the contents API, which runs no hooks.155- A running service stored the old owner in state (a lease file, a saved repo name). The new156 owner check rejected it. For a live system, accept both owners for a fixed period and write the157 removal date next to the code. Check saved state before you merge a change to an owner constant.158- Two agents opened rename PRs for one repo in the same minute. List open PRs before you start,159 and close the duplicate.160- Some repos had no PR-standards file. Open a prefix-less PR on the default branch there.161 Do not invent a prefix.162- A repo with an invalid PR prefix cannot take a PR until its config is fixed. Fix that first, in its own PR.163- A repo whose `main` already fails lint shows a red check that the rename did not cause. Say so in the PR.