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.

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.

Lead Time

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

Lead Time#

Lead time is the total elapsed time from issue creation to closure. It includes time in backlog, waiting for prioritization, blocked by dependencies, in active development, in review, and waiting for release.

Definition#

lead_time = issue.closed_at - issue.created_at

Start signal: issue-created -- the timestamp when the GitHub issue was opened.

End signal: issue-closed -- the timestamp when the issue was closed (by any means: a merged PR, manual close, or bot).

Quick Start

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

Quick Start#

Install gh-velocity and run your first metrics in under 5 minutes.

Prerequisites#

The GitHub CLI must be installed and authenticated:

# Install (macOS shown -- see gh docs for Linux/Windows)
brew install gh

# Authenticate
gh auth login

Private repos require at least repo scope. Public repos work without special scopes.

Install#

gh extension install dvhthomas/gh-velocity

Verify it works:

gh velocity version

Generate a config file#

All metric commands require a .gh-velocity.yml file. The preflight command analyzes your repo and generates one:

Cycle Time

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

Cycle Time#

Cycle time measures how long active work took on an issue. Unlike lead time, which includes all waiting time from creation, cycle time starts when work begins.

Two strategies detect when work starts.

What it tells you#

Cycle time reveals how long active work takes, stripped of backlog wait time. A low, consistent cycle time means the team delivers quickly once work begins. High variability suggests inconsistent scope or frequent context-switching.

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.

How It Works

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

How It Works#

gh-velocity reads artifacts your team already produces -- issues, pull requests, labels, releases -- and turns them into metrics. No data warehouse, no tracking integration, no per-seat subscription. Everything comes from the GitHub API.

Commands are organized by the question they answer:

Command group	Question it answers	Examples
`flow`	How fast is work flowing?	`flow lead-time`, `flow cycle-time`, `flow throughput`, `flow velocity`
`quality`	Is this code good?	`quality release`
`status`	What's happening right now?	`status wip`, `status my-week`, `status reviews`
`report`	Give me the full picture	Composite dashboard of flow + quality
`config`	How do I set this up?	`config preflight`, `config validate`, `config show`

The lifecycle of an issue#

Every issue follows a lifecycle -- stages from creation to completion. Each transition produces a timestamp that maps to a metric:

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.

Configuration

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

Configuration#

All metric commands require a .gh-velocity.yml file. Run gh velocity config preflight --write to generate one. This page covers first-time setup; see Configuration Reference for the full schema.

Generate a config with preflight#

Let preflight inspect your repo and generate a tailored config:

cd your-repo
gh velocity config preflight --write

Preflight examines labels, project boards, and recent activity, then generates a .gh-velocity.yml with matchers (patterns like label:bug that classify issues), lifecycle labels, and project board settings.

Configuration

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

Configuration Reference#

Complete reference for .gh-velocity.yml fields, types, defaults, and validation rules.

All metric commands require a .gh-velocity.yml file. Run gh velocity config preflight --write to generate one, or create one manually in your repository root. Use --config to point to an alternate path. Every field is optional -- the tool uses sensible defaults for anything omitted.

To generate a config tailored to your repository:

gh velocity config preflight # preview to stdout (from inside your repo)
gh velocity config preflight --write # save to .gh-velocity.yml
gh velocity config preflight -R cli/cli # analyze a remote repo

To validate an existing config:

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.

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.

Velocity

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

Velocity#

Velocity measures effort completed per iteration (sprint). It tracks how much work finishes each cycle to reveal trends and consistency.

Definition#

velocity = sum(effort) for items completed in the iteration
completion_rate = velocity / committed_effort * 100

Velocity is the total effort of items that are "done" within an iteration.
Committed effort is the total effort of all items assigned to the iteration (done or not).
Completion rate is the percentage of committed effort that was actually completed. If committed effort is 0, completion rate is omitted.

An item is "done" when:

API Consumption

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

API Consumption#

How gh-velocity uses the GitHub API: rate limits, per-command costs, caching, and optimization.

API types used#

gh-velocity uses two GitHub API interfaces:

API	Rate limit	Used for
REST Search API	30 requests/minute, 1000 results/query	Finding issues, PRs by date range, scope, lifecycle
GraphQL API	5,000 points/hour	Project board data, timeline events, closing references, iteration fields

The Search API is the primary bottleneck. Each paginated search query (up to 10 pages of 100 results) counts as one request per page against the 30/minute limit.

CI Setup

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

CI / GitHub Actions Setup#

