Appearance
Authentication troubleshooting
This page covers what goes wrong between a stored credential and a git host. For setting a credential up, see Access tokens, OAuth sign-in or SSH keys. For URL and network problems, see Cloning troubleshooting.
Which credential gets used
On the clone screen, with Require authentication on:
- What you pick explicitly is used.
- With nothing picked, the credential is chosen for you only when exactly one stored credential matches the URL's host. Otherwise the row reads Select… and you choose.
- For an SSH URL, the choices are the Git over SSH identities of the server whose host and port match the URL.
- Changing the URL to a different host clears the pick.
Once a project exists, it uses the credential recorded in its settings and nothing else. There is no fallback to another credential for the same host, and no silent anonymous attempt: a project that requires authentication but has lost its credential stops with "This project requires authentication, but no credential is selected." Open the project's settings and choose one.
Messages on the clone screen
- Select a credential, or turn off Require authentication. The URL needs a credential and none is picked.
- Selected credential is for X, but the URL is for Y. The pick belongs to another host. Pick or add one for Y.
- The selected credential expects an HTTP or HTTPS URL. A token or OAuth credential against an
ssh://orgit@URL. Tokens only speak HTTPS. Either switch the URL to its HTTPS form, which most hosts offer next to the SSH one, or pick an SSH identity. - SSH URLs need a key. Turn on Require authentication and choose an SSH identity. SSH is never anonymous.
Authentication failed
The host rejected the credential. Check:
- The token has not expired or been revoked. Open the credential under Settings → Git Credentials and tap Test credential.
- The token has the permissions the operation needs: read for clone and fetch, write for push.
- The username is the account the token belongs to.
For OAuth, Sign in again on the credential's screen replaces the tokens.
SSH key rejected
The server was reached but did not accept the key. Open the identity under Settings → SSH Servers and tap Test key. If that fails too, the public key is not on your account: open SSH key details, copy the public key and compare it line by line with the host's SSH keys page.
Host not yet trusted, host key changed
Both come from the host-key check that runs before any SSH connection.
- Host not yet trusted: no fingerprint is on record for this host and port, so the connection was refused. Trust is only established where you can confirm a fingerprint: adding the server under Settings → SSH Servers, testing an identity, or cloning. Do one of those, confirm the fingerprint, then retry.
- Host key changed: the server presented a different key from the one you trusted. If you know why, open the server under Settings → SSH Servers and tap Check for change to confirm the new fingerprint. If you do not, stop and find out first.
Could not resolve credential from Keychain
The credential is in the list but its secret is not readable. The usual cause is a restore from a backup, since git credentials are tied to the device they were saved on; SSH keys also vanish if the device passcode is removed. Remove the credential and add it again. For OAuth that means signing in again; for an SSH key, generate a new pair or paste the original and update the host.
Can't remove credential
The dialog names the projects still using it. Open each project's settings and pick another credential, or turn off Require authentication for projects that no longer need it. Then remove the credential.
Choosing between token, OAuth and SSH
- OAuth is the fastest setup on GitHub, GitLab and Gitea, and the app keeps the token fresh.
- Token works on every HTTPS host, including ones the app has no sign-in for. You renew it yourself when it expires.
- SSH works on any host with an SSH endpoint, never expires, and needs a passcode on the device. It is the only choice for hosts that are SSH-only.
You can keep credentials of every kind for the same host and pick per project.