Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/gitlab.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,9 @@ Then in GitLab, Project (or group, or Admin → System hooks) → Settings → W
| Triggers | **Merge request events** · **Comments** |
| SSL verification | enabled |

Add one webhook in the console for each hook you set up in GitLab (a system hook, each group hook). Each has its own URL and secret, so one can be given a new secret, disabled or deleted without touching the others. The URL alone picks the host, and only that webhook's secret verifies it.
Add one webhook in the console for each hook you set up in GitLab (a system hook, each group hook).

**A system hook alone is not enough.** GitLab system hooks send merge request events but never comments, so `@bot` commands and learnings from replies need a group or project webhook with **Comments**. A system hook plus group hooks is fine: the console drops the duplicate merge request event. When a host receives deliveries but no comment events, the Code hosts page and Setup say so. Each has its own URL and secret, so one can be given a new secret, disabled or deleted without touching the others. The URL alone picks the host, and only that webhook's secret verifies it.

**Signing tokens (GitLab 19.0+, recommended).** After saving the hook, GitLab shows its signing token (`whsec_…`). Paste it into the webhook in the console. Signed deliveries are then checked by signature. If the host's **Unsigned webhooks** setting is **Reject**, the webhook only works once its signing token is saved.

Expand Down
66 changes: 66 additions & 0 deletions internal/admin/admin_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -682,3 +682,69 @@ func TestSetupChecklist(t *testing.T) {
t.Errorf("reloading /admin/setup must serve the app: %d", code)
}
}

func TestCommentEventsWarning(t *testing.T) {
e := setup(t, config.OIDC{AllowedEmails: []string{"alice@example.com"}})
e.idp.as(map[string]any{"sub": "u1", "email": "alice@example.com", "email_verified": true})
_ = e.login(t).Body.Close()
ctx := context.Background()
gl, err := e.adm.Hosts.Save(ctx, hosts.Host{Platform: hosts.GitLab, BaseURL: "https://gitlab.example.com", Enabled: true,
Settings: hosts.Settings{BotName: "review-bot"}, Secrets: hosts.Secrets{Token: "t"}}, "a@x")
if err != nil {
t.Fatal(err)
}
hostWarning := func() string {
t.Helper()
_, body := e.do(t, "GET", "/admin/api/hosts", "", nil)
var list struct {
Hosts []struct {
ID int64
CommentWarning string `json:"comment_warning"`
}
}
_ = json.Unmarshal(body, &list)
for _, h := range list.Hosts {
if h.ID == gl.ID {
return h.CommentWarning
}
}
t.Fatalf("host missing: %s", body)
return ""
}
if w := hostWarning(); w != "" {
t.Errorf("no deliveries yet: no warning, got %q", w)
}
// Only system hook deliveries (merge requests): the issue #25 setup.
_ = e.st.InsertWebhookEvents(ctx, []store.WebhookEvent{
{Platform: "gitlab", Host: "gitlab.example.com", Event: "System Hook", Kind: "merge_request", Auth: "signature", Outcome: store.HookQueued},
{Platform: "gitlab", Host: "gitlab.example.com", Event: "Note Hook", Kind: "note", Auth: "failed", Outcome: store.HookRejected}, // unverified: doesn't count
})
if w := hostWarning(); !strings.Contains(w, "system hooks don't send comments") || !strings.Contains(w, "@review-bot") {
t.Errorf("system hook only: %q", w)
}
code, body := e.do(t, "GET", "/admin/api/setup", "", nil)
if code != 200 || !bytes.Contains(body, []byte(`"id":"comments","title":"Receive comments"`)) || !bytes.Contains(body, []byte("system hooks")) {
t.Errorf("setup comments step: %s", body)
}
// A verified comment clears it.
_ = e.st.InsertWebhookEvents(ctx, []store.WebhookEvent{{Platform: "gitlab", Host: "gitlab.example.com", Event: "Note Hook", Kind: "note", Auth: "token", Outcome: store.HookIgnored}})
if w := hostWarning(); w != "" {
t.Errorf("after a comment event: %q", w)
}
if _, body := e.do(t, "GET", "/admin/api/setup", "", nil); !bytes.Contains(body, []byte("1 comment event received")) {
t.Errorf("setup after a comment: %s", body)
}
}

