Getting Started#

gh-velocity computes engineering metrics from your GitHub data. This section takes you from first install to a fully configured system.

1. Install and run your first report#

Two commands. No configuration beyond what preflight generates.

gh extension install dvhthomas/gh-velocity
cd your-repo
gh velocity config preflight --write   # analyzes your repo, writes .gh-velocity.yml
gh velocity report --since 30d         # lead time, throughput, quality

No labels, no workflows, no project boards required. See the Quick Start for the full walkthrough.

2. Enable cycle time with lifecycle labels#

Cycle time measures how long work is actively in progress. It needs a signal for when work starts -- an in-progress label applied to the issue. Without it, cycle time shows "n/a."

If you use a GitHub Projects board, project-label-sync can apply lifecycle labels automatically when issues move between columns. See Cycle Time Setup.

3. Add per-release quality metrics#

When you tag a release, gh velocity quality release v1.0.0 shows what went into it -- bug ratio, issue composition, per-item timing. To post this automatically on every release, add a release workflow. The release event triggers the report and posts it as a Discussion or comment.

4. Add automatic metrics on each issue and PR#

gh velocity issue 42 and gh velocity pr 125 show composite metrics for a single item -- lead time, cycle time, review rounds, linked PRs. With --post, they write those metrics directly into the issue or PR body on close or merge.

To automate this, add a workflow file. It listens for issue close and PR merge events and runs the corresponding command.

This is per-repo. GitHub Actions triggers only fire for events in their own repository. Every repo needs two files: .gh-velocity.yml (generated by preflight --write) and the workflow file.

The full picture#

Once fully configured, a repo gets:

  • Summary reports on demand or on a schedule (report --since 30d)
  • Release quality posted automatically when you tag (quality release)
  • Issue metrics posted to each issue body when it closes (issue <N> --post)
  • PR metrics posted to each PR body when it merges (pr <N> --post)
  • Cycle time driven by lifecycle labels, optionally synced from your project board

Each piece is independent. Start with step 1 and add the rest when ready.

Quick Start Forward