docs/users.org

  1#+title: gitbay user guide
  2
  3Everything here works from stock OpenSSH — replace =gitbay= with
  4=ssh git@<host>= in any command and it behaves identically. The CLI adds
  5convenience (instance profiles, repo inference, =$EDITOR=), nothing more.
  6=ssh git@<host> help= lists every command the server knows.
  7
  8* Installing the CLI
  9
 10#+begin_src sh
 11go install gitbay.org/gitbay/cmd/gitbay@latest   # any platform with Go
 12
 13brew tap krz/tap https://gitbay.org/krz/homebrew-tap.git
 14brew install krz/tap/gitbay                      # Homebrew (macOS/Linux)
 15#+end_src
 16
 17Or build from source: =go build ./cmd/gitbay= in a clone of
 18=https://gitbay.org/krz/gitbay.git=.
 19
 20* Getting an account
 21
 22How you join depends on the instance's registration mode. On instances
 23with web accounts enabled, =/register= offers the same signup as a
 24browser form (paste your SSH public key); everything below works from
 25the terminal alone:
 26
 27- closed :: an admin creates your account on the host and registers your
 28  first SSH key. Nothing for you to do but hand over your public key.
 29- invite :: you receive a single-use code by email. With the SSH key you
 30  want to use:
 31  #+begin_src sh
 32  ssh git@<host> register --username you --invite <code>
 33  #+end_src
 34  Your account is active immediately; the invited address is your
 35  verified email.
 36- open ::
 37  #+begin_src sh
 38  ssh git@<host> register --username you --email you@example.org
 39  #+end_src
 40  A verification code arrives by mail. Until you run
 41  =ssh git@<host> email verify <code>=, the account is pending: you can
 42  run =whoami= and the email commands, and nothing else — no git, no
 43  repos.
 44
 45* SSH keys
 46
 47Your key is your identity; there are no passwords anywhere. The SSH
 48username is always =git= — the key alone determines who you are.
 49
 50#+begin_src sh
 51gitbay auth keys list
 52gitbay auth keys add --scope git < ~/.ssh/ci_key.pub   # key on stdin
 53gitbay auth keys remove SHA256:...
 54#+end_src
 55
 56Scopes: =full= (default; git plus every control command) or =git= (git
 57transport only — right for CI and automation keys, which then cannot
 58touch issues, settings, or your account).
 59
 60A key belongs to exactly one account instance-wide. Registering a key
 61someone else already holds is refused without telling you whose it is.
 62
 63* Verified commits
 64
 65The commit badge is driven by the *author* email and the signing key:
 66=verified= means the signature is valid, the key is registered to an
 67account, and the author email is a verified address on that account.
 68
 69For OpenPGP signing (git's default):
 70#+begin_src sh
 71gpg --armor --export you@example.org | gitbay auth pgp add
 72#+end_src
 73
 74For SSH signing (=git config gpg.format ssh=): sign with any key
 75registered on your account; your verified addresses act as the principal
 76set. No separate registration step.
 77
 78Add and verify additional addresses with =email add <address>= /
 79=email verify <code>= (requires the instance to have SMTP; otherwise an
 80admin can assert an address for you).
 81
 82The states you will see, in decreasing order of trust: =verified=,
 83=signed_unknown_key= (valid signature, key not registered here — register
 84it and history upgrades retroactively), =signed_email_mismatch= (real
 85key, author line claims someone else), =signed_key_expired= /
 86=signed_key_revoked=, =bad_signature=, =unsigned=. Server-created commits
 87(web edits, merge commits) are always =unsigned= — the server holds no
 88signing key on principle.
 89
 90* Repositories
 91
 92#+begin_src sh
 93gitbay repo create you/project [--private]
 94gitbay repo clone you/project
 95gitbay repo list
 96gitbay repo show you/project
 97gitbay repo log you/project --limit 20      # commits with signature states
 98gitbay repo fork other/project [--name mine]
 99gitbay repo delete you/project --yes
100#+end_src
101
102Pushing is SSH-only. Public repositories are anonymously readable over
103HTTPS (and =git://= where enabled); private repositories exist only over
104SSH and answer "not found" to everyone without access.
105
106Access and settings (owner or =admin= grant):
107#+begin_src sh
108gitbay repo access grant you/project alice write    # read | write | admin
109gitbay repo access revoke you/project alice
110gitbay repo settings protect you/project main       # no force-push, no delete
111gitbay repo settings require-signed you/project on  # every commit must verify
112gitbay repo settings git-daemon you/project on      # expose over git://
113gitbay repo topics add you/project cli forge        # free-form tags, shown on the web
114gitbay repo search forge                            # find repos by name/description/topic
115gitbay repo grep you/project "some string"          # literal git grep over the default branch
116gitbay repo pin you/project                         # pin to your web dashboard
117gitbay repo unpin you/project
118gitbay repo archive you/project                     # read-only: pushes and issue/MR
119gitbay repo unarchive you/project                   #   writes refused, browsing intact
120#+end_src
121
122Import from another forge — git data first, then optionally the GitHub
123issue and PR history (issues keep state/labels/comments; PRs land as
124closed or merged MRs with their discussion; originals are attributed
125inline since foreign authors have no local account; re-running resumes
126where it stopped):
127#+begin_src sh
128gitbay repo import you/mirror --from https://github.com/you/repo.git \
129    [--private] [--token-stdin]        # token on stdin, never in the URL
130gitbay repo import-issues you/mirror --from you/repo --token-stdin
131#+end_src
132
133Moving between gitbay instances (no lock-in): run on the TARGET, with
134your key registered on both sides. Profile, repos with settings,
135issues, MRs, and comments replay with attribution; git data mirrors
136client-side through your own key. Keys never transfer and emails
137arrive unverified — trust is per-instance. Re-running resumes.
138Push-blocking policies (require-signed, protected branches) are
139deferred and printed for you to re-apply after the data lands.
140=gitbay auth export= alone doubles as a user-level backup.
141
142#+begin_src sh
143gitbay migrate --from old-instance.example [--from-port 22]
144#+end_src
145
146Mirroring keeps a foreign remote in sync during a gradual migration
147(repo admin; https remotes; the token is stored server-side for the
148recurring sync and never echoed back):
149
150#+begin_src sh
151gitbay repo mirror add you/project https://github.com/you/project.git \
152    --direction push --token-stdin    # propagate after every local push
153gitbay repo mirror add you/copy https://github.com/them/theirs.git \
154    --direction pull                  # follow upstream; local pushes refused
155gitbay repo mirror list               # sync status and last error, per mirror
156gitbay repo mirror sync / remove <id>
157#+end_src
158
159* Organizations
160
161Orgs share the owner namespace with users and own repositories at
162=org/repo=. Members get write on all org repos; org admins get repo
163admin, create repos under the org, and manage membership.
164
165#+begin_src sh
166gitbay org create krz
167gitbay org members add krz alice [--role admin]
168gitbay org show krz
169gitbay org rename krz newname     # clone URLs change
170gitbay org delete krz --yes       # only when it owns no repositories
171#+end_src
172
173* Issues
174
175Anyone who can read a repository can file and comment. Closing/reopening
176is for the author or anyone with write; labels and assignees need write.
177
178#+begin_src sh
179gitbay issue create --title "it breaks" [--body "..." | --file -]
180gitbay issue list [--state open|closed|all]
181gitbay issue show 4
182gitbay issue comment 4 --message "same here"
183gitbay issue edit 4 --title "better title" [--body|--file -]  # author or write
184gitbay issue close 4 / reopen 4
185gitbay issue label 4 --add bug --remove wontfix
186gitbay issue assign 4 --add alice
187gitbay issue milestone 4 v1.0                 # or "none" to clear
188#+end_src
189
190Inside a clone, the repository is inferred from the =origin= remote —
191that is why no =owner/name= appears above. Anywhere else, pass it as the
192first argument. Long text: =--body= inline, =--file -= from stdin, or
193neither on a terminal and =$EDITOR= opens.
194
195Releases anchor notes and binary assets to a pushed tag (write access;
196assets stream over SSH, capped by the instance's =max_asset_bytes=):
197
198#+begin_src sh
199gitbay release create v1.0 --title "First light" [--notes|--file -|$EDITOR]
200gitbay release asset add v1.0 tool-linux-amd64 < dist/tool-linux-amd64
201gitbay release asset get v1.0 tool-linux-amd64 > tool   # or the web download link
202gitbay release list / show v1.0 / delete v1.0 --yes
203#+end_src
204
205The web shows them under the repository's =releases= tab with rendered
206notes, sha256 sums, and download links.
207
208Commit messages act on issues when the commits land on the default
209branch (direct push or MR merge): =closes/fixes/resolves #4= closes the
210issue with a linking comment, and a bare =#4= leaves a reference
211comment. Each issue/commit pair acts once, ever. Same repository only.
212
213Milestones group issues and MRs toward a release (write access to
214manage, attach with =issue milestone= / =mr milestone=; progress shows
215on the web at =/owner/name/milestones=):
216
217#+begin_src sh
218gitbay milestone create v1.0 --description "first release" --due 2027-01-01
219gitbay milestone list [--state open|closed|all]
220gitbay milestone close v1.0 / reopen v1.0
221#+end_src
222
223Issue templates: commit =.gitbay/issue-template.md= (and optional
224=issue-template-<name>.md= variants) to the default branch. =gitbay
225issue create= prefills =$EDITOR= with the default template, the web
226form prefills its textarea, and =gitbay issue templates= lists them.
227
228* Merge requests
229
230#+begin_src sh
231gitbay mr create --source feature --target main --title "add thing"
232gitbay mr create other/upstream --source you/fork:feature --target main --title "..."
233gitbay mr list / show 4 / diff 4
234gitbay mr checkout 4              # local branch mr/4 from the MR head
235gitbay mr review 4 --approve      # or --request-changes / --comment
236gitbay mr merge 4 [--strategy ff|merge|squash|rebase]
237gitbay mr close 4
238#+end_src
239
240Semantics worth knowing:
241
242- the MR head lives in the *target* repository as
243  =refs/merge-requests/N/head= (fetchable by any reader), so an MR
244  survives deletion of its source branch or fork.
245- force-pushing the source updates the MR and marks existing reviews
246  stale.
247- default strategy: fast-forward when possible, else a merge commit.
248  Squash makes one commit authored by the MR author, committed by the
249  merger. Rebase replays a linear range preserving authors; it refuses
250  ranges containing merge commits, and when fast-forward is possible it
251  *is* one (original commits and signatures land untouched).
252- on =require_signed_commits= branches only fast-forwards of fully
253  verified commits merge; everything server-created is refused with
254  instructions to rebase locally.
255
256Repo admins can gate merges (=repo settings ...=): =require-approvals
257<n>= (fresh, non-author approvals; each reviewer's latest review is
258their stance, and a fresh request-changes blocks), =require-resolved=
259(no open review threads), =require-checks= (all statuses green). With
260approvals required, a =CODEOWNERS= file on the target branch (root or
261=.gitbay/=) additionally demands an approval from an owner of every
262owned changed file — gitignore-style patterns, last match wins.
263
264Review threads anchor to diff lines:
265
266#+begin_src sh
267gitbay mr diff-comment 4 --path main.go --line 12 --message "use log here"
268gitbay mr diff-comment 4 --reply 7 --message "done"     # join thread 7
269gitbay mr threads 4                                     # threads with staleness
270gitbay mr resolve 4 7 / unresolve 4 7
271#+end_src
272
273Threads render inline on the MR page. A force-push marks them stale
274(shown under "threads on earlier revisions") rather than guessing new
275anchors; =mr show= reports the unresolved count. Resolving is for the
276thread author, the MR author, or anyone with write.
277
278* Notifications
279
280When the instance has SMTP configured, activity mails you: someone
281opens an issue or MR on your repository, comments where you are a
282participant (author, commenter, reviewer), reviews, closes, or merges.
283You are never mailed about your own actions, and only verified primary
284addresses receive anything. Delivery retries on relay failure.
285
286* Scripting
287
288Every read command takes =--json= and emits one envelope:
289={"protocol_version": 1, "data": ...}=. stdout is data, stderr is
290messages. Exit codes are stable: 0 ok, 1 failure, 2 usage, 3 not found,
2914 denied, 5 server/protocol error. Nothing ever prompts; destructive
292commands take =--yes=.
293
294For HTTP automation see =docs/api.org=.
295
296* CLI setup
297
298#+begin_src sh
299gitbay remote add myforge forge.example.org [--port n] [--user u] --default
300gitbay remote list
301gitbay init [name] [--private]   # git init + repo create + origin, in one step
302#+end_src
303
304Configuration lives at =~/.config/gitbay/config.toml=. The CLI shells
305out to your real =ssh=, so =~/.ssh/config=, the agent, and hardware keys
306all apply. Man pages: =gitbay man --dir <dir>=; completions:
307=gitbay completion bash|zsh|fish=.