Managing Multiple Git Identities Was a Mess, So I Built gitrole

Multiple accounts were annoying. Multiple machines made it worse. Then came the agents.

I was supposed to be on vacation.

Not fully offline. Just the kind of trip where you bring an old laptop, keep a loose eye on things, and tell yourself that if something urgent comes up, you can handle it.

I had my dotfiles. I had the usual setup scripts for bootstrapping a machine and juggling Git accounts. I even had a shell wrapper and GIT_SSH_COMMAND to force the right key per repo. I thought that would be enough. It wasn’t.

Halfway through the trip, a client messaged me. The project they had been sitting on for weeks suddenly became urgent.

So there I was, on an old laptop, trying to jump back into work mode.

I needed to pull private files from one GitHub account, set up a client repo on another, and keep my personal GitHub config intact on the same laptop. Three identities. One machine. As if that weren’t enough chaos, I also wanted an agent running overnight, and none of them were playing nicely together.

I tried to make gh behave across multiple accounts.

Wrong account authenticating. Wrong identity on commits. Private repos inaccessible because the wrong SSH key was being used. Everything was tangled together.

I got it working eventually. But it took way longer than it should have. And the worst part was knowing this was not a one time problem. It was going to happen again on the next machine, the next repo, the next account, the next agent.

That was the moment I stopped patching the workflow and decided to build the missing tool.

That tool is gitrole.

Why separate identities at all?

For me, this is not just cleanup. It is discipline.

Work is employer-owned code. Wrong identity on a commit is not just awkward; it's a problem. It is an accountability and IP problem.

Freelance is client-owned code. I also keep private client templates and tools there that I do not want mixed into anything else.

Personal is my own work. I do not want employer email on side projects or personal experiments bleeding into client repos.

Agents make this even more important. If an agent commits as me and pushes something broken, was that me or the agent? There needs to be a clean boundary.

Each identity has a different owner, audience, and level of accountability. Mixing them is not just messy. It creates real problems.

The actual problem

Git identity is split across two systems.

Commit identity is your user.name and user.email — what your commit says it is from.

Push identity is your SSH setup — which key gets used, which GitHub account that key maps to, which host alias the repo remote points at.

Those two things are related, but they are not the same. You can easily end up with commits that look right, but pushes that go through the wrong account. Git does not warn you when those two drift apart. Most people only notice after the damage is already in history.

gh helps with GitHub authentication. It does not manage your Git commit identity. You can gh auth switch all day and still commit as the wrong person.

That is the hole gitrole fills.

What gitrole gives you

gitrole gives you one place to check the two things Git keeps separate:

• who the next commit will say it is from
• which GitHub account will actually push it

Instead of editing config by hand and hoping you remembered everything, you save your identities once, switch to the one you want, and check the repo before you commit or push.

The three-command loop

gitrole use work --local
gitrole status
gitrole doctor

• use switches the identity for this repo only
• status tells you whether commit and push identity are aligned
• doctor explains what is wrong if they are not

You save a role once per identity:

gitrole add work \
  --name "Your Name" \
  --email "you@company.com" \
  --ssh ~/.ssh/id_work \
  --github-user your-work-github-username \
  --github-host github.com-work

Then use it and check it:

gitrole use work --local
gitrole status

work  aligned
  commit Your Name <you@company.com>
  push  your-work-github-username via github.com-work
  scope local override

If status shows aligned, you are done. If something looks off, gitrole doctor tells you exactly what and why:

gitrole doctor

checks
  ok role   commit identity matches saved role work
  ok scope  selected role work is applied via local config
  ok commit effective commit identity matches selected role work
  ok auth   SSH auth matches role githubUser your-work-github-username

And if the push path is still wrong:

gitrole remote set work

That rewrites origin to use the SSH host alias configured for that role.

Remote was still pointing at the personal account after switching to work. Doctor caught it. One command fixed it.

The fresh-machine moment

On a clean machine, the problem becomes obvious fast. You install gitrole, run status, and see this:

no matching role  warning
  commit Ada <ada@example.com>
  push  Ada via github.com
  scope global

Git is configured. gitrole just does not know that identity yet. So you capture it:

gitrole import current --name personal

imported current identity as personal
  commit Ada <ada@example.com>
  scope global

Now gitrole knows that identity by name. No retyping.

Agents made this more important, not less

Humans are bad at remembering which identity belongs where.

Agents are worse. They do not carry ambient context unless you make it explicit.

That is why gitrole has gitrole status --short, gitrole doctor --json, and repo-local .gitrole policy files. Not because I wanted to build an AI tool, but because explicit identity state matters a lot more once software is committing on your behalf.

The point

I built gitrole because I was tired of that moment before every push:

wait — am I the right person right now?

Save your identities once. Switch with one command. Check before you push.

It already works; I use it myself, and I'm still refining it as I pressure test it across machines and repos. If you try it, I'd love to hear what works and what still feels rough.

Install: npm install -g gitrole

Docs: docs.gitrole.dev — repo pinning, agent identity setup, and machine-readable output for automation.

GitHub: github.com/synsoftworks/gitrole