Guides on gh-velocity

Interpreting Results

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

Interpreting Results#

gh-velocity produces output in four formats: pretty (default), JSON, markdown, and HTML. Each format contains the same data, structured for different consumers. This guide explains how to read the output, what healthy metrics look like, and what common patterns mean.

Reading your output#

Output formats at a glance#

Format	Best for	Flag
Pretty	Terminal reading, quick checks	`--results pretty` (default)
JSON	Agents, scripts, `jq` pipelines, CI	`--results json`
Markdown	Pasting into issues, PRs, Discussions	`--results markdown`
HTML	Self-contained report files	`--results html`

All commands accept --results (or -r). If you omit it, you get pretty.

Setting Up Flow Velocity

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

Setting Up Flow Velocity#

The flow velocity command measures effort completed per iteration -- a number, not a ratio. It answers "how much work did we ship this period?" in effort units. A related metric, completion rate (done / committed), measures predictability. Both appear in the output. For the metric definition and formula, see the Velocity reference.

Iteration and effort are independent of scope and lifecycle -- they control how velocity is computed, not which items are measured. See Definitions for details.

Cycle Time Setup

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

Cycle Time Setup#

Cycle time measures how long active work took on an issue, excluding backlog time (unlike lead time, which measures full elapsed duration from creation to close). The measurement depends on your configured strategy. For the metric definition and formula, see the Cycle Time reference.

Choosing a strategy#

There are two cycle time strategies. Choose based on your workflow.

Your workflow	Recommended strategy	Why
Issues with lifecycle labels	`issue`	Measures real work time (label applied to closed); immutable timestamps
PRs close issues (most OSS repos)	`pr`	Measures PR review time (created to merged)
Issues only, no labels or PRs	`issue`	Lead time works immediately; add an `in-progress` label for cycle time

The PR strategy requires zero setup; the issue strategy gives richer data but requires label discipline.

Posting Reports

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

Posting Reports#

gh-velocity posts metrics directly to GitHub via the --post flag. Bulk commands (report, quality release) post to GitHub Discussions; single-item commands (flow lead-time 42) post as issue/PR comments.

The --post flag#

Every command supports --post:

gh velocity report --since 30d --post
gh velocity quality release v1.2.0 --post
gh velocity flow lead-time 42 --post

By default, --post runs in dry-run mode -- it shows what would be posted without writing to GitHub. To post for real, set GH_VELOCITY_POST_LIVE:

Agent Integration

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

Agent Integration#

Every gh-velocity command supports --results json for structured output, making it composable with LLM agents, CI scripts, and data pipelines.

JSON output structure#

Every command produces up to four layers of data:

Stats — aggregate numbers (top-level keys like lead_time, cycle_time)
Detail — per-item breakdowns (the issues array)
Insights — observations with severity (the insights array)
Provenance — how the output was produced (the provenance object)

The report command emits stats only. Standalone commands emit all four layers. Details:

Ad Hoc Queries

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

Ad Hoc Queries#

Practical patterns for common gh-velocity tasks.

Compare two releases#

gh velocity quality release v2.0.0 --results json > v2.json
gh velocity quality release v1.9.0 --results json > v1.json

echo "v1.9.0 median lead time: $(jq -r '.aggregates.lead_time.median_seconds / 86400 | round | "\(.)d"' v1.json)"
echo "v2.0.0 median lead time: $(jq -r '.aggregates.lead_time.median_seconds / 86400 | round | "\(.)d"' v2.json)"

Compare bug ratios:

echo "v1.9.0 bug ratio: $(jq -r '.composition.bug_ratio * 100 | round | "\(.)%"' v1.json)"
echo "v2.0.0 bug ratio: $(jq -r '.composition.bug_ratio * 100 | round | "\(.)%"' v2.json)"

Find your slowest issues#

gh velocity quality release v1.2.0 --results json | \
 jq -r '.issues | sort_by(-.lead_time_seconds) | .[0:5] | .[] |
 "#\(.number) \(.title[0:40]) -- \(.lead_time_seconds / 86400 | round)d"'

Check label coverage before a release#

gh velocity quality release v1.2.0 --results json | \
 jq '"Bug: \(.composition.bug_count), Feature: \(.composition.feature_count), Unlabeled: \(.composition.other_count)"'

If other_count is high, label your issues before publishing the release. Run gh velocity config preflight to discover available labels and generate matching category matchers.

Troubleshooting

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

Troubleshooting#

Solutions for common errors, N/A results, and unexpected output.

Error messages#

"not a git repository. Use --repo owner/name"#

Not inside a git checkout. Either cd into a local clone or use -R:

gh velocity quality release v1.2.0 -R owner/repo

"no GitHub release for v1.0.0, using current time"#

The tag exists but has no corresponding GitHub Release. The tool falls back to the current time for the release date, making release lag inaccurate. Fix by creating GitHub Releases for your tags. If you only push tags, the tool resolves dates from the tag's commit -- less precise but functional.