Git transport

This page explains how git clients talk to Openhub. Pushes are accepted only over SSH, by a built-in SSH server. Clones and fetches work over SSH and over read-only smart HTTP. In every case the git protocol itself is handled by the installed git program, and Openhub decides who may run it against which repository.

Source files:

• src/ssh.rs: the SSH server.
• src/web/git_http.rs: smart HTTP.
• src/sync.rs: bookkeeping after a push.
• src/web/code.rs (archive): downloads.
• src/config.rs: clone URLs.

Channels at a glance

Clone URLs

Config builds the URLs shown in the Clone dropdown, in push hints and in the documentation pages:

The SSH host is --ssh-host, or failing that the host of --public-url. The SSH port is --ssh-port, or failing that the port of --ssh-addr. Set both when Openhub runs behind port forwarding, for example container port 2222 published as host port 22.

SSH server

The server is built on russh (ssh::serve) and listens on --ssh-addr.

Host key

On first start, Openhub generates an Ed25519 host key at <data>/ssh_host_ed25519_key, in OpenSSH format with mode 0600, and reuses it on every later start. Its SHA-256 fingerprint is logged at startup so users can check it. If the key is lost, every client sees a "host key changed" warning, so keep it in backups.

Server settings

Authentication

1. auth_publickey_offered. The client offers a public key, and Openhub accepts the offer only if its fingerprint is in ssh_keys. Clients therefore only sign with keys that will work, and move on to the next key otherwise.
2. auth_publickey. russh has verified the client's signature. Openhub loads the owning user, updates last_used_at and logs the sign-in with the peer address.

The SSH username is ignored. Anything works, but clone URLs use git.

Channel requests

Command parsing

parse_command accepts exactly these forms, which are what git clients send:

git-upload-pack '<path>'
git-receive-pack '<path>'
git upload-pack '<path>'
git receive-pack '<path>'

It then processes the path:

1. Removes surrounding single or double quotes.
2. Rejects the path if it still contains ', ", \ or a NUL byte.
3. Trims / from both ends, then removes a trailing .git.
4. Requires exactly owner/name.

Anything else, including git-upload-archive (that is, git archive --remote), gets ERROR: Openhub only supports git fetch and push over SSH. and exit status 1.

Authorisation and execution

SshSession::exec_request does the following:

1. Looks up the repository with db::repo_by_name and calls AppState::access.

2. Checks permissions:

   • No read access, or no such repository: ERROR: Repository not found.
   • receive-pack without write access: ERROR: You do not have permission to push to owner/name.

3. For receive-pack, records every branch tip (branch_tips), so push hints can tell what changed.

4. Spawns <git-bin> upload-pack|receive-pack <data>/repos/<id>.git:

   • The path comes from the database ID, never from the client's string.
   • No shell is involved.
   • stdin, stdout and stderr are piped.
   • kill_on_drop is set.
   • GIT_PROTOCOL is passed through when the client sent it.

5. Relays data:

   client ──SSH data──▶ SshSession::data ──unbounded mpsc──▶ task ──▶ git stdin
   client ◀─SSH data─── handle.data      ◀── forward() ◀───────────── git stdout
   client ◀─ext. data── handle.extended_data(1) ◀── forward() ◀────── git stderr
   client EOF ─────────▶ channel_eof drops the sender ──────────────▶ git stdin closed
   

6. After git exits, sends git's exit status, then EOF, then closes the channel.

Why the Channel object is dropped. channel_open_session drops russh's Channel handle on purpose and receives data through the data callback instead. Holding the handle without reading from it fills russh's per-channel buffer and deadlocks the session. The trade-off is that the queue to git's stdin is unbounded (see Security).

Protecting refs/pull

Every repository is created with receive.hideRefs=refs/pull. git receive-pack then neither advertises refs/pull/* nor accepts updates to it: a push there fails with deny updating a hidden ref. upload-pack still advertises these refs, so clients can fetch them.

After a push

When receive-pack exits with status 0, two things happen before the exit status is sent:

1. sync::after_push runs:

   • db::touch_pushed sets pushed_at.
   • git::ensure_head makes sure HEAD names an existing branch. It prefers the current default branch, then main, then master, then the first branch alphabetically. If it had to pick a different branch, repositories.default_branch is updated. That's how a repository's first push of a non-main branch becomes its default.
   • sync::refresh_pulls re-evaluates every open pull request in the repository. It records new heads and marks pull requests as merged when their head is now in the base (see Pull requests).

2. Push hints (push_hints): for each non-default branch whose tip changed in this push, Openhub prints one of the following on stderr. The client shows them prefixed with remote:.

   Create a pull request for 'feature' on Openhub by visiting:
        https://git.example.com/alice/project/compare/main...feature
   

   View pull request for 'feature':
        https://git.example.com/alice/project/pull/3
   

   Deleted branches and the default branch get no hint.

Errors in after_push are logged and don't fail the push, which by then has already been accepted.

Smart HTTP (read-only)

Routes, with {repo} accepting an optional .git suffix:

Details:

• Authorisation (git_http::authorize):
  • A missing repository gets 404.
  • A public repository needs no credentials.
  • A private repository needs Basic auth. Missing or wrong credentials get 401 with WWW-Authenticate: Basic realm="Openhub". Valid credentials without read access get 404.
• Protocol v2. The Git-Protocol header is passed through as GIT_PROTOCOL when it contains only [A-Za-z0-9=:.].
• Body limit. The git-upload-pack route accepts request bodies up to 64 MB (GIT_BODY_LIMIT in src/web/mod.rs). Negotiation for large repositories lists many commits. Other routes keep axum's 2 MB default.
• Middleware. These paths skip the session lookup and the cross-origin check, because git clients send neither cookies nor Origin (see ctx::is_git_request).
• Errors. git's stderr is discarded. Failures are logged and returned as 500 with a short message.

Archive downloads

GET /{owner}/{repo}/archive/{ref}.zip or .tar.gz (code::archive):

1. Checks read access with load_repo.
2. Resolves {ref} with git::resolve, which accepts a branch, tag or commit SHA. The ref must not include a path.
3. Runs git --git-dir <path> archive --format=zip|tar.gz --prefix=<repo>-<ref>/ <commit-sha> and streams stdout to the client as attachment; filename="<repo>-<ref>.<ext>". Any / in the ref becomes -.

git archive honours the repository's own .gitattributes, including export-ignore and export-subst. See Security for why that matters.

Protocol features

The installed git provides the protocol support:

• Protocol v0, v1 and v2.
• Shallow clones (--depth).
• Side-band progress.
• Atomic pushes.

Openhub doesn't set uploadpack.allowFilter, so partial clone filters (--filter=blob:none) are ignored by the server. It doesn't install hooks, and nothing in the protocol can write a repository's config or hooks. Git LFS isn't supported.

When you change this

• New SSH command: add it to Service and parse_command, together with its unit test. Decide which Access level it needs. Extend the smoke test.
• New post-push behaviour: put it in sync::after_push, so web merges and pushes share it where it applies.
• New git configuration for hosted repositories: add it to git::configure. Existing repositories don't pick it up automatically, so add a startup step if they need it.
• Changes to HTTP authentication: keep private repositories indistinguishable from missing ones, and keep pushes on SSH unless that is decided otherwise.