krz/gitbay

  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* Getting an account
  9
 10How you join depends on the instance's registration mode:
 11
 12- closed :: an admin creates your account on the host and registers your
 13  first SSH key. Nothing for you to do but hand over your public key.
 14- invite :: you receive a single-use code by email. With the SSH key you
 15  want to use:
 16  #+begin_src sh
 17  ssh git@<host> register --username you --invite <code>
 18  #+end_src
 19  Your account is active immediately; the invited address is your
 20  verified email.
 21- open ::
 22  #+begin_src sh
 23  ssh git@<host> register --username you --email you@example.org
 24  #+end_src
 25  A verification code arrives by mail. Until you run
 26  =ssh git@<host> email verify <code>=, the account is pending: you can
 27  run =whoami= and the email commands, and nothing else — no git, no
 28  repos.
 29
 30* SSH keys
 31
 32Your key is your identity; there are no passwords anywhere. The SSH
 33username is always =git= — the key alone determines who you are.
 34
 35#+begin_src sh
 36gitbay auth keys list
 37gitbay auth keys add --scope git < ~/.ssh/ci_key.pub   # key on stdin
 38gitbay auth keys remove SHA256:...
 39#+end_src
 40
 41Scopes: =full= (default; git plus every control command) or =git= (git
 42transport only — right for CI and automation keys, which then cannot
 43touch issues, settings, or your account).
 44
 45A key belongs to exactly one account instance-wide. Registering a key
 46someone else already holds is refused without telling you whose it is.
 47
 48* Verified commits
 49
 50The commit badge is driven by the *author* email and the signing key:
 51=verified= means the signature is valid, the key is registered to an
 52account, and the author email is a verified address on that account.
 53
 54For OpenPGP signing (git's default):
 55#+begin_src sh
 56gpg --armor --export you@example.org | gitbay auth pgp add
 57#+end_src
 58
 59For SSH signing (=git config gpg.format ssh=): sign with any key
 60registered on your account; your verified addresses act as the principal
 61set. No separate registration step.
 62
 63Add and verify additional addresses with =email add <address>= /
 64=email verify <code>= (requires the instance to have SMTP; otherwise an
 65admin can assert an address for you).
 66
 67The states you will see, in decreasing order of trust: =verified=,
 68=signed_unknown_key= (valid signature, key not registered here — register
 69it and history upgrades retroactively), =signed_email_mismatch= (real
 70key, author line claims someone else), =signed_key_expired= /
 71=signed_key_revoked=, =bad_signature=, =unsigned=. Server-created commits
 72(web edits, merge commits) are always =unsigned= — the server holds no
 73signing key on principle.
 74
 75* Repositories
 76
 77#+begin_src sh
 78gitbay repo create you/project [--private]
 79gitbay repo clone you/project
 80gitbay repo list
 81gitbay repo show you/project
 82gitbay repo log you/project --limit 20      # commits with signature states
 83gitbay repo fork other/project [--name mine]
 84gitbay repo delete you/project --yes
 85#+end_src
 86
 87Pushing is SSH-only. Public repositories are anonymously readable over
 88HTTPS (and =git://= where enabled); private repositories exist only over
 89SSH and answer "not found" to everyone without access.
 90
 91Access and settings (owner or =admin= grant):
 92#+begin_src sh
 93gitbay repo access grant you/project alice write    # read | write | admin
 94gitbay repo access revoke you/project alice
 95gitbay repo settings protect you/project main       # no force-push, no delete
 96gitbay repo settings require-signed you/project on  # every commit must verify
 97gitbay repo settings git-daemon you/project on      # expose over git://
 98#+end_src
 99
100Import from another forge (git data only — issues and PRs do not
101transfer):
102#+begin_src sh
103gitbay repo import you/mirror --from https://github.com/you/repo.git \
104    [--private] [--token-stdin]        # token on stdin, never in the URL
105#+end_src
106
107* Organizations
108
109Orgs share the owner namespace with users and own repositories at
110=org/repo=. Members get write on all org repos; org admins get repo
111admin, create repos under the org, and manage membership.
112
113#+begin_src sh
114gitbay org create krz
115gitbay org members add krz alice [--role admin]
116gitbay org show krz
117gitbay org rename krz newname     # clone URLs change
118gitbay org delete krz --yes       # only when it owns no repositories
119#+end_src
120
121* Issues
122
123Anyone who can read a repository can file and comment. Closing/reopening
124is for the author or anyone with write; labels and assignees need write.
125
126#+begin_src sh
127gitbay issue create --title "it breaks" [--body "..." | --file -]
128gitbay issue list [--state open|closed|all]
129gitbay issue show 4
130gitbay issue comment 4 --message "same here"
131gitbay issue close 4 / reopen 4
132gitbay issue label 4 --add bug --remove wontfix
133gitbay issue assign 4 --add alice
134#+end_src
135
136Inside a clone, the repository is inferred from the =origin= remote —
137that is why no =owner/name= appears above. Anywhere else, pass it as the
138first argument. Long text: =--body= inline, =--file -= from stdin, or
139neither on a terminal and =$EDITOR= opens.
140
141* Merge requests
142
143#+begin_src sh
144gitbay mr create --source feature --target main --title "add thing"
145gitbay mr create other/upstream --source you/fork:feature --target main --title "..."
146gitbay mr list / show 4 / diff 4
147gitbay mr checkout 4              # local branch mr/4 from the MR head
148gitbay mr review 4 --approve      # or --request-changes / --comment
149gitbay mr merge 4 [--strategy ff|merge|squash|rebase]
150gitbay mr close 4
151#+end_src
152
153Semantics worth knowing:
154
155- the MR head lives in the *target* repository as
156  =refs/merge-requests/N/head= (fetchable by any reader), so an MR
157  survives deletion of its source branch or fork.
158- force-pushing the source updates the MR and marks existing reviews
159  stale.
160- default strategy: fast-forward when possible, else a merge commit.
161  Squash makes one commit authored by the MR author, committed by the
162  merger. Rebase replays a linear range preserving authors; it refuses
163  ranges containing merge commits, and when fast-forward is possible it
164  *is* one (original commits and signatures land untouched).
165- on =require_signed_commits= branches only fast-forwards of fully
166  verified commits merge; everything server-created is refused with
167  instructions to rebase locally.
168
169* Scripting
170
171Every read command takes =--json= and emits one envelope:
172={"protocol_version": 1, "data": ...}=. stdout is data, stderr is
173messages. Exit codes are stable: 0 ok, 1 failure, 2 usage, 3 not found,
1744 denied, 5 server/protocol error. Nothing ever prompts; destructive
175commands take =--yes=.
176
177For HTTP automation see =docs/api.org=.
178
179* CLI setup
180
181#+begin_src sh
182gitbay remote add myforge forge.example.org [--port n] [--user u] --default
183gitbay remote list
184gitbay init [name] [--private]   # git init + repo create + origin, in one step
185#+end_src
186
187Configuration lives at =~/.config/gitbay/config.toml=. The CLI shells
188out to your real =ssh=, so =~/.ssh/config=, the agent, and hardware keys
189all apply. Man pages: =gitbay man --dir <dir>=; completions:
190=gitbay completion bash|zsh|fish=.