func TestCommentWarningText(t *testing.T) {
gh := hosts.Host{Platform: hosts.GitHub}
if w := commentWarning(gh, store.HostHookStats{Verified: 3}); !strings.Contains(w, "Issue comment") || !strings.Contains(w, "@bot") {
t.Errorf("github: %q", w)
}
if w := commentWarning(hosts.Host{Platform: hosts.Bitbucket}, store.HostHookStats{Verified: 1}); !strings.Contains(w, "Comment created") {
t.Errorf("bitbucket: %q", w)
}
if w := commentWarning(hosts.Host{Platform: hosts.GitLab}, store.HostHookStats{Verified: 2, SystemHook: 1}); !strings.Contains(w, "Turn on Comments") {
t.Errorf("gitlab with a group hook but no comments: %q", w)
}
}
55 changes: 52 additions & 3 deletions internal/admin/handlers.go
Original file line number Diff line number Diff line change
Expand Up @@ -592,6 +592,9 @@ type hostView struct {
// Webhooks have their own URL and secrets (added in the admin panel).
Webhooks []webhookView `json:"webhooks"`
Events []string `json:"events"`
// CommentWarning is set when verified deliveries arrive but no comment
// events do, so @bot commands and learnings would fail silently.
CommentWarning string `json:"comment_warning,omitempty"`
// Licensed is false for a host the license does not cover (a second
// host on a platform without the hosts feature): it is not used.
Licensed bool `json:"licensed"`
Expand All @@ -603,16 +606,61 @@ var hookEvents = map[string][]string{
hosts.Bitbucket: {"Pull request: Created", "Updated", "Merged", "Declined", "Comment created"},
}

func (a *Admin) viewHost(h hosts.Host) hostView {
func (a *Admin) viewHost(h hosts.Host, stats map[string]store.HostHookStats) hostView {
v := hostView{ID: h.ID, Platform: h.Platform, Host: h.Host, BaseURL: h.BaseURL, Name: h.Name, Enabled: h.Enabled,
Settings: h.Settings, Secrets: h.SecretStatus(), WebhookURL: a.cfg.BaseURL + "/webhooks/" + h.Platform, Webhooks: []webhookView{},
Events: hookEvents[h.Platform], Licensed: !h.Enabled || a.Hosts.Active(h)}
for _, e := range a.Hosts.Endpoints(h.ID) {
v.Webhooks = append(v.Webhooks, a.viewWebhook(h.Platform, e))
}
if h.Enabled {
v.CommentWarning = commentWarning(h, stats[h.Platform+":"+h.Host])
}
return v
}

// hookStats returns verified-delivery stats by "platform:host" (empty on
// error: the warnings are a hint, not a reason to fail the page).
func (a *Admin) hookStats(ctx context.Context) map[string]store.HostHookStats {
out := map[string]store.HostHookStats{}
list, err := a.store.HookStats(ctx)
if err != nil {
a.logger.Warn("webhook stats unavailable", "error", err)
return out
}
for _, s := range list {
out[s.Platform+":"+s.Host] = s
}
return out
}

// commentWarning explains why comment events are missing for a host that
// does receive webhooks: a GitLab system hook never sends them, and other
// hooks need the comment events switched on.
func commentWarning(h hosts.Host, s store.HostHookStats) string {
if s.Verified == 0 || s.Comments > 0 {
return ""
}
bot := "@" + h.BotName
if h.BotName == "" {
bot = "@bot"
}
effect := bot + " commands and learnings from replies won't work"
switch h.Platform {
case hosts.GitLab:
if s.SystemHook == s.Verified {
return "Only system hook deliveries so far. GitLab system hooks don't send comments, so " + effect +
". Add a group or project webhook with Comments (Manage webhooks gives it its own URL)."
}
return "No comment events received yet, so " + effect + ". Turn on Comments on the group or project webhook."
case hosts.GitHub:
return "No comment events received yet, so " + effect + ". Subscribe the webhook or GitHub App to Issue comment and Pull request review comment."
case hosts.Bitbucket:
return "No comment events received yet, so " + effect + ". Turn on the Comment created trigger on the webhook."
}
return ""
}

// webhookView is a webhook endpoint as the admin UI sees it: its URL and
// which secrets are set, never their values.
type webhookView struct {
Expand Down Expand Up @@ -736,8 +784,9 @@ func (a *Admin) apiListHosts(w http.ResponseWriter, r *http.Request, s *store.Se
return
}
out := []hostView{}
stats := a.hookStats(r.Context())
for _, h := range a.Hosts.All() {
out = append(out, a.viewHost(h))
out = append(out, a.viewHost(h, stats))
}
writeJSON(w, http.StatusOK, map[string]any{"mode": a.Hosts.Mode(), "hosts": out, "key_env": secrets.EnvKey})
}
Expand Down Expand Up @@ -793,7 +842,7 @@ func (a *Admin) saveHost(w http.ResponseWriter, r *http.Request, s *store.Sessio
if fresh, ok := a.Hosts.Get(saved.ID); ok {
saved = fresh
}
writeJSON(w, status, a.viewHost(saved))
writeJSON(w, status, a.viewHost(saved, a.hookStats(r.Context())))
}

func (a *Admin) apiCreateHost(w http.ResponseWriter, r *http.Request, s *store.Session) {
Expand Down
19 changes: 19 additions & 0 deletions internal/admin/setup.go
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,25 @@ func (a *Admin) setup(ctx context.Context) (setupStatus, error) {
}
steps = append(steps, delivery)

// 4b. Comments (optional: reviews work without them, @bot commands and
// learnings don't). Shown once deliveries arrive, so it can say why.
if delivery.Done {
comments := setupStep{ID: "comments", Title: "Receive comments", Optional: true, Link: "/hosts",
Help: "@bot commands and learnings from replies need comment events. A GitLab system hook doesn't send them: add a group or project webhook with Comments."}
stats := a.hookStats(ctx)
total := 0
for _, h := range active {
total += stats[h.Platform+":"+h.Host].Comments
if w := commentWarning(h, stats[h.Platform+":"+h.Host]); w != "" && comments.Detail == "" {
comments.Detail = h.Name + ": " + w
}
}
if total > 0 && comments.Detail == "" {
comments.Done, comments.Detail = true, plural(total, "comment event")+" received"
}
steps = append(steps, comments)
}

// 5. A model.
model := setupStep{ID: "model", Title: "Set up a model",
Help: "Reviews need at least one model profile: add it under models: in the config file (provider, model and the env var holding the API key), set model: to it, and restart."}
Expand Down

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion internal/admin/ui/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<meta name="csp-nonce" content="__CSP_NONCE__">
<!-- Applies the saved theme before the first paint (no inline scripts: strict CSP). -->
<script src="/admin/assets/theme.js"></script>
<script type="module" crossorigin src="/admin/assets/index-bZ2wRe7T.js"></script>
<script type="module" crossorigin src="/admin/assets/index-DMQms6p-.js"></script>
<link rel="stylesheet" crossorigin href="/admin/assets/index-D7T42H01.css">
</head>
<body>
Expand Down
40 changes: 40 additions & 0 deletions internal/store/store.go
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,24 @@ type WebhookEvent struct {
DurationMS int `json:"duration_ms"`
}

// HostHookStats summarises a host's verified webhook deliveries in the
// history (see PruneWebhookEvents for how long it is kept).
type HostHookStats struct {
Platform string `json:"platform"`
Host string `json:"host"`
// Verified counts deliveries whose signature or token matched.
Verified int `json:"verified"`
// Comments counts verified comment events (GitLab notes, GitHub issue
// and review comments, Bitbucket comment_created).
Comments int `json:"comments"`
// SystemHook counts verified deliveries from a GitLab system hook,
// which never sends comments.
SystemHook int `json:"system_hook"`
}

// CommentKinds are the webhook kinds that carry a comment.
var CommentKinds = []string{"note", "issue_comment", "pull_request_review_comment", "pullrequest:comment_created"}

// Webhook outcomes.
const (
HookQueued = "queued"
Expand Down Expand Up @@ -292,6 +310,8 @@ type Store interface {
ListWebhookEvents(ctx context.Context, f WebhookFilter) ([]WebhookEvent, error)
// CountWebhookEvents counts events by outcome since a time.
CountWebhookEvents(ctx context.Context, since time.Time) (map[string]int, error)
// HookStats summarises verified deliveries per host.
HookStats(ctx context.Context) ([]HostHookStats, error)
// PruneWebhookEvents deletes events older than before and keeps at most
// keep rows.
PruneWebhookEvents(ctx context.Context, before time.Time, keep int) (int64, error)
Expand Down Expand Up @@ -1162,6 +1182,26 @@ func (p *Postgres) CountWebhookEvents(ctx context.Context, since time.Time) (map
return out, rows.Err()
}

func (p *Postgres) HookStats(ctx context.Context) ([]HostHookStats, error) {
rows, err := p.pool.Query(ctx, `SELECT platform, host, count(*),
count(*) FILTER (WHERE kind = ANY($1) OR event = 'Note Hook'),
count(*) FILTER (WHERE event = 'System Hook')
FROM webhook_events WHERE auth IN ('signature', 'token') AND host <> '' GROUP BY platform, host ORDER BY platform, host`, CommentKinds)
if err != nil {
return nil, err
}
defer rows.Close()
out := []HostHookStats{}
for rows.Next() {
var s HostHookStats
if err := rows.Scan(&s.Platform, &s.Host, &s.Verified, &s.Comments, &s.SystemHook); err != nil {
return nil, err
}
out = append(out, s)
}
return out, rows.Err()
}

func (p *Postgres) PruneWebhookEvents(ctx context.Context, before time.Time, keep int) (int64, error) {
tag, err := p.pool.Exec(ctx, `DELETE FROM webhook_events WHERE received_at < $1
OR id <= (SELECT id FROM webhook_events ORDER BY id DESC OFFSET $2 LIMIT 1)`, before, keep)
Expand Down
26 changes: 26 additions & 0 deletions internal/store/store_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -491,3 +491,29 @@ func TestWebhookEndpointsStore(t *testing.T) {
t.Errorf("a malformed ID is just not found: %v", err)
}
}

func TestHookStats(t *testing.T) {
p := openTest(t)
ctx := context.Background()
host := fmt.Sprintf("stats-%d.example.com", time.Now().UnixNano())
if err := p.InsertWebhookEvents(ctx, []WebhookEvent{
{Platform: "gitlab", Host: host, Event: "System Hook", Kind: "merge_request", Auth: "signature"},
{Platform: "gitlab", Host: host, Event: "Note Hook", Kind: "note", Auth: "token"},
{Platform: "gitlab", Host: host, Event: "Note Hook", Kind: "note", Auth: "failed"},
}); err != nil {
t.Fatal(err)
}
list, err := p.HookStats(ctx)
if err != nil {
t.Fatal(err)
}
for _, s := range list {
if s.Host == host {
if s.Verified != 2 || s.Comments != 1 || s.SystemHook != 1 {
t.Errorf("stats = %+v", s)
}
return
}
}
t.Errorf("host missing from %+v", list)
}
33 changes: 33 additions & 0 deletions internal/store/storetest/memory.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"context"
"encoding/json"
"fmt"
"slices"
"sort"
"strings"
"sync"
Expand Down Expand Up @@ -371,6 +372,38 @@ func (m *Memory) InsertWebhookEvents(_ context.Context, events []store.WebhookEv
return nil
}

func (m *Memory) HookStats(context.Context) ([]store.HostHookStats, error) {
m.mu.Lock()
defer m.mu.Unlock()
by := map[string]*store.HostHookStats{}
var keys []string
for _, e := range m.hooks {
if (e.Auth != "signature" && e.Auth != "token") || e.Host == "" {
continue
}
k := e.Platform + ":" + e.Host
s := by[k]
if s == nil {
s = &store.HostHookStats{Platform: e.Platform, Host: e.Host}
by[k] = s
keys = append(keys, k)
}
s.Verified++
if slices.Contains(store.CommentKinds, e.Kind) || e.Event == "Note Hook" {
s.Comments++
}
if e.Event == "System Hook" {
s.SystemHook++
}
}
sort.Strings(keys)
out := []store.HostHookStats{}
for _, k := range keys {
out = append(out, *by[k])
}
return out, nil
}

func (m *Memory) ListWebhookEvents(_ context.Context, f store.WebhookFilter) ([]store.WebhookEvent, error) {
m.mu.Lock()
defer m.mu.Unlock()
Expand Down
Loading
Loading