Run gh-velocity in CI to post automated reports on releases, PRs, and schedules.

How authentication works#

gh-velocity uses the GH_TOKEN environment variable for all GitHub API calls -- the same variable that powers the gh CLI. Locally, gh auth login handles this. In CI, set GH_TOKEN in your workflow. See Token permissions for what each token can access.

Token setup#

The default GITHUB_TOKEN works for most commands. However, GITHUB_TOKEN cannot access Projects v2 boards -- a GitHub platform limitation.

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.

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:

Throughput

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

Throughput#

Throughput counts issues closed and PRs merged within a time window -- the simplest measure of delivery rate.

Definition#

throughput_issues = count(issues closed in window)
throughput_prs = count(PRs merged in window)

Unweighted: every closed issue and every merged PR counts as 1, regardless of size, complexity, or effort.

Throughput vs. velocity#

Throughput and velocity both measure output, but they differ in two ways:

Dimension	Throughput	Velocity
Weighting	Every item = 1	Items weighted by effort strategy (count, attribute, or numeric)
Time boundary	Arbitrary date range (`--since` / `--until`)	Iteration-aligned (sprint boundaries)

Throughput is useful without sprints or effort estimates. Velocity is useful for tracking effort-weighted output across consistent iteration boundaries.

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:

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.

Quality

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

Quality Metrics#

Quality metrics analyze the composition and health of a release. They answer: "What did this release contain, and how healthy was the release process?"

What this tells you#

These metrics reveal whether the team is shipping improvements or fighting fires. A rising bug ratio signals growing technical debt. Frequent hotfixes suggest inadequate testing or overly aggressive release schedules. High release lag means finished work sits unreleased, increasing the risk of stale branches and merge conflicts.

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.

Staleness

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

Staleness#

Staleness measures how recently a work item had activity. It applies to open items in the WIP report.

Signals#

Signal	Threshold	Meaning
ACTIVE	Updated < 3 days ago	Normal activity, no concern
AGING	Updated 3-7 days ago	May need attention
STALE	Updated > 7 days ago	Likely blocked or abandoned

Calculation#

staleness = now - item.updated_at

updated_at is GitHub's last activity timestamp (comments, commits, label changes, status changes)
Thresholds are currently fixed (not configurable)
Staleness is computed at query time, not cached

WIP staleness ratio#

stale_ratio = stale_items / total_wip_items

A high stale ratio (>30%) suggests systemic flow problems -- items are being started but not finished.

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.

Shelly

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

Meet Shelly#

Every good project needs a mascot. Ours is Shelly — a chunky pixel tortoise with a patterned shell, a confident gaze, and an ironic name for a tool called velocity.

Why a tortoise?#

Because slow and steady wins the race.

Velocity isn't about going fast. It's about going consistently. The teams that ship the most over time aren't the ones sprinting and crashing — they're the ones with a sustainable pace, predictable delivery, and short feedback loops.

config

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

gh-velocity config#

Inspect, validate, and generate configuration

Synopsis#

Configuration commands for .gh-velocity.yml.

Getting started:

gh velocity config preflight -R owner/repo # analyze repo, suggest config
gh velocity config create # generate starter config
gh velocity config validate # check for errors

Options#

 -h, --help help for config

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

config create

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

gh-velocity config create#

Create a default .gh-velocity.yml in the current directory

Synopsis#

Generate a starter .gh-velocity.yml with sensible defaults.

For a smarter config tailored to your repo, use 'config preflight' first: gh velocity config preflight -R owner/repo

gh-velocity config create [flags]

Examples#

 gh velocity config create

Options#

 -h, --help help for create

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

config discover

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

gh-velocity config discover#

Discover Projects v2 boards and fields linked to a repo

Synopsis#

Queries the GitHub API to find Projects v2 boards linked to the target repository, then lists their fields and status options.

Use this to find the project URL and status field name needed for .gh-velocity.yml configuration.

gh-velocity config discover [flags]

Examples#

 # Discover projects for a remote repo
 gh velocity config discover -R cli/cli

 # JSON output for scripting
 gh velocity config discover -R owner/repo -r json

Options#

 -h, --help help for discover

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

config preflight

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

gh-velocity config preflight#

Analyze a repo and recommend a .gh-velocity.yml configuration

Synopsis#

Preflight queries your repository to build a smart starting configuration.

It inspects:

Labels (to detect bug, feature, and status labels)
A specific Projects v2 board (to find status fields and lifecycle mapping)
Recent merged PRs (to gauge activity and linking patterns)
Recent closed issues (to check label usage)

