klinux / klinux/gocdnext

Badge: filter by event (?event=) for Woodpecker-style multi-badge READMEs

Open
#294 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

good first issue
Dominant language
Go
Stars
7
Forks
3
Avg merge
2h 12m
Merged PRs (30d)
30

Description

Problem

Status badges (#292) currently expose one badge per project/pipeline, filterable only by ?branch=. Woodpecker's badge model is one endpoint + filters?branch= and ?event= — so a README can show several badges that each reflect a different slice of activity (e.g. one for push, one for pull_request). We already have the branch half; this adds the event half for badge parity.

Proposal

Add an optional ?event= query parameter to the badge endpoint that filters the "latest run" lookup by the run's triggering event (runs.cause). Accepted values mirror the material event vocabulary: push, pull_request, tag, manual, cron, upstream. Unknown/empty → current behaviour (no event filter).

![build](https://<host>/api/v1/badge/example-app.svg?token=T&branch=main&event=push)
![pr](https://<host>/api/v1/badge/example-app.svg?token=T&event=pull_request)

Scope

  • GetBadgeLatestRun / GetBadgeLatestRunByBranch: add an optional cause = @event OR @event = '' predicate (kept sargable; verify the existing runs_badge_latest* indexes still bound the lookup, add a covering index if EXPLAIN shows a scan).
  • Handler: parse + validate event against the fixed allow-list (reject anything else → treated as no filter, never reflected into SQL/SVG).
  • Docs: badge reference page — document event alongside branch.

Guardrails (security / performance / corner cases)

  • No oracle: same as #292 — a filter that matches nothing returns the same unknown badge as a bad token; never a 404 that distinguishes existence.
  • Allow-list only: event is validated against the closed vocabulary before it touches SQL; nothing user-controlled is reflected into the SVG (label stays fixed, message stays the status enum).
  • Perf: the lookup must stay index-bounded (README/wiki traffic is anonymous + cacheable, but hot). EXPLAIN ANALYZE in the PR.
  • Corner cases: empty/unknown event = no filter; project with no run of that event = unknown; combine cleanly with branch.

Non-goal

Deployment-status badges are a different dimension (deploy state lives in deployment_revisions/environments, not runs.cause) — tracked separately.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at GetBadgeLatestRun and GetBadgeLatestRunByBranch, then trace the badge handler's query parsing and the badge reference page. Verify the event allow-list, unknown and empty behavior, branch combination, and no-match badge behavior. Run EXPLAIN ANALYZE to confirm the existing runs_badge_latest* indexes keep the lookup bounded, and document event beside branch.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, postgres
Domain
api, backend, databases, documentation, performance
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.