Skip to content
Buzz Guide › Set up the workspace › Add a repository to a project
Task 2.2 · 2 of 5

Add a repository to a project

Project lead, performance consultant · Set up the workspace

Steps at a glance

  1. Decide where the repository will live
  2. Check that git is installed
  3. Add the repository to the project
  4. Get your files into it
  5. Confirm access and the file tree

Projects is a preview feature

Projects sits behind the experiments toggle in Settings and is under heavy active development. The behaviour on this page — in particular the limits on GitHub repositories — can change with any release. Last checked: Buzz v0.5.23 (main), 2026-09-10.

1. Decide where the repository will live

A project repository can live in one of two places, and the choice decides who can read it.

Hosted on your relay. Buzz runs its own git server on the community relay, at https://<your-relay>/git/<owner-pubkey>/<repo-id>. Access is decided by the channel the repository is attached to: only channel members can clone it. Nothing runs outside the community, and no external account is involved. This is the option for anything private, and for any client work.

External, on GitHub. The repository stays on GitHub and Buzz reads it from there. Buzz clones GitHub repositories without credentials, which means only public GitHub repositories work. A private GitHub repository shows Could not load the repository file tree in the Files panel, and there is no GitHub token, GitHub App or Buzz user you can add to fix it. If the work must stay private and must stay on GitHub, you cannot bring it into a Buzz project today; keep GitHub as a backup remote instead and host the working copy on the relay.

2. Check that git is installed

The desktop app runs the git that is installed on your machine and handles authentication itself — it ships its own credential helper and signs each clone, fetch and push with your Buzz key. Nothing is written to your global git configuration, and no key touches disk.

Check the version in a terminal:

git --version

You need git 2.46 or later. Older versions do not support the credential protocol the helper relies on, and every relay-hosted operation fails with an authentication error. On macOS, brew install git gives a current version.

3. Add the repository to the project

Open the project, then Add repository.

Give it a short id (for example einspo) and choose the channel it belongs to — this is the access gate, so pick a private channel for anything you would not show the whole community.

The Clone URL field decides where the repository lives:

  • Leave it empty for a relay-hosted repository. Buzz announces the repository, seeds an empty repo on the relay, and clones it into the app's local repositories folder. The Files panel shows No files have been pushed yet until you push.
  • Paste a GitHub URL for an external repository. It must be public (see step 1). Check the owner and name character by character — tr0ndk/einspo and trondk/einspo are different repositories, and a typo produces the same error as a private repository.

4. Get your files into it

For a relay-hosted repository, the desktop app can push for you:

  1. Copy the contents of your existing working folder into the app's checkout — everything except the .git folder, unless you want to bring the history across.
  2. Commit in the checkout.
  3. In the Files panel, use Push (top right; the button appears when the local checkout is ahead). The app signs the push with your key.

If you want to keep working from your existing clone instead, add the relay as a remote and push from the terminal:

git remote add buzz https://<your-relay>/git/<owner-pubkey>/<repo-id>
git push -u buzz main

Pushing from outside the app needs the git-credential-nostr helper configured for your terminal git — the app's automatic authentication does not cover it. See the reference below; it is a one-time setup per machine.

Your key is your git identity

The relay verifies pushes by the signature of your Buzz key, not by a password. Anyone with your nsec can push as you. Keep the key file at 0600, never put a key on a git command line, and prefer a separate key per machine or agent so a leak does not take your whole identity.

5. Confirm access and the file tree

Open the project's Files panel. A relay-hosted repository shows the tree after the first push; an external one shows it as soon as the clone completes.

If the panel shows Could not load the repository file tree, work through the causes in order:

Cause How to tell Fix
GitHub repository is private Opening the GitHub URL in a private browser window gives 404 Host on the relay (step 1), or make the repository public
Wrong owner or name Same 404 in a private window Correct the clone URL and refresh
git older than 2.46 git --version; relay-hosted repositories fail with an authentication error Upgrade git
You are not a member of the repository's channel Repository access restricted Ask the channel owner to add you
Relay unreachable Couldn't reach the repository Check the connection and refresh

Refreshing is under the repository dropdown at the top of the Files panel.

Verified against Buzz v0.5.23 · Updated 10 Sep 2026