Use --project-url to include a project board in the analysis. Copy the URL from your browser when viewing the project board.

config show

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

gh-velocity config show#

Display resolved configuration with defaults applied

Synopsis#

Display the fully resolved configuration with all defaults applied.

This shows the effective config that commands will use — including default values for any keys you have not set in your .gh-velocity.yml. Use this to verify that your config is interpreted the way you expect.

The JSON output (-r json) is useful for debugging or piping into other tools.

gh-velocity config show [flags]

Examples#

 gh velocity config show
 gh velocity config show -r json

Options#

 -h, --help help for show

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

config validate

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

gh-velocity config validate#

Validate configuration and report errors

Synopsis#

Validate a .gh-velocity.yml file and report any errors.

Checks include: YAML syntax, known top-level keys, matcher syntax (label:, type:, title:, field: patterns), project URL format, numeric ranges (e.g., hotfix_window_hours), and category name requirements.

Use --velocity to additionally verify that velocity-specific config (effort strategy, iteration strategy, project field names) is correctly configured against your actual GitHub project board.

This command does not make API calls (except with --velocity, which queries the project board to validate field names).

flow

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

gh-velocity flow#

Flow metrics (lead-time, cycle-time, velocity)

Synopsis#

How fast is work flowing through your team?

Flow metrics measure the speed and volume of work:

lead-time Total time from issue creation to closure cycle-time Active work time (start signal to close/merge) throughput Items completed per time window velocity Effort delivered per iteration

Options#

 -h, --help help for flow

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

flow cycle-time

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

gh-velocity flow cycle-time#

Cycle time for an issue, PR, or bulk query

Synopsis#

Cycle time measures how long an issue or PR was actively worked on.

The measurement strategy is set in .gh-velocity.yml:

cycle_time: strategy: issue # work started → issue closed (default) strategy: pr # PR created → PR merged

The issue strategy detects "work started" from lifecycle labels (e.g., label:in-progress). Configure lifecycle.in-progress.match for cycle time metrics.

Single mode: gh velocity cycle-time 42 gh velocity cycle-time --pr 99 Bulk mode: gh velocity cycle-time --since 30d [--until 2026-03-01]

flow lead-time

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

gh-velocity flow lead-time#

Lead time for an issue or bulk query (created → closed)

Synopsis#

Lead time measures the elapsed time from issue creation to close.

Single mode: gh velocity lead-time 42 Bulk mode: gh velocity lead-time --since 30d [--until 2026-03-01]

In bulk mode, returns per-item rows plus aggregate statistics for all issues closed in the given date window.

gh-velocity flow lead-time [<issue>] [flags]

Examples#

 # Single issue
 gh velocity flow lead-time 42
 gh velocity flow lead-time 42 -R cli/cli

 # All issues closed in the last 30 days
 gh velocity flow lead-time --since 30d

 # Custom window, JSON output
 gh velocity flow lead-time --since 2026-01-01 --until 2026-02-01 -r json

Options#

 -h, --help help for lead-time
 --since string Start of date window (YYYY-MM-DD, RFC3339, or Nd relative)
 --until string End of date window (default: now)

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

flow throughput

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

gh-velocity flow throughput#

Count issues closed and PRs merged in a window

Synopsis#

Throughput counts the number of issues closed and pull requests merged in a date window. This is the simplest measure of team output.

Default window is the last 30 days.

gh-velocity flow throughput [flags]

Examples#

 # Last 30 days
 gh velocity flow throughput

 # Last 7 days, JSON output
 gh velocity flow throughput --since 7d -r json

 # Remote repo
 gh velocity flow throughput --since 30d -R cli/cli

Options#

 -h, --help help for throughput
 --since string Start of date window (default: 30d)
 --until string End of date window (default: now)

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

flow velocity

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

gh-velocity flow velocity#

Measure effort completed per iteration (sprint velocity)

Synopsis#

Velocity measures effort completed per iteration and completion rate.

Three effort strategies: count — every item = 1 (default) attribute — map labels/types to effort values via matchers numeric — read effort from a project board Number field

Two iteration strategies: project-field — read boundaries from a ProjectV2 Iteration field fixed — calendar math from length + anchor date

gh velocity

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

gh-velocity#

GitHub velocity and quality metrics

Synopsis#

Compute velocity and quality metrics from GitHub data and post them where the work happens.

Options#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 -h, --help help for gh-velocity
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

issue

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

gh-velocity issue#

Composite detail view for a single issue

Synopsis#

