JiraMetrics

https://jirametrics.org
Admin
JiraMetrics is an open-source tool that extracts workflow data from Jira to generate HTML reports,...
Tokens:18,645
Snippets:303
Trust Score:6.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Define start_at with status

Source: https://jirametrics.org/config/cycletime

Example of setting the start time when an issue enters a specific status.

```ruby
start_at first_time_in_status 'In Progress'
```

--------------------------------

### Install project dependencies

Source: https://jirametrics.org/contributing

Commands to install Ruby and JavaScript dependencies required for development.

```bash
bundle install
```

```bash
npm install
```

--------------------------------

### Example downloader output

Source: https://jirametrics.org/quickstart

Sample console output showing the data retrieval process.

```text
Sample

Sample
  Downloading all statuses
  Downloading board configuration for board 44
  Downloading sprints for board 44
  Downloading primary issues for board 44
    Downloaded 1-2 of 2 issues to target/sample_issues/ 
  Downloading linked issues for board 44
Full output from downloader in jirametrics.log
Sample
```

--------------------------------

### Initialize dependency_chart

Source: https://jirametrics.org/charts

Basic invocation of the dependency chart, which requires GraphViz to be installed on the system.

```ruby
dependency_chart
```

--------------------------------

### Install JiraMetrics via pkgsrc

Source: https://jirametrics.org/install

Commands for installing JiraMetrics using the pkgsrc package management system.

```bash
sudo pkgin -y install 'ruby*-jirametrics'
```

```bash
cd devel/ruby-jirametrics
bmake install
```

--------------------------------

### Install JiraMetrics on JRuby

Source: https://jirametrics.org/install

Command to install the gem specifically within a JRuby environment.

```bash
jruby -S gem install jirametrics
```

--------------------------------

### Define first_time_in_or_right_of_column

Source: https://jirametrics.org/config/cycletime

Example of using the first_time_in_or_right_of_column method.

```ruby
first_time_in_or_right_of_column 'In Progress'
```

--------------------------------

### Configure JiraMetrics with config.rb

Source: https://jirametrics.org/config

A comprehensive example of a configuration file defining global settings and project-specific board and file export parameters.

```ruby
Exporter.configure do
  target_path 'target'
  jira_config 'improvingflow.json'
  timezone_offset '-08:00'
  holiday_dates '2024-12-25', '2024-12-26'


  project do
    file_prefix 'sample'

    download do
      rolling_date_count 90
    end

    board id: 1 do
      cycletime do
        start_at first_time_in_status_category('In Progress')
        stop_at still_in_status_category('Done')
      end
    end

    file do
      file_suffix '.csv'

      columns do
        write_headers true

        date 'Done', currently_in_status_category('Done')
        date 'Start', first_time_in_status_category('In Progress')
        string 'Type', type
        string 'Key', key
        string 'Summary', summary
      end
    end
end
```

--------------------------------

### GET not_yet_started

Source: https://jirametrics.org/mcp

Retrieves issues that have not yet been started, sorted by creation date with the oldest first.

```APIDOC
## GET not_yet_started

### Description
Returns issues that have not yet been started (backlog items), sorted by creation date oldest first.

### Parameters
#### Query Parameters
- **project** (string) - Optional - Only return issues from this project name.
- **current_status** (string) - Optional - Only return issues currently in this status.
- **current_column** (string) - Optional - Only return issues whose current status maps to this board column.
- **history_field** (string) - Optional - Only return issues where this field ever had the value specified by history_value. Must be used together with history_value.
- **history_value** (string) - Optional - The value to look for in the change history of history_field. Must be used together with history_field.
- **ever_blocked** (boolean) - Optional - Only return issues that were ever blocked.
- **ever_stalled** (boolean) - Optional - Only return issues that were ever stalled.
- **currently_blocked** (boolean) - Optional - Only return issues that are blocked right now.
- **currently_stalled** (boolean) - Optional - Only return issues that are stalled right now.
```

