runcard

does not own.

── WHY THIS MODULE EXISTS ──────────────────────────────────────────────────
`slack` is a client: it renders and posts a card, and its header says the
loop that keeps the card current belongs to each repo. That held while every
pipeline was ONE `dagger call` that could carry the loop inside it. It stopped
holding once pipelines became many jobs on many runners: no dagger call spans
them, so each repo would need the same ~200-line watcher. `pacha/app` wrote it
first (`pipelineCardLive`, 2026-09-16); this is that prototype, shared.

── THREE SHAPES, ONE CARD LOOK ─────────────────────────────────────────────
· `watch` multi-job workflows. A job with no `needs` polls the run's jobs
through the GitHub API and rewrites the card as rows change.
· `report` single-job workflows, as the job's last step. One post at the
end; the steps are the rows. No second runner is paid for.
· `thread` post detail under an existing card, found by its metadata. A
Dagger call that used to open its own card posts here instead.

── IT NEVER WAITS FOR A HUMAN ──────────────────────────────────────────────
When all that is left of a run is jobs parked on an environment approval,
`watch` renders them as "awaiting approval", closes the card as `waiting` and
EXITS. A second watcher job that `needs` the gated job and passes
`resumeAfter` picks the same card up once the gate opens and carries it to
its verdict, so a released run does not stay "awaiting approval" forever. Polling an approval held a runner for up to thirty minutes and was
retired on 2026-08-22 (ADR-0003 §2.3); approvals are the `deploy-gate` service's
job, and it threads its request under this card by the commit sha in the
card's metadata.

── THE CARD'S METADATA IS API ──────────────────────────────────────────────
`event_type` = the caller's `eventType`; `event_payload` carries `repo`, `sha`,
`run_id`, `run_attempt` and `status`. `thread` finds cards by the first three
of (event_type, run_id, run_attempt); `deploy-gate` finds them by `sha`;
`slack.readTrend` reads `repo` and the numbers. See `slack`'s `EventPayload`.

── TEST REPORTS CROSS JOBS AS ARTIFACTS ────────────────────────────────────
A `wildbit.test-report/v1` built in job A has to reach the watcher in job B,
on another runner, with no shared disk. Each job uploads its report with
`actions/upload-artifact` under a name starting `test-report-` (with
`overwrite: true`), and `watch` reads them back through `github.runArtifactFiles`
when it closes, merges them with `testing.merge`, maps features when it has the
specs, and forwards ONE report to `slack.render`/`slack.breakdown`.

Chosen over a `runcard.attachReport` that posts each report into the card's
thread: that would put multi-kilobyte JSON through Slack metadata (capped, and
a report of 600 suites does not fit), race the watcher's first post, depend on
a Slack token every job would then need (Dependabot runs have none), and leave
nothing durable. An artifact needs only the `actions: read` the watcher already
holds, costs one step per job, is retained with the run, and is the file a
later Grafana import reads. `report` takes the reports directly: a single job
already has them in hand.

── NOTIFICATION IS BEST-EFFORT ─────────────────────────────────────────────
No function here fails a build because Slack or the API was slow. They throw
only on MISCONFIGURATION (bad JSON, a `selfJob` that matches nothing, a token
that cannot read the run) — the failures that would otherwise hold a runner
until the deadline and render a card that lies.

Installation

dagger install github.com/wildbitca/daggerverse/runcard@v0.3.0content_copy Copied!

Types