Show everything about a single issue: facts (timestamps, category), metrics (lead time, cycle time), and linked PRs with their cycle times.

This is the recommended command for per-item GitHub Actions automation. Use --post to add a rich comment to the issue when it closes.

gh-velocity issue <number> [flags]

Examples#

 # View issue detail
 gh velocity issue 42

 # Post as a comment on the issue
 gh velocity issue 42 --post

 # JSON output
 gh velocity issue 42 -r json

Options#

 -h, --help help for issue

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

pr

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

gh-velocity pr#

Composite detail view for a single pull request

Synopsis#

Show everything about a single PR: facts (author, timestamps), metrics (cycle time, time to first review, review rounds), and closed issues.

This is the recommended command for per-PR GitHub Actions automation. Use --post to add a rich comment to the PR when it merges.

gh-velocity pr <number> [flags]

Examples#

 # View PR detail
 gh velocity pr 125

 # Post as a comment on the PR
 gh velocity pr 125 --post

 # JSON output
 gh velocity pr 125 -r json

Options#

 -h, --help help for pr

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

quality

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

gh-velocity quality#

Quality metrics for releases

Synopsis#

Is this release good?

Quality metrics analyze your releases:

release Composition, bug ratio, timing, and per-issue breakdown for a specific release tag

Options#

 -h, --help help for quality

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

quality release

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

gh-velocity quality release#

Release velocity and quality metrics

Synopsis#

Compute per-issue lead time, cycle time, release lag, and quality metrics for a release.

Use --discover to show the discovery diagnostic view: which issues and PRs each linking strategy discovered for the release.

gh-velocity quality release <tag> [flags]

Examples#

 # Release metrics with auto-detected previous tag
 gh velocity quality release v2.65.0

 # Explicit previous tag
 gh velocity quality release v2.65.0 --since v2.64.0

 # Discover diagnostic: what did each strategy find?
 gh velocity quality release v2.65.0 --discover

 # Remote repo, JSON output
 gh velocity quality release v2.65.0 -R cli/cli -r json

Options#

 --discover Show discovery diagnostic: what issues/PRs each strategy discovered
 -h, --help help for release
 --since string Override previous tag for commit range (tag name)

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

report

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

gh-velocity report#

Composite dashboard of velocity and quality metrics

Synopsis#

Show a trailing-window report composing lead time, cycle time, throughput, work in progress, and quality metrics.

Default window is the last 30 days. Use --since and --until to customize.

Each section computes independently; a failure in one section does not block others. Sections that require specific config (WIP needs project.id or active_labels; quality needs releases) are gracefully omitted when unavailable.

status

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

gh-velocity status#

Current work status (wip, my-week, reviews)

Synopsis#

What is happening right now?

Status commands show the current state of work:

wip Work in progress — open items with lifecycle labels my-week Personal weekly summary for 1:1 prep reviews Pending and stale pull request reviews

Options#

 -h, --help help for status

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

status my-week

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

gh-velocity status my-week#

Your activity summary for 1:1 prep

Synopsis#

Shows what you shipped, what's blocked, and what's ahead — designed for 1:1 prep.

Sections (in order): Insights Shipping velocity, AI-assisted %, lead time median & p90 Waiting on PRs waiting for first review, stale issues What I shipped Issues closed, PRs merged, PRs reviewed, releases What's ahead Open issues and PRs with status annotations Review queue PRs from others waiting on your review

status reviews

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

gh-velocity status reviews#

Show PRs awaiting review

Synopsis#

Show open pull requests that are waiting for code review.

PRs waiting more than 48 hours are flagged as STALE.

This command shows the work (PRs), not individual reviewers.

gh-velocity status reviews [flags]

Examples#

 # Show review queue
 gh velocity status reviews

 # Markdown for posting to a discussion
 gh velocity status reviews -r markdown

 # JSON for automation
 gh velocity status reviews -r json

Options#

 -h, --help help for reviews

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

status wip

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

gh-velocity status wip#

Show work in progress

Synopsis#

Show items currently in progress.

Uses lifecycle.in-progress.match and lifecycle.in-review.match labels from config to find open issues that are actively being worked on.

Use -R owner/repo to target a specific repo.

gh-velocity status wip [flags]

Examples#

 # Show WIP from configured lifecycle labels
 gh velocity status wip

 # JSON output for CI/automation
 gh velocity status wip -r json

Options#

 -h, --help help for wip

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

version

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

gh-velocity version#

Print version information

gh-velocity version [flags]

Options#

 -h, --help help for version

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)