ADR-001: GitHub Projects “Released” Column as Deployment Signal

Status: Accepted

Context

To calculate PR cycle time — the duration from a developer’s first commit to the code being live in production — we need a reliable signal for when work is deployed.

Candidates considered:

Signal	Pros	Cons
GitHub Releases (release: published)	Simple webhook, clean timestamp	Project does not create Releases
workflow_run completion on the frontend image workflow	Automatic, SHA-linked	Only fires when frontend files change — backend-only PRs are invisible
GitHub Projects “Released” column	Works for all PRs regardless of what changed; project board is the team’s source of truth for “done”	Requires projects_v2_item webhook + GraphQL API; needs admin setup per project

Decision

Use the GitHub Projects projects_v2_item.edited webhook event as the deployment signal.

When an issue’s status field changes to the configured “released” column name, the dashboard stamps deployedAt on every PR linked to that issue. The column name defaults to "Released" and is configurable per-installation via the admin settings UI, so teams that call their column “Prod”, “Shipped”, or anything else don’t need to change code.

Consequences

• Works universally across frontend, backend, and infrastructure PRs.
• The dashboard is portable — any team with a GitHub Projects board can use it by setting their column name in the admin UI.
• Historical data (PRs merged before the webhook is wired up) will have deployedAt = null. The cycle time panel falls back to mergedAt for those records.
• Requires a projects_v2_item webhook event to be added to the GitHub webhook pointing at this dashboard. Needs admin access on the source repo.
• Requires a GH_TOKEN with read:project scope to resolve issue→PR links via the GraphQL API.

Related issues

• #76 — schema: deployedAt on pull_requests
• #77 — ingest projects_v2_item.edited webhook
• #78 — update cycle time calculation
• #79 — admin settings: released_column_name