origin. When you start a project on New project, choose where it comes from:
- GitHub repository (where your r5d offers GitHub, as r5d.dev does): an existing repository of a GitHub account, or a new one r5d creates. r5d imports, pulls and pushes with the GitHub account you connected for repository access (Connect GitHub repositories, also in Settings → Git), which can be any GitHub account, whichever way you sign in to r5d. r5d finds each branch’s pull request, with its state, and opens one for you with Create pull request.
- SSH remote (any git host): a repository on GitLab, GitHub Enterprise Server, Gitea, Forgejo, Bitbucket or any other host that accepts SSH. r5d generates an SSH key for it.
- HTTPS remote (any git host): a repository on any host you reach over HTTPS, with a username and access token you enter for the project, or your account’s for the host, or none for a public repository.
- No remote: r5d creates the project with a first commit (a
README.md). Pull, Push and reviews are unavailable until you add a remote.
SSH remotes
Enter the repository’s SSH URL, eithergit@gitlab.com:group/repo.git or ssh://git@git.example.com:2222/group/repo.git. Once you have connected GitHub repositories, github.com repositories use the GitHub option instead; until then, and on an r5d that doesn’t offer GitHub, they are SSH remotes like any other host’s.
The key
If you have an account key for the host (see Git hosts), it is selected and the project needs no key step. Otherwise, or if you choose Generate a deploy key for this project, r5d generates a key for this project and shows its public key (ssh-ed25519 AAAA… r5d <project>@<r5d host>). Copy it and add it on the host:
- GitLab: the repository’s Settings → Repository → Deploy keys, with Grant write permissions to this key.
- GitHub Enterprise Server, Gitea, Forgejo: the repository’s deploy keys, with write access.
- Hosts whose deploy keys are read-only (for example Bitbucket Cloud access keys): add the key to a user account’s SSH keys instead. The key then has that account’s access.
The host key
r5d reads the host’s SSH key and shows its SHA-256 fingerprint. Compare it with the fingerprint the host’s administrators publish, then choose Confirm host key. github.com, gitlab.com and bitbucket.org publish their keys, so r5d pins them without asking. If a host later presents a different key, Pull, Push and imports fail with a host key changed error, and the project’s settings show the new fingerprint. Confirm it only if you know why the key changed.Check access
Check access tests read access, and write access with a dry run that changes nothing on the host. It names whatever is missing, for example a deploy key without write access. Once read access works, the same check imports the repository and then shows the project ready, or why the import failed; an empty repository starts with a first commit. Until then the project waits, and you can check again from the project’s settings.SSH host aliases
If you reach a host at another address or port than the one your remote URLs name, asHostName and Port do in ~/.ssh/config:
gitlab.example.com, with :port only for ssh:// URLs that name one) and the address r5d connects to (192.168.2.19:2222, a host name or an IP address). Remote URLs stay as the host shows them, such as git@gitlab.example.com:group/repo.git, and so do the host’s keys and its pinned host key: a machine at the alias’s address must present the host’s own key.
r5d then connects to that address everywhere it runs SSH for you: from its server for the host key, Check access, imports and reading the remote, from your workers for Pull and Push, and in your agents’ git commands that use r5d’s keys. Each of these must reach the address, so an address only your office network reaches works only where r5d and your workers run inside it. When the address changes, edit the alias. A worker needs a current r5d-worker for Pull and Push through an alias.
HTTPS remotes
Enter the repository’s HTTPS clone URL, as the host shows it:https://gitlab.com/group/repo.git, https://git.example.com/acme/website.git. On GitLab it ends in .git: r5d follows no redirect. Enter the username and password separately, never in the URL; plain http:// isn’t accepted.
Credentials
Enter a username and an access token (or a password, where the host accepts one for git):- GitLab: a personal, project or group access token with
read_repositoryandwrite_repository. Any username works. - GitHub (where you haven’t connected GitHub repositories): a fine-grained personal access token with read and write access to the repository’s contents. Any username works.
- Gitea, Forgejo: an access token with read and write access to repositories, with your username.
- Bitbucket: an access token with the username
x-token-auth, or an app password with your username. - Others, such as git-mcp: whatever the host takes for git over HTTPS. Without a username, r5d sends
git, which hosts that read only the token accept.
Hosts r5d’s server reaches
r5d’s server reads the repository itself (imports, Check access, the remote’s branches), so it must reach the host over HTTPS with a certificate a public CA signed. It reaches public hosts; a host on a private network only where your r5d’s administrator allows it (Admin settings, internal hosts). A self-signed certificate, one a company’s own CA signed, an expired one or one for another host name fails with couldn’t verify the host’s TLS certificate.Pull, Push and agents
Pull and Push on a branch’s Git page work for SSH and HTTPS remotes as for GitHub. Your agents’ owngit fetch, git pull and git push in the project’s checkout use the project’s key without any SSH setup on the worker. A key r5d chooses is used alone, with the host key you confirmed.
Reviews on an SSH remote
r5d doesn’t look up the merge requests or pull requests of an SSH remote’s host. When a conversation opens one (an agent with the host’s CLI, such asglab, or you in the host’s web pages), it attaches the link to the conversation, and the branch shows it as its review, without its state:
!12 on a GitLab, #12 elsewhere; without a kind it reads as its host and path.
Other remotes you add yourself with git remote add, and any host r5d has no key for, use your own SSH keys and ~/.ssh/config on the worker.
Over HTTPS, your agents’ git fetch, git pull and git push in the project’s checkout use the remote’s credential, and git clone of another repository on a host with an account credential works anywhere, for example in an account workspace chat. Hosts r5d has no credential for use your own credential helpers on the worker.
Commands r5d runs on the worker can read the key and credential files r5d delivers: the project’s key or token in that project’s conversations, and your account keys and HTTPS host credentials in all of your conversations. r5d never puts a key or token in a prompt or transcript.
What r5d reads and fetches from the remote
r5d shows how each branch stands against the remote’s branch of the same name: in step, commits not pushed, commits behind, or diverged, in the sidebar (↑2 on a session’s row, the rest in its card), in the branch’s header and on its Git page, which always agree. To know, it reads the heads of the remote’s branches, all of them in one request, and keeps those of your project’s branches: after a conversation finishes, after Pull and Push, when you open a branch, and every few minutes while the project is in use. When a read fails, r5d keeps what the last read said and adds Remote unavailable, with why and when the remote was last read. When a branch on the remote has commits r5d doesn’t have, because someone pushed them from outside r5d (a teammate, CI, the host’s web editor), r5d fetches those commits to count them:- Without file contents: only the commits and their folder listings, never the files.
- Only your branches: the remote’s heads of the branches your project has in r5d, its primary branch among them. Other branches on the remote are read, not fetched.
- With the project’s own access: the GitHub account connected for repository access, the project’s SSH key with the host key you confirmed, or the HTTPS remote’s credential.
- Kept only to count: the fetched commits stay in a temporary copy on r5d’s server, which holds no file contents. They are not added to your branch, its checkout or any worker; Pull brings them into the branch.
A git server of your own
r5d fetches only from a host that offers to leave file contents out of a fetch (Git’s partial clone filter), as GitHub does. On a server of your own that serves Git over SSH, allow it for every repository, or in one repository’s config:Branch history on every worker
Every worker keeps a checkout of every branch of your projects, set up in the background and kept current as branches move, whichever worker their conversations run on. A checkout starts with the branch’s latest 50 commits. Older history and earlier versions of files come from r5d when a Git command needs them, through the checkout’sr5d remote, so git log -p and git blame work as usual. For more history at once:
r5d remote only fetches, and only while the worker runs; your commits reach r5d when the worker publishes the checkout. git fetch --all leaves it out.
Project settings
The project’s Repository settings show the remote, the key it uses with its fingerprint and last use, the host key, and the last Check access. There you can:- Replace key: r5d generates a new key and switches to it once Check access succeeds with it. The old key keeps working on the host until you remove it there. Cancel replacement discards the new key and keeps the current one.
- Use account key or Use a deploy key instead: switch between the project’s own key and your account key for the host. Switching to the account key first checks that it can read the repository.
- Remove remote: the project keeps its branches and history and has no remote afterwards. r5d deletes the project’s deploy key; remove it on the host too. Deleting the project also deletes its key.
- Add a remote to a project without one: a GitHub repository (where your r5d offers GitHub), an SSH remote or an HTTPS remote. The project keeps its history; r5d only records the remote.
Git hosts (account keys)
If you work with many repositories on one host, add an account key for the host once instead of a deploy key per repository: Settings → Git → Add host, with the host name and its SSH port if it is not 22. r5d generates a key and shows its public key. Add it to your user account on the host (on GitLab: User settings → SSH Keys), confirm the host key, and choose Check access. A repository path is optional; with one, Check access also tests read and write access to that repository. An account key acts as you on that host: it reaches every repository your account there can reach. A deploy key reaches one repository, which is why deploy keys stay available and take precedence: a project with its own deploy key keeps using it. With an account key:- adding a project from that host needs no key step, only Check access;
- agents can use the host anywhere, for example
git clone git@gitlab.company.com:group/other.gitin an account workspace chat.
HTTPS hosts (account credentials)
If you reach many repositories on one host over HTTPS, save its credential once instead of one per project: Settings → Git → HTTPS hosts → Add host, with the host name (and:port if its HTTPS port isn’t 443), a username and an access token. Every HTTPS remote on that host without credentials of its own uses it, and so do your agents’ git commands anywhere. Check access with a repository path tests reading it and a dry-run push.
An account credential acts as you on its host, with everything your token can reach there; a project’s own token can be narrower, which is why it takes precedence. Removing a credential that projects use lists them and asks for confirmation; they then reach their remote without credentials until you give them some.
Host kinds
r5d labels a link to an issue or a review as its host writes it, names reviews as the host does and links to the host’s branches and commits once it knows what the host is: its kind. Settings → Git → Host kinds lists your git hosts with their kinds:
github.com, gitlab.com and bitbucket.org are built in, so a
github.com pull request reads #418 even when you reach github.com over SSH. Your r5d’s administrator can set a host’s kind for everyone (Admin settings → Git hosts); such a host shows this installation and keeps that kind. Choose a kind for any other host in its row, or enter a host and its kind and choose Set kind, with the host name alone (git.example.com, without ssh://, a user or a port); only you see the kinds you set, and links you already have are relabelled. Without a kind, a link reads as its host and path, and r5d makes no links to the host.
If a host’s web pages have another name than its SSH host, set the kind of that name too: links are labelled by the name in their URL.