krz/gitbay

A CLI-first git forge. cli forge git self-hosted https://gitbay.org

Commit b1b9cddc02

b1b9cddc02117181510c5e0d11bd9fcf7ab38cc0

parent: 54013eb4e0

Verified · cmc

cmc <hello@cleberg.net> · 2026-08-25 16:58 UTC 

docs: CI builds, runner setup, pages

Layout: unified · split

Admin.org +28
@@ -182,6 +182,34 @@ Replace the binary, restart the unit. Migrations apply automatically and
182are transactional; hook scripts under =<root>/hooks= are rewritten at 182are transactional; hook scripts under =<root>/hooks= are rewritten at
183startup to point at the current binary path. 183startup to point at the current binary path.
184 184
185* CI runner
186
187=gitbay-runner= executes builds queued by pushes. It polls over SSH as
188an admin account (runner commands are admin-only: a runner executes
189arbitrary repo code), clones, runs the steps, streams the log back, and
190resolves the commit status. Run it as a dedicated unprivileged user:
191
192#+begin_src sh
193useradd --system --create-home --home-dir /var/lib/gitbay-runner ci-runner
194sudo -u ci-runner ssh-keygen -t ed25519 -N "" -f /var/lib/gitbay-runner/.ssh/id_ed25519
195gitbayd --config /etc/gitbay/config.toml admin user create ci --admin \
196 --key /var/lib/gitbay-runner/.ssh/id_ed25519.pub
197gitbay-runner -remote git@127.0.0.1 -workdir /var/lib/gitbay-runner/work
198#+end_src
199
200v1 runs steps directly on the host — no containers — so treat the
201runner machine as executing whatever your users push. Install the
202toolchains your builds need on it.
203
204* Pages
205
206=[pages] domain = "example.site"= serves public repos' =pages= branches
207on =<owner>.<domain>=. DNS needs a wildcard record =*.<domain>= to the
208server; ACME issues per-subdomain certificates on demand (only for
209owners that exist). The domain must not be the site host or a parent of
210it — pages content runs its own scripts and must stay off the forge's
211origin.
212
185* Security 213* Security
186 214
187The [[Threat-Model]] file is the reference for what the forge 215The [[Threat-Model]] file is the reference for what the forge
Roadmap.org +6 −3
@@ -82,10 +82,13 @@ work to it.
82 82
83Bigger bets, each valuable independently; order by appetite. 83Bigger bets, each valuable independently; order by appetite.
84 84
85- [[https://gitbay.org/krz/gitbay/issues/13][#13]] CI/CD via external runners (after #1; the forge never executes 85- [[https://gitbay.org/krz/gitbay/issues/13][#13]] CI/CD — done 2026-08-25 (.gitbay/ci.yml jobs, gitbay-runner over
86 repository content) 86 SSH on bay1, statuses feed require-checks; the forge never executes
87 repository content itself)
87- [[https://gitbay.org/krz/gitbay/issues/16][#16]] Git LFS 88- [[https://gitbay.org/krz/gitbay/issues/16][#16]] Git LFS
88- [[https://gitbay.org/krz/gitbay/issues/15][#15]] static page hosting (needs the separate-origin decision) 89- [[https://gitbay.org/krz/gitbay/issues/15][#15]] static pages — done 2026-08-25 (public repos' =pages= branches on
90 <owner>.<pages domain>, separate origin; gitbay.org deployment awaits
91 the domain)
89- [[https://gitbay.org/krz/gitbay/issues/11][#11]] iOS app (hutch-based) and [[https://gitbay.org/krz/gitbay/issues/12][#12]] Android 92- [[https://gitbay.org/krz/gitbay/issues/11][#11]] iOS app (hutch-based) and [[https://gitbay.org/krz/gitbay/issues/12][#12]] Android
90- [[https://gitbay.org/krz/gitbay/issues/21][#21]] teams within orgs — done 2026-08-25 (members-role scoping + per-repo team grants) 93- [[https://gitbay.org/krz/gitbay/issues/21][#21]] teams within orgs — done 2026-08-25 (members-role scoping + per-repo team grants)
91- [[https://gitbay.org/krz/gitbay/issues/25][#25]] wikis — done 2026-08-25 (push-edited .wiki companions; krz/gitbay has one) 94- [[https://gitbay.org/krz/gitbay/issues/25][#25]] wikis — done 2026-08-25 (push-edited .wiki companions; krz/gitbay has one)
Users.org +28
@@ -301,6 +301,34 @@ Threads render inline on the MR page. A force-push marks them stale
301anchors; =mr show= reports the unresolved count. Resolving is for the 301anchors; =mr show= reports the unresolved count. Resolving is for the
302thread author, the MR author, or anyone with write. 302thread author, the MR author, or anyone with write.
303 303
304* CI builds
305
306A =.gitbay/ci.yml= in the repo runs jobs on every branch push:
307
308#+begin_src yaml
309jobs:
310 test:
311 steps:
312 - go test ./...
313#+end_src
314
315Each job becomes a build (=build list=, =build log=, the builds tab on
316the web) and a =ci/<job>= commit status, which =repo settings
317require-checks= can gate merges on. Steps run with =sh -c= on the
318instance's runner, stopping at the first failure; a broken config
319surfaces as a failed =ci/config= status. Environment: =GITBAY_REPO=,
320=GITBAY_SHA=, =GITBAY_REF=, =GITBAY_JOB=, =CI=true=.
321
322* Pages
323
324On instances with =[pages] domain= set, a =pages= branch in any public
325repo is served as a static site: the repo named =pages= at
326=https://<you>.<domain>/=, every other repo at
327=https://<you>.<domain>/<repo>/=. Push HTML to publish; a CI job can
328build and push the branch for automatic deploys. Sites run on a
329separate origin — your scripts work, and the forge's cookies are out of
330reach.
331
304* Notifications 332* Notifications
305 333
306When the instance has SMTP configured, activity mails you: someone 334When the instance has SMTP configured, activity mails you: someone