Use repo-local identity policy with .gitrole

What this is

Use a root-level .gitrole file when a repository should say:

• "this role is the normal one here"
• "these roles are still okay here"

This is repo-local identity policy, not workflow automation.

If you have not done the normal role setup yet, start with Use the right Git identity for this repo first. This guide is the next step when a repository should say which roles belong there.

It does not:

• switch roles for you
• install hooks
• block commits

It just gives the repo a small, clear identity rule.

Pin a repo to one role

If a repo should use exactly one saved role most of the time, this is the easiest path:

gitrole pin company-main

That creates a .gitrole file like this:

{
  "version": 1,
  "defaultRole": "company-main",
  "allowedRoles": ["company-main"]
}

Think of pin as saying:

• this repo belongs to company-main
• do not guess
• do not allow extra roles unless someone edits the policy on purpose

If .gitrole already exists, gitrole pin fails on purpose. It will not merge, overwrite, or silently expand the policy.

The file format

The first version is intentionally small:

{
  "version": 1,
  "defaultRole": "company-main",
  "allowedRoles": ["company-main", "maintainer-personal"]
}

What each field means:

• defaultRole is the role that normally belongs in this repo
• allowedRoles is the short list of roles that are still valid here

The default role must also appear in allowedRoles.

Resolve the default role

Run this inside the repository:

gitrole resolve

If the repo has a valid .gitrole file, resolve prints the defaultRole.

Example:

company-main

If you want the whole policy as JSON for scripts, prompts, or agents, use:

gitrole resolve --json

Example:

{
  "version": 1,
  "defaultRole": "company-main",
  "allowedRoles": ["company-main", "maintainer-personal"]
}

If no .gitrole file exists, resolve fails clearly. status and doctor still work normally without repo policy.

How status and doctor use policy

When .gitrole exists, gitrole status and gitrole doctor add repo policy on top of the normal identity, remote, and SSH checks.

The policy states are simple:

• ok: the effective role matches defaultRole
• info: the effective role is allowed here, but it is not the default
• warn: the effective role is not in allowedRoles

Allowed-but-not-default does not degrade the repo to warning by itself.

Shared repo example

This is useful for a shared org repo where both the org identity and a maintainer's personal identity are valid:

{
  "version": 1,
  "defaultRole": "company-main",
  "allowedRoles": ["company-main", "maintainer-personal"]
}

If you are currently using maintainer-personal, the repo can still be aligned.

Example status output:

maintainer-personal  Maintainer Name <maintainer@personal.example>  global  aligned
repo policy  allowed role maintainer-personal (default: company-main)

Example doctor interpretation:

• remote and SSH auth can still be correct
• policy is surfaced as info, not warn, because the current role is allowed even though it is not the default

When to use it

Add .gitrole when a repository has an identity policy you want to make explicit, such as:

• a company repo that should normally use a work role
• a shared repo where more than one role is valid
• an open-source repo where a maintainer identity is allowed but not always the default

Keep it small.

Use .gitrole when you want the repo to answer two simple questions:

• what role is preferred here?
• is the current role allowed here?

If automation should read that policy before it commits or pushes, continue with Use gitrole as an identity preflight for agents and automation.