Velojiraptor

Velojiraptor pulls data from Jira and generates metrics reports. It can display filtered history and provide insights into several engineering KPIs, including Time In Status and Lead Time.

---

There are similar solutions out there. Why did you implement a custom one?

Mainly because of the Time In Status report. While it’s supported via Jira plugins, these provide a poor interface with other apps. Automating this report wasn’t possible with other plugins available on the market.

We did it for fun, too. 🤓

Table of Contents

• Install
• API Token
• Usage
  • Search
  • History
  • Time in Status
  • Lead Time
  • Count
  • Header List
  • Formats

Install

There are two ways to install Velojiraptor:

Download binaries

You can download precompiled binaries of all versions in the Release section. It’s recommended to use the latest release binary.

Note for macOS users: Since Velojiraptor isn't a notarized app, Apple will prevent you from running it for the first time. To bypass Gatekeeper, you'll need to hold the control key (⌃) while right-clicking on the vjr file, select Open from the popup menu, and then click Open in the alert popup window.

Build from source

To build Velojiraptor from the source code, make sure you have Go 1.17 or higher.

go install cmd/vjr/vjr.go

API Token

Velojiraptor requires a token to access Jira's API. Atlassian's official docs explain how to obtain one.

Jira deprecated basic authentication with passwords but still requires a username to access the endpoints.

Provide your credentials like so:

export JIRA_USERNAME=foo
export JIRA_TOKEN=bar
export JIRA_URL=https://baz.atlassian.net

Usage

Velojiraptor provides various commands. Use the --h or --help flag to display further information about the available options and arguments.

Search

Before Velojiraptor can generate any report, you'll need to feed it with some data. The first step is to search Jira's API for tickets. We will use the search command's output as the input of our reports.

We filter the tickets using Jira Query Language (JQL), which is very flexible: It can filter boards, assignees, statuses, creators, and much more.

Visit Jira's official JQL Guide to learn more.

Here's an example that will generate some data in a file named result.json:

vjr search --jql "project IN (YOUR_PROJECT_NAME) AND updated > 2022-01-02 AND updated < 2022-01-15 AND statusCategory IN (Done)" > result.json 

History

History lists the changes made in the given field based on the search result above. This can be useful for checking how often the due date has changed.

vjr history --input result.json --field status

Time in Status

This report shows how long a ticket remained in a specific status. The numbers are based on the status history. We can exclude statuses by adding -e flags.

vjr time-in-status --input result.json -e TODO -e "In Progress"

Lead Time

We can generate a Lead Time report based on the Time in Status report. Note that the -e flag is also supported here.

vjr lead-time --input result.json -e Foo

Count

The count command is similar to search—we use JQL to find tickets via Jira's API. The difference is under the hood: count is optimized for returning the number of search results.

For example, to search for open bugs, run the following:

vjr search count --jql "type = bug AND statusCategory NOT IN (Done)" 

Header List

The header-list (or hl) displays the headers found in your output file. This is particularly useful for including/excluding the correct columns in your final report. The result will be a list of all the headers, like the following:

vjr header-list --input result.json

"TODO"
"Ready for QA"
"QA Success"
"Ready for Production Deployment"

Formats

Most commands support several output formats. You can control it with the --format flag.

vjr search --jql "project IN (Foo)"

# Table
vjr --format table --jql "project IN (Foo)"

# CSV
vjr --format csv search --jql "project IN (Foo)"