2ticketss/00-jira-to-gh-issues

Jira to GitHub Issues Converter

A Rust command-line tool that converts Jira CSV exports to GitHub issue markdown files compatible with the gh-issue-generator tool.

Prerequisites

• Rust installed (cargo, rustc)
• Basic familiarity with Jira CSV exports

Installation

Option 1: Build from source

1. Clone this repository

git clone https://github.com/bee8333/2ticketss.git
cd 2ticketss/00-jira-to-gh-issues

2. Build the application:

cargo build --release

3. The executable will be in target/release/jira-to-gh-issues

4. Optional: Add to your PATH

# Linux/macOS
cp target/release/jira-to-gh-issues ~/.local/bin/

# or add the following to your .bashrc or .zshrc
export PATH="$PATH:/path/to/2ticketss/00-jira-to-gh-issues/target/release"

Option 2: Install with Cargo

If you have Rust installed, you can install directly with:

cargo install --path .

Exporting Issues from Jira

1. In Jira, go to the issue list view (with all filters applied)
2. Click "Export" and select "CSV (All fields)"
3. Save the CSV file

Required Jira fields:

• Summary (required)
• Issue key (required)

Recommended fields (for best results):

• Issue Type
• Priority
• Description
• Assignee
• Reporter
• Created
• Labels

Usage

jira-to-gh-issues [OPTIONS] --input <jira_export.csv>

Arguments:

• --input, -i <jira_export.csv>: Path to the CSV file exported from Jira (required)

Options:

• --output, -o <output_dir>: Directory where the markdown files will be saved
• --status, -s <status>: Default status for the issues (draft or ready)
• --verbose, -v: Increase verbosity level (can be used multiple times: -v, -vv)
• --config, -c <config>: Path to config file

Logging Options

You can control log verbosity in two ways:

1. Using the --verbose flag:

   • -v: Debug level logging
   • -vv: Trace level logging

2. Using the RUST_LOG environment variable:

   # Set global log level
   RUST_LOG=debug jira-to-gh-issues --input issues.csv
   
   # Set per-module log level
   RUST_LOG=jira_to_gh_issues=trace,csv=warn jira-to-gh-issues --input issues.csv
   

Configuration

The tool supports configuration files to store default settings. Configuration is searched in these locations (in order):

1. Path specified with --config option
2. .jira-to-gh-issues.toml in current directory
3. ~/.jira-to-gh-issues.toml in home directory
4. ~/.config/jira-to-gh-issues/config.toml in XDG config directory

A default configuration file will be created at ~/.config/jira-to-gh-issues/config.toml if none exists.

Configuration Options

# Default output directory
output_dir = "00-jira-to-gh-issues/output"

# Default issue status (draft or ready)
default_status = "ready"

# Required fields in CSV
required_fields = ["Summary", "Issue key"]

Creating or Editing Configuration

You can manually create or edit the configuration file, or run the tool once to create a default configuration automatically.

For example, to set custom defaults:

mkdir -p ~/.config/jira-to-gh-issues
cat > ~/.config/jira-to-gh-issues/config.toml << EOF
output_dir = "github-issues/jira-exports"
default_status = "draft"
required_fields = ["Summary", "Issue key", "Description"]
EOF

Example Workflow

1. Export issues from Jira

# Assuming you've exported Jira issues to "sprint-backlog.csv"

2. Convert to GitHub issue format

jira-to-gh-issues --input sprint-backlog.csv --output github-issues

3. Create GitHub issues using gh-issue-generator

cd ..
gh-issue-generator --repo myuser/myrepo github-issues/20240405123045/batch.md

How It Works

1. The tool reads a CSV file exported from Jira
2. For each issue in the CSV, it:
   • Extracts relevant information (title, description, labels, etc.)
   • Converts it to the GitHub issue markdown format with YAML front matter
   • Writes individual markdown files for each issue
   • Creates a batch file containing all issues
3. Output is saved in a timestamped directory to avoid overwriting previous conversions
4. An error log is generated for any issues that couldn't be processed

Output Format

The tool generates:

1. Individual markdown files for each issue (named after the Jira issue key)
2. A batch file containing all issues in the format expected by gh-issue-generator
3. An error log file listing any processing issues

Each generated file follows the format required by the gh-issue-generator tool:

---
title: Issue title
status: ready (or draft)
labels:
  - label1
  - label2
assignees:
  - assignee1
---

# Issue title

## Description

Issue description...

## Metadata

- **Jira Issue**: JIRA-123
- **Created**: Creation date
- **Reporter**: Reporter name

Mapping Rules

Jira Field	GitHub Issue Field
Summary	title
Issue Type	Converted to a label
Priority	High/Critical → priority label
Labels	labels
Description	Description section
Assignee	assignees
Reporter	Listed in metadata
Created	Listed in metadata
Issue Key	Listed in metadata & filename

Troubleshooting

CSV Import Issues

• Ensure the CSV export from Jira includes the required fields (Summary, Issue key)
• If the import fails with "Missing required columns", verify your Jira export contains these field names
• For malformed CSV files, try opening in a spreadsheet application and re-saving

Character Encoding

• If you see corrupted characters, ensure your CSV is UTF-8 encoded
• Some Jira instances export in different encodings depending on region settings

Large Exports

• For very large exports (1000+ issues), consider splitting into multiple files
• Processing large files may require more memory

Limitations

• Complex Jira markup may not convert perfectly to Markdown
• Attachments from Jira issues are not transferred
• Comments are not included in the conversion

License

MIT