# 2ticketss
2 complementary command-line tools for GitHub issue management - **00-jira-to-gh-issues**: A Rust tool that converts Jira CSV exports to GitHub issue markdown files compatible with gh-issue-generator. It handles messy CSV data and preserves issue metadata - **01-gh-issue-generator**: A Rust tool that creates GitHub issues from Markdown files with YAML front matter. It parses structured Markdown, supports batch processing, and integrates with GitHub CLI
This commit is contained in:
232
00-jira-to-gh-issues/README.md
Normal file
232
00-jira-to-gh-issues/README.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 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](../01-gh-issue-generator) tool.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Rust](https://www.rust-lang.org/tools/install) installed (cargo, rustc)
|
||||
- Basic familiarity with Jira CSV exports
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Build from source
|
||||
|
||||
1. Clone this repository
|
||||
```bash
|
||||
git clone https://github.com/bee8333/2ticketss.git
|
||||
cd 2ticketss/00-jira-to-gh-issues
|
||||
```
|
||||
|
||||
2. Build the application:
|
||||
```bash
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
3. The executable will be in `target/release/jira-to-gh-issues`
|
||||
|
||||
4. Optional: Add to your PATH
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```toml
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# Assuming you've exported Jira issues to "sprint-backlog.csv"
|
||||
```
|
||||
|
||||
### 2. Convert to GitHub issue format
|
||||
```bash
|
||||
jira-to-gh-issues --input sprint-backlog.csv --output github-issues
|
||||
```
|
||||
|
||||
### 3. Create GitHub issues using gh-issue-generator
|
||||
```bash
|
||||
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:
|
||||
|
||||
```markdown
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user