--------------------------------

### Install JiraMetrics via RubyGems

Source: https://jirametrics.org/install

Standard command to install the JiraMetrics gem on a system with a compatible Ruby version.

```bash
gem install jirametrics
```

--------------------------------

### List and Inspect Jira Boards

Source: https://jirametrics.org/quickstart

Commands to list available boards and inspect specific board columns to identify start and stop points for cycle time calculations.

```bash
jirametrics boards
```

```bash
jirametrics boards 44
```

--------------------------------

### Configure download date boundaries

Source: https://jirametrics.org/config/project

Sets the rolling date count and a start date boundary for Jira issue retrieval.

```ruby
download do
  rolling_date_count 90
  no_earlier_than '2024-10-01'
end
```

--------------------------------

### Custom cycletime logic

Source: https://jirametrics.org/config/cycletime

Example of passing an arbitrary block of code to extract custom data for cycletime calculations.

```ruby
start_at ->(issue) { issue.get_whatever_data_you_want }
```

--------------------------------

### NextGen Project Configuration Error

Source: https://jirametrics.org/changes

Example of the runtime error encountered when NextGen projects cause status category conflicts.

```ruby
/jirametrics/project_config.rb:205:in `add_possible_status': Redefining status category Status(name="FakeBacklog", id=10012, category_name="To Do", category_id=2) with Status(name="FakeBacklog", id=10017, category_name="In Progress", category_id=4). Was one set in the config? (RuntimeError)
```

--------------------------------

### Define currently_in_status

Source: https://jirametrics.org/config/cycletime

Example of using the currently_in_status method to match work currently in a specific status.

```ruby
currently_in_status 'In Progress'
```

--------------------------------

### Define board cycle time

Source: https://jirametrics.org/config/project

Configures the start and stop criteria for cycle time calculations on a specific Jira board.

```ruby
board id: 1 do
  cycletime do
    start_at first_time_in_status_category('In Progress')
    stop_at still_in_status_category('Done')
  end
end
```

--------------------------------

### Display Aging Work in Progress Chart

Source: https://jirametrics.org/charts

Renders the aging work in progress chart to visualize items that have started but not yet finished.

```text
aging_work_in_progress_chart
```

--------------------------------

### Initial Ruby Configuration

Source: https://jirametrics.org/quickstart

Set up the base configuration file with timezone and path settings.

```ruby
Exporter.configure do
  timezone_offset '-08:00'
  target_path 'target/'
  jira_config 'jira_config.json'
end
```

--------------------------------

### Configure a standard project

Source: https://jirametrics.org/config/standard_project

Initializes a project using the standard_project helper. The require statement is mandatory to avoid undefined method errors.

```ruby
require 'jirametrics/examples/standard_project'

Exporter.configure do
  target_path 'target'
  jira_config 'improvingflow.json'

  standard_project name: 'Maple', file_prefix: 'maple', boards: { 1 => :default }
end
```

--------------------------------

### Create Working Directory

Source: https://jirametrics.org/quickstart

Initialize a new directory for JiraMetrics data and reports.

```bash
mkdir myreports
cd myreports
```

--------------------------------

### Configure standard_project in config.rb

Source: https://jirametrics.org/quickstart

Define your project configuration, including timezone, output paths, and cycle time logic for specific boards.

```ruby
require 'jirametrics/examples/standard_project'

Exporter.configure do
  timezone_offset '-08:00'
  target_path 'target/'
  jira_config 'jira_config.json'

  standard_project name: 'Sample', file_prefix: 'sample', boards: {
    44 => lambda do |_|
      start_at first_time_in_or_right_of_column 'In Progress'
      stop_at first_time_in_or_right_of_column 'Done'
    end
  }
end
```

--------------------------------

### Define project file structure

Source: https://jirametrics.org/config/project

Basic template for defining file prefixes and download/file configurations within a project block.

```ruby
project do
  file_prefix 'sample'

  download do
    # ...
  end

  file do
    # ...
  end
