HachiCode

Appearance

SSH keys ​

SSH is one of three ways to reach a git host. The other two, OAuth sign-in and access tokens, work over HTTPS. Use SSH when the host does not offer OAuth (most self-hosted Gitea and Gogs instances), when you want a credential that never expires, or when your repositories are only reachable over SSH.

In HachiCode an SSH key belongs to a server, not to a git host name. You register the server once (host and port), trust its host key, and then add one or more identities under it. A Git over SSH identity is what a clone or push uses; a Remote folder access identity is what an SSH folder uses. Both live in the same place.

Add the server ​

  1. Settings → SSH Servers, tap +.
  2. Fill in Name, Host (just the host name, no ssh://, no git@, no path) and Port (22 unless your host says otherwise).
  3. Tap Save. Before the server is created the app reads the host's key and asks Trust this server?, showing the fingerprint. Compare it with the fingerprint your host publishes and tap Trust only if they match.

The server screen then shows an Auths section for identities and a Host key section with the trusted fingerprint and when you trusted it. Host and port are locked once an identity is bound to the server, because the identity is tied to that exact endpoint.

Add a Git over SSH identity ​

  1. On the server screen, tap + under Auths and choose Git over SSH.
  2. Give it a Name so you recognise it later.
  3. Either tap Generate new key pair, or paste an existing private key into Or paste a private key (PEM). Generated keys are Ed25519; pasted keys must be in OpenSSH format.
  4. The public key appears under Public key — add this to the server's authorized_keys. Tap it to copy.
  5. Tap Save.

Now add the public key to your account on the host:

Tap Test key afterwards. It signs in as git@<host> with the key and proves the key is authorized on the host. It does not check access to any particular repository; that is what the clone screen's own Test is for.

Passphrase-protected keys ​

Git identities have no passphrase field, and a pasted key that is still encrypted is refused with "Passphrase-protected SSH keys aren't supported for git yet." Decrypt the key first, for example with ssh-keygen -p on a laptop, or generate a fresh pair on the device.

Remote folder access identities do accept a Passphrase (optional). See SSH folders.

Where keys live ​

Private keys are stored in the iOS Keychain, restricted to this device and only available while a passcode is set. They are not written to the file system and do not ride along in backups. Removing the device passcode destroys them. The app reads the key only for the operation that needs it.

On an identity's screen, the key details button opens SSH key details: the key's comment, algorithm, SHA256 and MD5 fingerprints, and the public key with a copy button. Use it when you need to match the key against what your host displays.

Use the identity ​

Paste an SSH URL on the clone screen, either the git@host:owner/repo shorthand or ssh://git@host:port/owner/repo when the port is not 22. Turn on Require authentication and pick the identity. Only identities under the server whose host and port match the URL are offered, so the shorthand form always looks for a server on port 22.

A project keeps the identity you picked. Change it later in the project's settings under Authentication.

Replace or remove a key ​

Open the identity and generate or paste a new key; the note "A key is stored" reminds you the old one is kept if you leave the field empty. Projects bound to the identity keep working after the replacement.

Delete identity removes the key from the Keychain. It is refused while an SSH folder still uses the identity; Forget the folder first. Deleting the server removes every identity under it, and is refused while an SSH folder is still linked through it; Forget the folder first.

When the host key changes ​

If a server is rebuilt or rotates its key, the next operation stops with Host key changed. Open the server under Settings → SSH Servers and tap Check for change in the Host key section. The app reads the new key and asks you to confirm the new fingerprint before it trusts it. Do this only when you expected the change; an unexpected new key can mean someone is sitting between you and the server.

See also ​

Last updated: