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

Configure in .gh-velocity.yml under the velocity: section. Run 'gh velocity config preflight' to get suggested configuration.

gh-velocity flow velocity [flags]

Examples#

  # Default: count effort, last 6 iterations
  gh velocity flow velocity

  # Current iteration only
  gh velocity flow velocity --current

  # Last 3 iterations, JSON output
  gh velocity flow velocity --history --iterations 3 --format json

  # With date filter
  gh velocity flow velocity --since 2026-01-01 --until 2026-03-01

  # Show not-assessed item numbers
  gh velocity flow velocity --verbose

Options#

      --current          Show only the current iteration
  -h, --help             help for velocity
      --history          Show only past iterations
      --iterations int   Number of past iterations to show (overrides config)
      --since string     Show iterations overlapping this start date
      --until string     Show iterations overlapping this end date
      --verbose          Include not-assessed item numbers

Options inherited from parent commands#

      --config string   Path to config file (default: .gh-velocity.yml)
      --debug           Print diagnostic info to stderr
  -f, --format string   Output format: json, pretty, markdown (default "pretty")
      --new-post        Force a new post (skip idempotent update; implies --post)
      --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
      --scope string    Additional GitHub search qualifier(s) ANDed with config scope

SEE ALSO#

• gh-velocity flow - Flow metrics (lead-time, cycle-time, velocity)