Troubleshoot identity warnings

Run the diagnosis in the same repository and environment as the check that warned:

gitrole doctor

For structured detail, use gitrole doctor --json. Both commands may exit 2 and still return a valid diagnosis. Exit 1 is failure; the error is on stderr and no result is printed on stdout.

Diagnose locally without SSH

gitrole doctor --offline
gitrole doctor --offline --json

Use this when you want local explanations without SSH connections or SSH configuration evaluation. --json --offline works too. Authentication is explicitly skipped, not failed or verified. Exit 0 means no local warnings; it does not establish an authenticated account or guarantee a future push.

Local identity, author/committer differences, fresh-repository state, policy, every selected push host and HTTPS pin checks still apply. Mixed SSH/HTTPS destinations keep local pin checks without the online mixed-authentication warning. A missing or mismatched pin still warns. No authentication history is read or saved. To inspect online authentication later, run gitrole doctor yourself with awareness that configured SSH commands, network access and SSH state changes may occur.

Choose the warning

What warned	What to inspect	Next action
commit	Effective author and committer; environment and included configuration	Confirm the intended role, then apply it locally if appropriate. Recheck any author/committer overrides.
remote	repository.push.remoteName and all targets	Check the selected push remote, push URLs, protocol, and expected host alias.
auth on HTTPS	Active role's githubUser and the .gitrole policy	Follow the HTTPS first-use explanation below through the first-use guide. A matching pin expresses an expectation; it does not check credentials.
auth on SSH	Each endpoint's supported SSH context and observed account	Read the SSH account guide. Unverified contexts warn even when a separate SSH command works.
policy	Default/allowed roles and the effective author	Review repo-local policy before changing it.

Do not switch roles or widen policy just to clear a warning. Choose the identity and policy the repository is intended to use.

HTTPS warns after add and use

This is expected without an allowing pin and a saved GitHub username. Read Use the right Git identity for this repo, including its HTTPS step. The check remains active offline. A matching pin can yield auth=na; it does not prove which account an HTTPS credential helper will use. Mixed SSH/HTTPS destinations warn online.

SSH account unverified

An unverified account is a limit of the check, not proof that your key is missing or your account is wrong. Read the reason in status or doctor. When more than one reason applies, human output points to gitrole doctor --json; the existing message fields contain the full list. expected in doctor is the saved account, not an observed login.

• Git can ask for your key passphrase. Gitrole checks without asking, so it may have different keys available. This does not mean your key necessarily needs a prompt or that your agent or keychain is empty. Do not change SSH settings just to clear the warning.
• The push and check use different settings. Review command-dependent SSH rules with whoever maintains the setup. A separate successful SSH connection does not establish the push account.
• A custom command or unsupported transport is selected. Review the selected push URL and any GIT_SSH_COMMAND, GIT_SSH or core.sshCommand override. Gitrole does not execute or bypass unsupported transports to identify an account.
• The connection check failed. Read the SSH error. A refusal alone does not distinguish unavailable credentials from connection or server problems. Review the intended host before changing keys or permissions.
• Authentication was skipped. status --offline performs local checks only; it does not attempt SSH authentication. Offline auth=na is not a failed connection.

For a supported SSH endpoint, the diagnostic may show a manual connection command. It preserves the endpoint's SSH user, host alias and explicit port. See the manual-check explanation before running it. Online status and doctor can themselves connect and run configured SSH commands or change SSH state; use offline status when those effects are not acceptable.

The role or scope differs from your Git config

current and import current use Git's effective author. doctor --json reports the effective author as commitIdentity and the committer as committerIdentity. Their field sources can be env, while scope still describes underlying configured author scope. A global name and local email yield mixed, not local.

If author and committer differ, commit alignment warns. A repository with no commits and no local/worktree override also warns, even if its global identity matches a role. Applying a local role can address that case; it does not prove the first push has a usable refspec.

Changing origin did not fix the push check

Inspect gitrole doctor --json. Gitrole selects the default push destination and checks every URL Git resolves for it. A branch pushRemote, remote.pushDefault, branch remote, explicit pushurl, or a URL or path used in place of a remote name can make the destination differ from origin's fetch URL. URL rewrites (insteadOf, pushInsteadOf) apply to that destination. gitrole remote set changes origin's fetch URL only. Correct the intended Git configuration after reviewing those destinations; see Machine-readable contracts for selection rules and limitations.

The prompt is empty or warns

The supplied zsh and Oh My Zsh functions have a known read-only status variable error. Use the existing gitrole-prompt helper directly or the Bash example; see the prompt guide. Offline prompts do not verify network authentication.

A command or output differs from the docs

Check gitrole --version and command -v gitrole, then read Install and update gitrole. Source changes and npm/Homebrew publication are separate. Completion, skills, and hooks have optional asset setup; installation does not enable them automatically.

An aligned result still cannot establish push success

A check does not prove refspec readiness or repository authorization. It observes current identity and default destinations. A later explicit git push target, git commit --author, or changed environment/configuration falls outside that snapshot.