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