Getting Started on gh-velocity

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:

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:

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.

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.