Initial docs: creating repos, importing codebases, going public

1 files changed, 68 insertions, 0 deletions

diff --git a/making-a-repo-public.md b/making-a-repo-public.md
new file mode 100644
index 0000000..080951c
--- /dev/null
+++ b/making-a-repo-public.md
@@ -0,0 +1,68 @@
+# Making a repo public (cgit)
+
+SSH access (gitolite) and web visibility (cgit) are **completely
+independent**. Every repo — whether created by an admin or self-created
+under `personal/<you>/...` — starts private: pushable/pullable over SSH
+by whoever gitolite grants access to, but invisible on
+`https://git.veltar.systems`.
+
+Making a repo browsable on the web is an **admin-only, server-side**
+step — it's not something you can do from a `git push`, and that's
+deliberate: it's the actual privacy boundary. Only repos explicitly
+listed get served; everything else silently doesn't exist as far as the
+web UI is concerned, regardless of who can SSH into it.
+
+If you're not an admin, ask one to do this for you (tell them the repo
+path, e.g. `personal/bryan/my-project`, and what description you want
+shown). If you are the admin, here's the process:
+
+## 1. SSH into gwaihir directly (not through gitolite — an actual shell)
+
+```bash
+ssh root@gwaihir
+```
+
+## 2. Add a stanza to `/etc/cgitrc`
+
+```
+repo.url=personal/bryan/my-project
+repo.path=/home/git/repositories/personal/bryan/my-project.git
+repo.desc=A short description shown on the repo list
+```
+
+`repo.url` is what shows up in the URL
+(`https://git.veltar.systems/personal/bryan/my-project/`) and can be
+whatever you like — it doesn't have to match the gitolite path, though
+keeping them the same avoids confusion.
+
+## 3. Reload nginx
+
+```bash
+nginx -t && systemctl reload nginx
+```
+
+That's it — no restart of cgit/fcgiwrap needed, cgit re-reads `/etc/cgitrc`
+on every request (it's a CGI process spawned fresh each time, not a
+long-running daemon).
+
+## 4. Verify
+
+```bash
+curl -s https://git.veltar.systems/ | grep my-project
+```
+
+You should see it listed on the index page, with working tree/log/diff
+links.
+
+## Un-publishing a repo
+
+Delete (or comment out) its `repo.url`/`repo.path`/`repo.desc` block from
+`/etc/cgitrc` and reload nginx the same way. This does not touch
+anything in gitolite — SSH access is unaffected either way.
+
+## A note on partial privacy
+
+If you ever want a repo browsable over HTTP but gated behind a password
+rather than either "fully public" or "fully hidden," that needs a
+separate nginx `location` block with `auth_basic` wrapping just that
+repo's path — not covered here, ask if you need it.