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