# Git over HTTPS and SSH

Clone and push with plain git over HTTPS or SSH, sign in with a token or an SSH key, push an existing repository, and fix the errors a push can return.

## Push an existing repository

```sh
sailfork auth login
git remote add origin https://git.sailfork.com/fenil/ocean-landing.git
git push -u origin main
```

`sailfork auth login` makes git sign in for you, so the push needs no password. Plain git is all you need after that: Sailfork speaks the normal git protocol over HTTPS and SSH.

## Remote addresses

| Transport | Address |
| --- | --- |
| HTTPS | `https://git.sailfork.com/<owner>/<repo>.git` |
| SSH | `ssh://git@git.sailfork.com:2222/<owner>/<repo>.git` |

The **Clone** box on a repository's page shows both, and `sailfork repo view --json=cloneUrl` prints the HTTPS one. The older `https://status.sailfork.com/<owner>/<repo>.git` address keeps working, so remotes you made earlier still push. Leave the `.git` ending on HTTPS addresses.

Change a remote that points elsewhere, for example after a [move from GitHub](https://status.sailfork.com/docs/migrate):

```sh
git remote set-url origin https://git.sailfork.com/<owner>/<repo>.git
```

## HTTPS with an access token

Git uses HTTP Basic authentication. The username is your handle and the password is an access token. The handle must be the one the token belongs to, and is compared without regard to case.

```sh
git clone https://git.sailfork.com/fenil/ocean-landing.git
# Username: fenil
# Password: <access token>
```

Plain `git clone` always fetches everything. For a large repository, `sailfork repo clone` can fetch less, using the clone defaults its admins set. See [Clone defaults](https://status.sailfork.com/docs/repositories#clone-defaults).

Create a token under **Settings**, **Keys and tokens**, **Access tokens**, with `sailfork token create`, or with `POST /api/tokens`. See [Access tokens](https://status.sailfork.com/docs/tokens).

| To do this | The token needs |
| --- | --- |
| Clone or fetch a private repository | `repo:read` |
| Push | `repo:write` |

A token limited to certain repositories answers 403 everywhere else. Public repositories can be cloned and fetched with no credentials at all.

### The credential helper

You rarely type a token. `sailfork auth login` and `sailfork auth setup-git` make `sailfork` git's credential helper for the git address, with two entries in your global git config:

```sh
credential.https://git.sailfork.com.helper
http.https://git.sailfork.com.proactiveAuth
```

The first points at sailfork, which answers git with the token of your sign-in. The second is set to `basic`, so git sends the credentials on its first request instead of after a 401. Git older than 2.46 ignores it and still works. `login` leaves things alone when another helper already answers for that address. To take over from it, run `sailfork auth setup-git`, or `sailfork auth setup-git --local` to change only the clone you are in. `sailfork auth logout` removes the helper. The flags are listed in [Install the CLI](https://status.sailfork.com/docs/install#connect-git).

If git still asks for a password, run `sailfork doctor`. It checks that the helper is set and that it answers.

## SSH

SSH uses a public key and no password. The server offers no shell. A connection that is not a git command gets `Hi <handle>! You've successfully authenticated, but sailfork does not provide shell access.`

### Add a key

In the web app, open **Settings**, **Keys and tokens**, **SSH keys** and choose **Add key**. Paste the public key, give it a title (it defaults to the key's comment), and choose its use:

- **Push and pull** signs you in over SSH.
- **Signing commits** marks your commits verified. A signing key does not sign in. To use one key for both, add it twice.

The page asks you to prove the key is yours by signing a short message with `ssh-keygen -Y sign`. From the CLI that happens for you:

```sh
sailfork key add ~/.ssh/id_ed25519.pub --title "work laptop"
sailfork key add ~/.ssh/signing.pub --signing
sailfork key list --kind signing
sailfork key delete <id>
```

`key add` takes a file, or `-` for stdin. Piped in, the key cannot be proven, so it is added unproven. Registering a public key proves nothing by itself, so a proven registration of the same key on another account takes precedence over an unproven one. Adding a key needs a token with the `user` scope.

Then clone over SSH:

```sh
git clone ssh://git@git.sailfork.com:2222/fenil/ocean-landing.git
sailfork repo clone fenil/ocean-landing --protocol ssh
```

`sailfork repo clone --protocol ssh` falls back to HTTPS, and says so, when port 2222 cannot be reached from your network.

### Accepted key types

| Key | Notes |
| --- | --- |
| `ssh-ed25519` | Recommended. |
| `ecdsa-sha2-nistp256`, `-nistp384`, `-nistp521` | ECDSA. |
| `ssh-rsa` | 2048 bits or more. Signatures use SHA-256 or SHA-512, never SHA-1. |
| `sk-ssh-ed25519@openssh.com`, `sk-ecdsa-sha2-nistp256@openssh.com` | Security keys. |

DSA keys are refused. If yours is old or small, make a new one:

```sh
ssh-keygen -t ed25519
```

To match a key to the list on the page, `ssh-keygen -lf ~/.ssh/id_ed25519.pub` prints the fingerprint shown under it.

### Sign your commits

After you add a signing key, tell git to use it:

```sh
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
```

## Git LFS

Sailfork serves the standard Git LFS API, so `git lfs install`, `git lfs track` and a normal `git push` work with no extra setup. LFS uses the same credentials as git over HTTPS: an access token as the password. File contents go straight to object storage through short-lived signed links, and a file up to 100 GiB uploads in parts. A repository holds up to 1 TiB of LFS objects, and they count toward your plan's storage. See [Limits](https://status.sailfork.com/docs/limits).

## Limits

A push is bounded in size. A push over the limit stops with `the pack is over the <bytes>-byte push limit`, and a single object over the object limit with `an object in the pack is <n> bytes, over the <bytes>-byte object limit`. Push a large history in parts: push one branch or an older slice first, then the rest. See [Limits](https://status.sailfork.com/docs/limits) for the current numbers.

Someone without write access to a public repository can push only to branches named `contrib/<their handle>/...`, at most 20 of them per repository, and at most 256 MiB per push.

## Common errors

| What you see | Cause and fix |
| --- | --- |
| `authentication required` (401) | No credentials, or ones that do not check out. Run `sailfork auth login`, or give git a handle and a valid token. A private or missing repository answers 401 before you sign in, so its existence is not revealed. |
| `insufficient_scope: this token needs repo:write` | The token can read but not push. Make one with `repo:write`. |
| `repository not found` (404), or over SSH `ERROR: Repository not found.` | The name is wrong, or the repository is private and your account cannot see it. Check the owner and spelling. A repository scheduled for deletion also answers 404. |
| `you do not have permission to push to this repository` (403) | You can read it but not write to it. Ask an owner for write access, or push a `contrib/<your handle>/...` branch to a public repository and open a pull request. |
| `this repository is a mirror of <remote> and is read-only: push there instead` | It is a pull mirror. Push to the remote it follows. |
| `protected branch: changes to <branch> must go through a pull request` | A branch rule requires a pull request. Push another branch and open one. See [Branches and protection](https://status.sailfork.com/docs/branches). |
| `protected branch: force push is not allowed` and `protected branch: deleting it is not allowed` | A branch rule forbids rewriting or deleting it. |
| `you can only push to contrib/<handle>/ here: push your branch as contrib/<handle>/<name>, then open a pull request from it` | You are pushing as an outside contributor. Rename the branch as the message says. |
| `<org> requires two-factor authentication: add a passkey or an authenticator app in Settings, Security to get back in` | The organization requires a second factor and you have not set one up. |
| `could not check your credentials right now, try again shortly` (503) | The server could not check the token. Retry. |

For the REST status codes, see [the REST API](https://status.sailfork.com/docs/api). To check a whole setup at once, see [`sailfork doctor`](https://status.sailfork.com/docs/install#check-your-setup).

---

Every docs page: https://status.sailfork.com/llms.txt
