.gitbay/wiki/API.org

  1#+title: gitbay API and webhooks
  2
  3* The JSON API
  4
  5One endpoint fronts the entire command registry — everything the SSH
  6control plane can do, current and future, with identical semantics.
  7Disabled by default; the instance must set:
  8
  9#+begin_src toml
 10[api]
 11enabled = true
 12#+end_src
 13
 14** Tokens
 15
 16Tokens are minted wherever the registry is reached: over SSH, on the
 17API, anywhere. =token create= makes a =read= token unless =--scope full=
 18is given; a read token runs only commands marked read-only. A full-scope
 19token can mint another, but a token or SSH key with a =--ttl= cannot run any
 20command that creates a credential — =token create=, =keys add=,
 21=repo deploy-key add=, =repo runner add=, =web login=, =admin invite=,
 22=admin user create=, =email verify=, =admin email verify= — since what
 23it made would outlive it. Give a token the narrowest scope and shortest
 24TTL that does its job, and revoke it when the job is over.
 25
 26#+begin_src sh
 27gitbay auth token create --name ci [--scope read|full] [--ttl 30d]
 28gitbay auth token list
 29gitbay auth token revoke ci [--created]
 30#+end_src
 31
 32Tokens and keys record the token they were created through. =token
 33revoke= prints what the token created, at any depth; with =--created=
 34it revokes those too, and their SSH connections close. Without it they
 35stay and the link is dropped.
 36
 37The token (prefix =gb_=, shown exactly once) is presented as
 38=Authorization: Bearer gb_...=. Only a hash is stored server-side.
 39Scope =read= permits list/show/log/diff-style commands and refuses
 40anything that modifies state. =--ttl= takes Go durations or a day
 41suffix (=30d=); expired, revoked, and unknown tokens all answer the
 42same 401.
 43
 44** POST /api/v1/cmd
 45
 46Request body:
 47#+begin_src json
 48{"argv": ["issue", "create", "you/project", "--title", "from CI"],
 49 "stdin": "optional body for --file - style input"}
 50#+end_src
 51
 52=argv= is real argv — no shell, no quoting rules. The response is the
 53command's own JSON envelope with =exit_code= added, plus =stderr= when
 54the command wrote diagnostics:
 55
 56#+begin_src json
 57{"protocol_version": 1, "exit_code": 0, "data": {"number": 7}}
 58#+end_src
 59
 60HTTP status maps the exit code: 0→200, 2→400, 3→404, 4→403, else 500.
 61Commands that emit raw text rather than an envelope (=help=, =mr diff=)
 62come wrapped as ={"output": "..."}=. Git transport commands and the
 63token commands are refused by name.
 64
 65#+begin_src sh
 66curl -s -H "Authorization: Bearer $TOKEN" \
 67     -d '{"argv":["whoami"]}' https://gitbay.org/api/v1/cmd
 68
 69printf '{"argv":["issue","create","you/project","--title","t","--file","-"],"stdin":"body\n"}' |
 70curl -s -H "Authorization: Bearer $TOKEN" -d @- https://gitbay.org/api/v1/cmd
 71#+end_src
 72
 73** GET /api/v1/read
 74
 75The conditional half: the same registry over GET, admitting only
 76commands the registry marks read-only, so a GET structurally cannot
 77mutate. Responses carry an =ETag=; =If-None-Match= answers 304.
 78
 79#+begin_src sh
 80curl -s -H "Authorization: Bearer $TOKEN" \
 81     "https://gitbay.org/api/v1/read?argv=repo&argv=show&argv=you/project"
 82#+end_src
 83
 84** The dashboard read
 85
 86=dashboard= returns the account aggregate — pinned repositories, open
 87merge requests, assigned issues, recent builds — in one call:
 88
 89#+begin_src sh
 90curl -s -H "Authorization: Bearer $TOKEN" \
 91     "https://gitbay.org/api/v1/read?argv=dashboard"
 92#+end_src
 93
 94For an instance admin the response also carries ={"server": {"commit":
 95"<sha>"}}=, the build the daemon is running, so the deployed commit is
 96readable without the journal. The key is absent for everyone else: the
 97exact build a host runs narrows down which known issues apply to it.
 98
 99** Cursor pagination