end
```

--------------------------------

### Configure MCP server with .mcp.json

Source: https://jirametrics.org/mcp

Basic configuration for the MCP server using the standard PATH.

```json
{
  "mcpServers": {
    "jirametrics": {
      "type": "stdio",
      "command": "jirametrics",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### aging_work

Source: https://jirametrics.org/mcp

Returns all issues that have been started but not yet completed (work in progress), sorted from oldest to newest.

```APIDOC
## aging_work

### Description
Returns all issues that have been started but not yet completed (work in progress), sorted from oldest to newest. Age is the number of days since the issue was started, calculated relative to the end of the downloaded data range.

### Parameters
- **min_age_days** (integer) - Optional - Only return issues at least this many days old.
- **project** (string) - Optional - Only return issues from this project name.
- **current_status** (string) - Optional - Only return issues currently in this status.
- **current_column** (string) - Optional - Only return issues whose current status maps to this board column.
- **history_field** (string) - Optional - Only return issues where this field ever had the value specified by history_value. Must be used with history_value.
- **history_value** (string) - Optional - The value to look for in the change history of history_field. Must be used with history_field.
- **ever_blocked** (boolean) - Optional - Only return issues that were ever blocked.
- **ever_stalled** (boolean) - Optional - Only return issues that were ever stalled.
- **currently_blocked** (boolean) - Optional - Only return issues that are blocked right now.
- **currently_stalled** (boolean) - Optional - Only return issues that are stalled right now.
```

--------------------------------

### Override cycletime in a chart

Source: https://jirametrics.org/config/cycletime

Example of overriding the board-level cycletime configuration within a specific chart declaration.

```ruby
daily_wip_chart do
  cycletime do
    start_at time_created
    stop_at first_time_in_or_right_of_column('Done')
  end
end
```

--------------------------------

### Basic WIP by Column Chart

Source: https://jirametrics.org/charts

Displays the standard WIP distribution chart for board columns.

```ruby
wip_by_column_chart
```

--------------------------------

### WIP by Column Chart with Recommendations

Source: https://jirametrics.org/charts

Enables historical analysis to suggest WIP limit adjustments based on the 85th-percentile WIP level.

```ruby
wip_by_column_chart do
  show_recommendations
end
```

--------------------------------

### Define custom board logic in standard_project

Source: https://jirametrics.org/config/standard_project

Provides custom cycle time logic for boards instead of using the default configuration.

```ruby
standard_project name: 'Sample', file_prefix: 'sample', boards: {
    1 => lambda do |_|
            start_at first_time_in_status('Refined')
            stop_at still_in_status_category('Done')
          end
  }
```

--------------------------------

### Configure multiple boards in config.rb

Source: https://jirametrics.org/quickstart

Define multiple standard_project entries within the Exporter configuration block to process different boards.

```ruby
require 'jirametrics/examples/standard_project'

Exporter.configure do
  timezone_offset '-08:00'
  target_path 'target/'
  jira_config 'jira_config.json'

  standard_project name: 'Sample', file_prefix: 'sample', boards: {
    44 => lambda do |_|
      start_at first_time_in_or_right_of_column 'In Progress'
      stop_at first_time_in_or_right_of_column 'Done'
    end
  }
  standard_project name: 'Board2', file_prefix: 'board2', boards: {
    3 => lambda do |_|
      start_at first_time_in_or_right_of_column 'In Progress'
      stop_at first_time_in_or_right_of_column 'Done'
    end
  }
end
```

--------------------------------

### Configure Claude Desktop for JiraMetrics

Source: https://jirametrics.org/mcp

Add the jirametrics server entry to the claude_desktop_config.json file to enable the MCP server.

```json
{
  "mcpServers": {
    "jirametrics": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "source ~/.rvm/scripts/rvm && jirametrics mcp --config /full/path/to/your/config.rb"
      ]
    }
  }
}
```

--------------------------------

### GET completed_work

Source: https://jirametrics.org/mcp

Retrieves issues that have been completed, sorted by most recent completion date. Includes metrics like cycle time and flow efficiency.

```APIDOC
## GET completed_work

### Description
Returns issues that have been completed, sorted most recently completed first. Includes cycle time, flow efficiency, and status/resolution at the time of completion.

### Parameters
#### Query Parameters
- **days_back** (integer) - Optional - Only return issues completed within this many days of the data end date.
- **project** (string) - Optional - Only return issues from this project name.
- **completed_status** (string) - Optional - Only return issues whose status at completion matches this value.
- **completed_resolution** (string) - Optional - Only return issues whose resolution at completion matches this value.
- **history_field** (string) - Optional - Only return issues where this field ever had the value specified by history_value.
- **history_value** (string) - Optional - The value to look for in the change history of history_field.
- **ever_blocked** (boolean) - Optional - Only return issues that were ever blocked.
- **ever_stalled** (boolean) - Optional - Only return issues that were ever stalled.
- **currently_blocked** (boolean) - Optional - Only return issues that were blocked at the time of completion.
- **currently_stalled** (boolean) - Optional - Only return issues that were stalled at the time of completion.
```

--------------------------------

### Jira Credentials Configuration

Source: https://jirametrics.org/quickstart

Define the Jira instance URL, user email, and API token in a JSON file.

```json
{
  "url": "https://improvingflow.atlassian.net",
  "email": "mbowler@gargoylesoftware.com",
  "api_token": "abcdefghijklmnopqrstuvwxyz"
}
```

--------------------------------

### Verify Jira Connection

Source: https://jirametrics.org/jira

Run this command to confirm that your credentials are valid without downloading any issue data.

```bash
jirametrics verify
```

--------------------------------

### Name a project

Source: https://jirametrics.org/config/project

Assign a name to a project to distinguish it when multiple projects are defined.

```ruby
project name: "MyName" do
  ...
end
```

--------------------------------

### Configure a file for HTML export

Source: https://jirametrics.org/project/file_html

Defines the file suffix and the charts to include in an HTML report.

```ruby
file do
  file_suffix '.html'

  html_report do
    # List of all the charts we want to include, in the order we want to see them in the report
    cycletime_scatterplot
    cycletime_histogram
    throughput_chart
  end
end
```

--------------------------------

### Configure project settings

Source: https://jirametrics.org/config/project

Apply custom settings within the project block to modify tool behavior, such as ignoring SSL errors.

```ruby
project do
  ...
  settings['ignore_ssl_errors'] = true
end
```

--------------------------------

### Integrate JiraMetrics with apfel

Source: https://jirametrics.org/mcp

Pass the full path of the executable to apfel using the which command.

```bash
apfel --mcp $(which jirametrics-mcp) "what boards do we have?"
```

--------------------------------

### Display Daily WIP by Age Chart

Source: https://jirametrics.org/charts

Visualizes the number of items in progress per day, color-coded by their age.

```text
daily_wip_by_age_chart
```

--------------------------------

### Configure daily_wip_chart

Source: https://jirametrics.org/charts

Define custom grouping rules for daily WIP charts to categorize issues by their parent ticket.

```ruby
daily_wip_chart do
  header_text 'Daily WIP by Parent'
  description_text <<-TEXT
    How much work is in progress, grouped by the parent of the issue. This will give us an
    indication of how focused we are on higher level objectives. If there are many parent
    tickets in progress at the same time, either this team has their focus scattered or we
    aren't doing a good job of splitting those parent tickets. Neither of those is desirable.
  TEXT
  grouping_rules do |issue, rules|
    rules.label = issue.parent&.key || 'No parent'
    rules.color = 'white' if rules.label == 'No parent'
  end
end
```

--------------------------------

### Define file suffix

Source: https://jirametrics.org/project/file_html

Sets the extension for the generated file, defaulting to .csv if not specified.

```ruby
file_suffix '.html'
```

--------------------------------

### Configure Personal Access Token Authentication

Source: https://jirametrics.org/jira

Use this configuration for Jira Server or Data Center instances by providing your instance URL and personal access token.

```json
{
  "url": "https://<your_url>",
  "personal_access_token": "<your_personal_access_token>"
}
```

--------------------------------

### Define projects in Exporter configuration

Source: https://jirametrics.org/config/project

Basic structure for declaring projects, including the ability to ignore projects by prefixing with 'x'.

```ruby
Exporter.configure do
  target_path 'target'
  jira_config 'improvingflow.json'
  timezone_offset '-08:00'

  project do
    # ... project 1 ...
  end

  project do
    # ... project 2 ...
  end

  xproject do
    # ... ignored project ...
  end
end
```

--------------------------------

### Redefine configuration settings per project

Source: https://jirametrics.org/config/project

Settings are inherited from preceding definitions, allowing for project-specific overrides by redefining them before the project block.

```ruby
Exporter.configure do
  target_path 'target'
  jira_config 'improvingflow.json'

  project do
    # ... project 1 ...
  end

  target_path 'target2'
  jira_config 'other.json'

  project do
    # ... project 2 using different target and jira config ...
  end
end
```

--------------------------------

### Execute JiraMetrics report generation

Source: https://jirametrics.org/quickstart

Run the command to download data and generate the report.

```bash
jirametrics go
```

--------------------------------

### Include custom CSS

Source: https://jirametrics.org/project/file_html

Configures the project to load a custom CSS file for report styling.

```ruby
project name: 'foo' do
  setting['include_css'] = './my_custom_css.css'
end
```

```ruby
project name: 'foo' do
  setting['include_css'] = './legacy_colors.css'
end
```

--------------------------------

### Basic Cumulative Flow Diagram

Source: https://jirametrics.org/charts

The simplest implementation of the cumulative_flow_diagram chart.

```ruby
cumulative_flow_diagram

```

--------------------------------

### list_projects

Source: https://jirametrics.org/mcp

Returns all available projects with their issue count, data end date, and any aggregate groups defined in the configuration.

```APIDOC
## list_projects

### Description
Returns all available projects with their issue count and data end date, plus any aggregate groups defined in your config. Claude will call this automatically when a question is ambiguous about which project it applies to.

### Parameters
This tool takes no parameters.
```

--------------------------------

### Configure MCP server with absolute path

Source: https://jirametrics.org/mcp

Use an absolute path for the command if the MCP host cannot locate the jirametrics executable on the system PATH.

```json
{
  "mcpServers": {
    "jirametrics": {
      "type": "stdio",
      "command": "/Users/you/.rbenv/shims/jirametrics",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Configure Jirametrics MCP in Vibe

Source: https://jirametrics.org/mcp

Use this configuration in your config.toml to run the Jirametrics MCP server over stdio. Ensure the command path points to the absolute path of the executable.

```toml
[[mcp_servers]]
name = "jirametrics"
transport = "stdio"
command = "C:/Ruby/bin/jirametrics-mcp"
args = ["--config", "C:/development/myreports/config.rb"]
```

--------------------------------

### Exporting Projects by Name

Source: https://jirametrics.org/changes

Usage of the --name parameter to selectively export projects using wildcard patterns.

```bash
jirametrics export --name "a*"
```

--------------------------------

### Configure Cookie-based Authentication

Source: https://jirametrics.org/jira

Use this as a last resort fallback. Requires manually copying authentication cookies from your browser, which must be refreshed periodically.

```json
{
  "cookies": {
    "<key>": "<value>"
  }
}
```

--------------------------------

### Generate throughput chart

Source: https://jirametrics.org/charts

Basic command to generate a weekly throughput line chart.

```ruby
throughput_chart
```

--------------------------------

### Specify both project name and ID

Source: https://jirametrics.org/config/project

Combine name and ID parameters when both are required for project identification.

```ruby
project name: 'MyProject', id: 5 do
  ...
end
```

--------------------------------

### Generate column entry times

Source: https://jirametrics.org/project/file_csv

Automatically generates columns for entry times per board status, often used for integration with Actionable Agile.

```ruby
# This is typical configuration for the Actionable Agile tool
columns do
  write_headers true

  string 'ID', key
  string 'link', url
  string 'title', summary
  column_entry_times
end
```

--------------------------------

### Configure multiple GitHub repositories

Source: https://jirametrics.org/config/project

Specifies multiple GitHub repositories to fetch pull request data from in a single call.

```ruby
download do
  rolling_date_count 90
  github_repo 'owner/repo1', 'owner/repo2'
end
```

--------------------------------

### Run JiraMetrics MCP with single-word command assistants

Source: https://jirametrics.org/mcp

Use the jirametrics-mcp executable for AI assistants that do not support subcommands.

```bash
jirametrics-mcp --config /full/path/to/your/config.rb
```

--------------------------------

### Configure an aggregated project

Source: https://jirametrics.org/config/aggregated_project

Defines an aggregated project by referencing previously configured standard projects. Ensure all referenced project names are declared before aggregation.

```ruby
Exporter.configure do
  target_path 'target'
  jira_config 'improvingflow.json'

  standard_project name: 'Maple', file_prefix: 'maple', boards: { 1 => :default }
  standard_project name: 'Pine', file_prefix: 'pine', boards: { 2 => :default }

  aggregated_project name: 'forest', project_names: ['Maple', 'Pine']
end
```

--------------------------------

### Configure API Token Authentication

Source: https://jirametrics.org/jira

Use this configuration for Jira Cloud instances by providing your instance URL, email, and generated API token.

```json
{
  "url": "https://<your_url>",
  "email": "<your email>",
  "api_token": "<your_api_key>"
}
```

--------------------------------

### Create a consolidated report template

Source: https://jirametrics.org/stitcher

Define an ERB template to pull charts from existing report files using the grab_by_title method.

```erb
This is a sample report with a single chart below.

<%= grab_by_title 'Cycletime Scatterplot', from_file: 'target/myproject.html' %>

Here is some more text below the chart.
```

--------------------------------

### Display and Configure Cycle Time Scatterplot

Source: https://jirametrics.org/charts

Renders a cycle time scatterplot and demonstrates how to apply custom grouping rules to categorize and style data points.

```text
cycletime_scatterplot
```

```ruby
cycletime_scatterplot do
  grouping_rules do |issue, rules|
    # Put all data into groups by type. Use the name of the
    # type as the label for the group
    rules.label = issue.type
    if issue.type == 'Story'
      # Set the color of stories to be green
      rules.color = 'green'
    else issue.type == 'Spike'
      # Ignore spikes
      rules.ignore
    else
      rules.color = 'yellow'
    end
  end
end
```

--------------------------------

### Configure project ID

Source: https://jirametrics.org/changes

Use this syntax to explicitly add a project ID to the configuration when required by the tool for team-managed projects.

```ruby
project id: 5 do
...
end
```

--------------------------------

### Display Daily WIP by Parent Ticket

Source: https://jirametrics.org/charts

Groups work-in-progress items by their parent ticket to analyze strategic focus.

```text
daily_wip_by_parent_chart
```

--------------------------------

### Specify a project ID

Source: https://jirametrics.org/config/project

Manually provide a project ID if the system cannot automatically determine it from the board.

```ruby
project id: 5 do
  ...
end
```

--------------------------------

### Configure JRuby Environment Variables

Source: https://jirametrics.org/install

Required environment variable configuration to prevent hanging during dependency report generation when using JRuby.

```bash
export JAVA_OPTS="--add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED"
```

--------------------------------

### Configure JiraMetrics for Actionable Agile Data Export

Source: https://jirametrics.org/forecasting

This configuration generates the specific CSV format required for Actionable Agile. The columns block defines the necessary fields for the export.

```ruby
Exporter.configure do
  timezone_offset '-05:00'

  target_path 'target/'
  jira_config 'jira_config_improvingflow.json'

  project name: 'myproject' do
    file_prefix 'myproject'

    download do
      rolling_date_count 90
    end

    board id: 1 do
      cycletime do
        start_at first_time_in_status_category('In Progress')
        stop_at still_in_status_category('Done')
      end
    end

    discard_changes_before status_becomes: :backlog # 'To Do'

    file do
      file_suffix '.csv'

      columns do
        write_headers true

        string 'ID', key
        string 'link', url
        string 'title', summary
        column_entry_times
      end
    end
  end
end
```

--------------------------------

### Generate expedited items chart

Source: https://jirametrics.org/charts

Displays the chart showing expedited items and their duration.

```ruby
expedited_chart
```

--------------------------------

### Configure a CSV file export

Source: https://jirametrics.org/project/file_csv

Defines the file suffix and column structure for a CSV export.

```ruby
file do
  file_suffix '.csv'
  # This is a typical configuration for the team dashboard at FocusedObjective.com
  columns do
    write_headers true

    date 'Done', currently_in_status_category('Done')
    date 'Start', first_time_in_status_category('In Progress')
    string 'Type', type
    string 'Key', key
    string 'Summary', summary
  end
end
```

--------------------------------

### Customize dependency_chart link_rules

Source: https://jirametrics.org/charts

Define rules for link visualization, including ignoring specific link types and configuring bidirectional link behavior.

```ruby
dependency_chart do
  link_rules do |link, rules|
    case link.name
    when 'Cloners'
      # We don't want to see any clone links at all.
      rules.ignore
    when 'Blocks'
      # For blocks, by default Jira will have links going both
      # ways and we want them only going one way. Also make the
      # link red.
      rules.merge_bidirectional keep: 'outward'
      rules.line_color = 'red'
    when 'Sync'
      # For sync, also only show one link but this time put 
      # arrows at both ends
      rules.merge_bidirectional keep: 'outward'
      rules.use_bidirectional_arrows
    end
  end
end
```

--------------------------------

### Configure GitHub repository for pull requests

Source: https://jirametrics.org/config/project

Specifies a single GitHub repository to fetch pull request data from.

```ruby
download do
  rolling_date_count 90
  github_repo 'owner/repo'
end
```

--------------------------------

### Configure MCP server for RVM

Source: https://jirametrics.org/mcp

Special configuration for RVM environments that require sourcing the RVM script before executing the command.

```json
{
  "mcpServers": {
    "jirametrics": {
      "type": "stdio",
      "command": "/bin/bash",
      "args": ["-c", "source ~/.rvm/scripts/rvm && jirametrics mcp"]
    }
  }
}
```

--------------------------------

### Configure Status Category Mappings

Source: https://jirametrics.org/faq

Define mappings for retired Jira statuses to ensure correct categorization in reports. Use the standard_project configuration to apply these mappings globally or per project.

```ruby
retired_statuses = {
  'Refinement:10012' => 'To Do',
  'Sign Off:10044' => 'Done'
}

standard_project name: 'Sample', file_prefix: 'sample',
  boards: { 44 => :default }, status_category_mappings: retired_statuses
```

--------------------------------

### Display Daily WIP by Blocked or Stalled Status

Source: https://jirametrics.org/charts

Tracks items that are flagged as blocked or have not changed status in the last five days.

```text
daily_wip_by_blocked_stalled_chart
```

--------------------------------

### Define blocked statuses

Source: https://jirametrics.org/config/project

Set a list of statuses that should be treated as blocked in the project configuration.

```ruby
settings['blocked_statuses']=['Blocked']
```

--------------------------------

### Generate estimate accuracy chart

Source: https://jirametrics.org/charts

Displays the default estimate accuracy chart using story points.

```ruby
estimate_accuracy_chart
```

--------------------------------

### Annotate charts with dates

Source: https://jirametrics.org/config/project

Add timestamped annotations to various charts by defining the date_annotations key in settings.

```json
"date_annotations": [
  { "date": "2025-12-05T10:00:00", "label": "Stuff happened" },
  { "date": "2025-12-08T10:00:00", "label": "More stuff" }
]
```

--------------------------------

### Basic Pull Request Cycle Time Histogram

Source: https://jirametrics.org/charts

Displays the default pull request cycle time distribution.

```ruby
pull_request_cycle_time_histogram

```

--------------------------------

### Authenticate GitHub CLI

Source: https://jirametrics.org/config/project

Command to authenticate the GitHub CLI required for downloading pull request data.

```bash
gh auth login
```

--------------------------------

### Basic pull_request_cycle_time_scatterplot usage

Source: https://jirametrics.org/charts

The simplest form of the pull request cycle time scatterplot.

```ruby
pull_request_cycle_time_scatterplot
```

--------------------------------

### Generate sprint burndown charts

Source: https://jirametrics.org/charts

Commands to generate sprint burndown charts by story points, story count, or both.

```ruby
# Generate both burndowns
sprint_burndown

# Generate only the story point burndown
sprint_burndown :points_only

# Generate only the story count burndown
sprint_burndown :counts_only
```

--------------------------------

### Configure custom parent link field

Source: https://jirametrics.org/faq

Use this setting to map a specific custom field to parent links when automatic detection fails.

```python
settings['customfield_parent_links'] = ['customfield_10019']
```

--------------------------------

### Define HTML report charts

Source: https://jirametrics.org/project/file_html

Lists the charts to be included in the report in the desired order.

```ruby
html_report do
  cycletime_scatterplot
  cycletime_histogram
  throughput_chart
end
```

--------------------------------

### Customize grouping rules

Source: https://jirametrics.org/charts

Define custom labels and colors for grouped data points.

```ruby
pull_request_cycle_time_scatterplot do
  cycletime_unit :hours
  grouping_rules do |pull_request, rules|
    rules.label = pull_request.repo
    rules.color = 'green'
  end
end
```

--------------------------------

### Display Cycle Time Histogram

Source: https://jirametrics.org/charts

Renders a histogram to plot the distribution of cycle times for completed work.

```text
cycletime_histogram
```

--------------------------------

### Configure cycle time units

Source: https://jirametrics.org/charts

Change the unit of measurement for the y-axis.

```ruby
pull_request_cycle_time_scatterplot do
  cycletime_unit :hours
end
```

--------------------------------

### Customizing Cycle Time Units

Source: https://jirametrics.org/charts

Configures the x-axis unit for the histogram. Supported units include :days, :hours, :minutes, and :hours24.

```ruby
pull_request_cycle_time_histogram do
  cycletime_unit :hours
end

```

--------------------------------

### Define custom column calculation

Source: https://jirametrics.org/project/file_csv

Uses a lambda to calculate column values dynamically when built-in methods are insufficient.

```ruby
columns do
  string 'sprint_count', ->(issue) { issue.get_whatever_data_you_want }
end
```

--------------------------------

### Configure status category mapping

Source: https://jirametrics.org/config/project

Maps a missing Jira status to a valid category to resolve export errors caused by deleted statuses.

```ruby
project do
  status_category_mapping status: 'MyNewStatus:3', category: 'In Progress'
end
```

```ruby
project do
  # Note that the id is missing for MyNewStatus
  status_category_mapping status: 'MyNewStatus', category: 'In Progress'
end
```
Tokens:
Raw