Concepts on gh-velocity

Definitions

Mon, 01 Jan 0001 00:00:00 +0000

Definitions#

gh-velocity is a command-line tool that measures development velocity and quality from GitHub data. It works at a terminal, in GitHub Actions, or in any automation platform -- it is not specific to CI.

Measurement axes#

Four independent axes control what gh-velocity measures and how. Scope and lifecycle filter which items to measure. Iteration and effort control how velocity is computed. They combine freely -- changing one does not affect the others.

GitHub's Capabilities & Limits

Mon, 01 Jan 0001 00:00:00 +0000

What GitHub Can and Cannot Tell You#

gh-velocity computes metrics directly from the GitHub API. That means zero setup, but also means the tool is constrained to what the API exposes. This page covers what works, what has rough edges, and what is fundamentally impossible.

What works well#

Issue lifecycle. Creation and closure dates are precise and always available. Lead time (created to closed) is the most reliable metric.

PR merge timestamps. The search API returns exact merge dates. The pr-link strategy uses these to find PRs merged within a release window, giving you accurate release composition.

Understanding Statistics

Mon, 01 Jan 0001 00:00:00 +0000

Understanding the Statistics#

gh-velocity reports several statistical measures for lead time, cycle time, and release lag. This page explains what each means and why it matters, without assuming a statistics background.

Why median over mean#

Lead times are almost always skewed: most issues close in days or weeks, but a few ancient issues closed during a release pull the average up. The median (the middle value when sorted) resists this distortion.

Linking Strategies

Mon, 01 Jan 0001 00:00:00 +0000

Linking Strategies#

The quality release command determines which issues belong to a release. Different teams use different workflows, and no single method works everywhere, so gh-velocity uses three strategies and merges the results.

Connecting PRs to issues#

GitHub tracks PR-to-issue connections through timeline events. A PR becomes linked to an issue when you:

Write Fixes #42, Closes #42, or Resolves #42 in the PR description
Use GitHub's sidebar "Development" section to link a PR to an issue
Mention #42 anywhere in the PR (creates a cross-reference event)
Use any casing variation: fix #42, close #42, resolve #42

The PR does not need to be merged, closed, or even out of draft. A draft PR that mentions an issue is enough.

Labels as Lifecycle Signal

Mon, 01 Jan 0001 00:00:00 +0000

Labels Are the Lifecycle Signal#

Labels are the sole source of truth for lifecycle and cycle-time signals in gh-velocity. Project boards remain useful for velocity reads (iteration tracking, effort fields) but play no role in lifecycle or cycle-time measurement.

Why labels won#

Label event timestamps (LABELED_EVENT.createdAt) are immutable. Once a label is applied, the timestamp never changes -- not when the label is removed, not when it is re-added, not when anything else changes. The first application is permanently recorded.