100
101=issue list=, =mr list=, =repo list=, and =feed= accept =--limit <n>=
102(1–200) and =--cursor <c>=. With either flag present the =data=
103envelope becomes ={"items": [...], "next": "..."}=; =next= is an
104opaque cursor for the following page, absent on the last one. Without
105the flags the response stays the complete bare array; a bare =feed=
106returns the newest 50 events.
107
108* Commit statuses (CI reporting)
109
110CI reports results through the same command surface (over SSH or the
111JSON API with a full-scope token; reporting requires write access):
112
113#+begin_src sh
114gitbay status set <owner/name> <sha> --context build --state pending
115gitbay status set <owner/name> <sha> --context build --state success --url https://ci.example/run/1
116gitbay status list <owner/name> <sha> --json    # {"combined": "...", "statuses": [...]}
117#+end_src
118
119One row per (commit, context): re-reporting updates in place. States:
120=pending=, =success=, =failure=, =error=; the combined state is the
121worst of them. Statuses appear on commit pages, MR pages, and
122=mr show=, each with =updated_at=; a =ci/<job>= status also carries
123=duration=, read from the build behind it, once that build has
124finished. With =repo settings require-checks <repo> on=, every status
125on the MR head must be green, and a head something was going to report
126on must carry some: a =.gitbay/ci.yml= with a job a push runs, or a
127repository that has recorded a status before, which is what reporting
128from outside through =status set= looks like. A repository where
129nothing has ever reported merges. Each
130report also emits a =status= event to webhooks.
131
132* Webhooks
133
134Per-repository outbound POSTs for repository events. Managed by repo
135admins:
136
137#+begin_src sh
138gitbay webhook add <url> --secret s3cret [--events push,issue.created]  # default *
139gitbay webhook list
140gitbay webhook deliveries [--limit 50]     # status, attempts, last error
141gitbay webhook redeliver <delivery-id>     # requeue, including dead letters
142gitbay webhook remove <id>
143#+end_src
144
145** Events
146
147Every event this forge records, and so every name =--events= may take.
148The server holds the same list as =control.EventKinds=, and a test
149fails if the code emits something not listed or lists something it never
150emits — so this is the whole set, not a sample. =webhook add= refuses a
151name that is not one of them, since a subscription to a typo would
152silently never fire.
153
154- repository: =push= (ref, old, new, forced, deleted), =repo.archived=,
155  =repo.unarchived=, =repo.imported= (from)
156- issues: =issue.created=, =issue.edited=, =issue.commented=,
157  =issue.closed=, =issue.open=, =issue.labeled= (labels),
158  =issue.assigned= (assignees), =issue.milestoned= (milestone)
159- merge requests: =mr.created=, =mr.edited=, =mr.commented=,
160  =mr.reviewed= (verdict), =mr.draft= (draft), =mr.retargeted= (from,
161  to), =mr.labeled= (labels), =mr.milestoned= (milestone), =mr.merged=
162  (number, sha), =mr.closed=
163- releases: =release.created= (tag), =release.deleted= (tag)
164- CI: =status=, =build.success=, =build.failure=, =build.cancelled=
165
166Every payload carries =number= where it names an issue or merge request.
167
168There is deliberately no =repo.deleted=. Both =events.repo_id= and
169=webhooks.repo_id= cascade from =repos=, so recording one would delete
170it — and every webhook that could have received it — in the same
171statement. A repository's deletion is visible in the audit log.
172
173** Delivery
174
175Each event POSTs one JSON body:
176
177#+begin_src json
178{"event": "push",
179 "repo": "you/project",
180 "actor": "alice",
181 "created_at": "2026-08-24T01:00:00.000Z",
182 "data": {"ref": "refs/heads/main", "old": "...", "new": "...",
183          "forced": false, "deleted": false}}
184#+end_src
185
186Headers: =X-Gitbay-Event=, =X-Gitbay-Delivery= (id), and — when the hook
187has a secret — =X-Gitbay-Signature-256: sha256=<hex hmac>= over the raw
188body. Verify before trusting:
189
190#+begin_src python
191import hmac, hashlib
192expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
193ok = hmac.compare_digest(expected, request.headers["X-Gitbay-Signature-256"])
194#+end_src
195
196A 2xx within 10 seconds is success. Anything else retries with
197exponential backoff (30s base, doubling) and dead-letters after five
198attempts; =webhook deliveries= shows the trail and =redeliver= revives a
199dead letter. Redirects are never followed, and targets resolving to
200loopback/private/link-local addresses are refused both at registration
201and again at connect time, unless the instance sets
202=[webhooks] allow_local=.