Appearance
OAuth sign-in
OAuth lets you sign in to your git host through its own web page, the same way the host's apps do. The host issues a token, HachiCode stores it in the Keychain, and clone, push and fetch use it for that host. No token to copy, no key to manage.
Use OAuth when the host offers it and you want the quickest setup. Use an access token when it does not, or when you already have one. Use SSH keys for hosts you reach over SSH.
Supported hosts
| Host | OAuth | What you fill in |
|---|---|---|
| GitHub | ✓ | Nothing; the app is registered already |
| GitHub Enterprise | ✓ | Host, OAuth Client ID, OAuth Client Secret |
| GitLab | ✓ | Nothing beyond the host |
| GitLab (self-hosted) | ✓ | Host, OAuth Application ID and Secret |
| Gitea | ✓ | Host, OAuth Client ID |
Any other host takes an access token through the Generic entry.
Sign in
- Settings → Git Credentials, tap +.
- Pick the host.
- Choose the Sign in with … row.
- Fill in whatever the table above asks for, then tap Sign in.
- A browser sheet opens at the host. Sign in if you are not already, and approve the permissions HachiCode asks for.
- The sheet closes and the credential appears in the list.
GitHub asks for the repo scope. GitLab asks for read_user, read_repository and write_repository. If the host grants fewer permissions than requested, the app says so in OAuth granted fewer permissions than requested and lets you Save anyway; anything the missing scope covers will then fail on the host with a 403.
Registering the app on your own host
Self-hosted GitLab, GitHub Enterprise and Gitea need an OAuth application registered on the host, which is where the Client ID and Secret come from. Set the redirect URI to hachicode://oauth/callback. On Gitea, turn Confidential client off; the app only needs the Client ID there.
What is stored
The access token, the refresh token if the host issued one, the token's expiry, the granted scopes and your username, which the app looks up on the host right after sign-in. Tokens go to the device Keychain and are only ever sent to the host they came from.
When a token expires
- GitHub tokens do not expire. If you revoke one on the host, the next operation fails with Authentication failed and you sign in again.
- GitLab and Gitea hand out short-lived tokens with a refresh token. The app refreshes them on its own before they run out. If a refresh fails, the operation fails and you sign in again.
Sign in again
Open the credential under Settings → Git Credentials and tap Sign in again under Re-authenticate. The new tokens replace the old ones; the credential keeps its identity, so every project bound to it keeps working.
That works for GitHub and GitLab. For a self-hosted host the app does not keep the application secret, so remove the credential and add it again instead.
Common failures
- Host is malformed. The Host field wants a bare host name such as
gitlab.example.com, or for Gitea the base URL you sign in to. No trailing slash. - Browser redirect did not include an OAuth callback. The browser sheet closed without handing back a code. Usually you cancelled, or the host's page errored. Try again; if it keeps happening, check the host is reachable and the Client ID is right.
- OAuth (auth code) not supported by this service. The host entry you picked has no browser sign-in. Use its access-token row instead.