# 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:
425
01-gh-issue-generator/README.md
Normal file
425
01-gh-issue-generator/README.md
Normal file
@@ -0,0 +1,425 @@
|
||||
# GitHub Issue Generator
|
||||
|
||||
A Rust command-line tool that generates GitHub issues from Markdown files. This tool parses structured Markdown files with YAML front matter and uses the GitHub CLI to create issues.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [GitHub CLI](https://cli.github.com/) installed and authenticated
|
||||
- [Rust](https://www.rust-lang.org/tools/install) installed (cargo, rustc)
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Build from source
|
||||
|
||||
1. Clone this repository
|
||||
```bash
|
||||
git clone https://github.com/bee8333/2ticketss.git
|
||||
cd 2ticketss/01-gh-issue-generator
|
||||
```
|
||||
|
||||
2. Build the application:
|
||||
```bash
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
3. The executable will be in `target/release/gh-issue-generator`
|
||||
|
||||
4. Optional: Add to your PATH
|
||||
```bash
|
||||
# Linux/macOS
|
||||
cp target/release/gh-issue-generator ~/.local/bin/
|
||||
|
||||
# or add the following to your .bashrc or .zshrc
|
||||
export PATH="$PATH:/path/to/2ticketss/01-gh-issue-generator/target/release"
|
||||
```
|
||||
|
||||
### Option 2: Install with Cargo
|
||||
|
||||
If you have Rust installed, you can install directly with:
|
||||
```bash
|
||||
cargo install --path .
|
||||
```
|
||||
|
||||
### GitHub CLI Authentication
|
||||
|
||||
Before using this tool, you must authenticate the GitHub CLI:
|
||||
|
||||
```bash
|
||||
# Login to GitHub
|
||||
gh auth login
|
||||
|
||||
# Verify you're authenticated
|
||||
gh auth status
|
||||
```
|
||||
|
||||
Make sure you have the appropriate scopes (repo for private repositories) during authentication.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
gh-issue-generator [OPTIONS] <input_paths>...
|
||||
```
|
||||
|
||||
Arguments:
|
||||
- `<input_paths>...`: One or more paths to Markdown files or directories containing Markdown files
|
||||
|
||||
Options:
|
||||
- `-r, --repo <owner/repo>`: GitHub repository in format owner/repo (e.g., "octocat/Hello-World")
|
||||
- `-d, --dry-run`: Run in dry-run mode (don't actually create issues)
|
||||
- `-v, --verbose`: Increase verbosity level (can be used multiple times: -v, -vv)
|
||||
- `-c, --config <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 gh-issue-generator --repo owner/repo issues/
|
||||
|
||||
# Set per-module log level
|
||||
RUST_LOG=gh_issue_generator=trace,walkdir=warn gh-issue-generator --repo owner/repo issues/
|
||||
```
|
||||
|
||||
Examples:
|
||||
```bash
|
||||
# Process a single Markdown file
|
||||
gh-issue-generator --repo myuser/myrepo issues/feature-request.md
|
||||
|
||||
# Process all Markdown files in a directory
|
||||
gh-issue-generator --repo myuser/myrepo issues/
|
||||
|
||||
# Process multiple files
|
||||
gh-issue-generator --repo myuser/myrepo issues/bug-1.md issues/feature-1.md
|
||||
|
||||
# Dry run (don't create actual issues)
|
||||
gh-issue-generator --repo myuser/myrepo --dry-run issues/
|
||||
|
||||
# Use a specific config file
|
||||
gh-issue-generator --config my-config.toml issues/
|
||||
|
||||
# Use increased verbosity for troubleshooting
|
||||
gh-issue-generator --repo myuser/myrepo --verbose issues/
|
||||
```
|
||||
|
||||
## 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. `.gh-issue-generator.toml` in current directory
|
||||
3. `~/.gh-issue-generator.toml` in home directory
|
||||
4. `~/.config/gh-issue-generator/config.toml` in XDG config directory
|
||||
|
||||
A default configuration file will be created at `~/.config/gh-issue-generator/config.toml` if none exists.
|
||||
|
||||
### Configuration Options
|
||||
|
||||
```toml
|
||||
# Default GitHub repository (optional)
|
||||
# If specified, you can omit --repo command line option
|
||||
default_repo = "myuser/myrepo"
|
||||
|
||||
# Report output directory (default: "report")
|
||||
report_dir = "report"
|
||||
```
|
||||
|
||||
### 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 a default repository:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/gh-issue-generator
|
||||
cat > ~/.config/gh-issue-generator/config.toml << EOF
|
||||
default_repo = "myuser/myrepo"
|
||||
report_dir = "github-issues/reports"
|
||||
EOF
|
||||
```
|
||||
|
||||
## Complete Workflow Examples
|
||||
|
||||
### Example 1: Creating Feature Requests
|
||||
|
||||
1. Create a feature request Markdown file:
|
||||
|
||||
```bash
|
||||
mkdir -p issues/features
|
||||
cat > issues/features/search-feature.md << 'EOF'
|
||||
---
|
||||
title: Implement advanced search functionality
|
||||
status: ready
|
||||
labels:
|
||||
- enhancement
|
||||
- search
|
||||
assignees:
|
||||
- developer1
|
||||
milestone: v2.0
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
We need to add advanced search capabilities to improve user experience.
|
||||
|
||||
## Requirements
|
||||
|
||||
- [ ] Support fuzzy search matching
|
||||
- [ ] Allow filtering by multiple criteria
|
||||
- [ ] Add search history feature
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
- Consider using Elasticsearch
|
||||
- Should be optimized for performance
|
||||
EOF
|
||||
```
|
||||
|
||||
2. Create the GitHub issue:
|
||||
|
||||
```bash
|
||||
gh-issue-generator --repo myuser/myrepo issues/features/search-feature.md
|
||||
```
|
||||
|
||||
### Example 2: Converting from Jira and Batch Creating
|
||||
|
||||
1. Convert Jira issues to GitHub format:
|
||||
|
||||
```bash
|
||||
cd ../00-jira-to-gh-issues
|
||||
./target/release/jira-to-gh-issues --input sprint-tickets.csv --output ../issues
|
||||
cd ..
|
||||
```
|
||||
|
||||
2. Create all issues at once:
|
||||
|
||||
```bash
|
||||
cd 01-gh-issue-generator
|
||||
./target/release/gh-issue-generator --repo myuser/myrepo ../issues/20240405123045/batch.md
|
||||
```
|
||||
|
||||
## Markdown Format
|
||||
|
||||
Each Markdown file should have YAML front matter at the beginning of the file, followed by the issue description.
|
||||
|
||||
The front matter must be enclosed between `---` lines and contain at least a `title` field.
|
||||
|
||||
### Front Matter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `title` | Yes | Issue title |
|
||||
| `status` | No | Issue status: "draft" or "ready" (default: "ready") |
|
||||
| `labels` | No | Array of labels to apply to the issue |
|
||||
| `assignees` | No | Array of GitHub usernames to assign the issue to |
|
||||
| `milestone` | No | Milestone to add the issue to |
|
||||
| `project` | No | GitHub project to add the issue to |
|
||||
| `parent` | No | Issue number or URL of a parent issue |
|
||||
|
||||
### Issue Body
|
||||
|
||||
The content after the front matter becomes the issue body. It can contain any Markdown formatting, including:
|
||||
- Task lists
|
||||
- Code blocks
|
||||
- Images
|
||||
- Links
|
||||
- Tables
|
||||
- etc.
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Add support for OAuth2 authentication
|
||||
status: ready
|
||||
labels:
|
||||
- enhancement
|
||||
- security
|
||||
assignees:
|
||||
- octocat
|
||||
milestone: v1.0
|
||||
project: Project Board
|
||||
parent: 42
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
We need to add support for OAuth2 authentication to improve security.
|
||||
|
||||
## Tasks
|
||||
|
||||
- [ ] Research OAuth2 providers
|
||||
- [ ] Implement OAuth2 flow
|
||||
- [ ] Add tests
|
||||
- [ ] Update documentation
|
||||
|
||||
## Additional Context
|
||||
|
||||
This is needed for compliance with our security requirements.
|
||||
```
|
||||
|
||||
### Draft Issues
|
||||
|
||||
Issues marked with `status: draft` will not be created in GitHub. They will be reported as skipped in the summary.
|
||||
|
||||
## Batch Files
|
||||
|
||||
The tool also supports processing multiple issues from a single file. This is useful for creating related issues in a single operation.
|
||||
|
||||
### Batch File Format
|
||||
|
||||
Batch files should:
|
||||
1. Start with any introductory content (optional)
|
||||
2. Use the delimiter `---ISSUE---` to separate individual issues
|
||||
3. Each issue section must include its own YAML front matter and body
|
||||
|
||||
### Example Batch File
|
||||
|
||||
```markdown
|
||||
# Sprint Planning Issues
|
||||
|
||||
This file contains all issues for the upcoming sprint.
|
||||
|
||||
---ISSUE---
|
||||
|
||||
---
|
||||
title: Implement login feature
|
||||
status: ready
|
||||
labels:
|
||||
- feature
|
||||
---
|
||||
|
||||
## Description
|
||||
Add user login functionality...
|
||||
|
||||
---ISSUE---
|
||||
|
||||
---
|
||||
title: Update homepage design
|
||||
status: ready
|
||||
labels:
|
||||
- ui
|
||||
---
|
||||
|
||||
## Description
|
||||
Refresh the homepage design...
|
||||
|
||||
---ISSUE---
|
||||
|
||||
---
|
||||
title: Database migration planning
|
||||
status: draft
|
||||
---
|
||||
|
||||
## Description
|
||||
Plan the database migration...
|
||||
```
|
||||
|
||||
### Processing Batch Files
|
||||
|
||||
Process a batch file the same way as a regular file:
|
||||
|
||||
```bash
|
||||
gh-issue-generator --repo myuser/myrepo sprint-planning.md
|
||||
```
|
||||
|
||||
The tool will create each non-draft issue as a separate GitHub issue.
|
||||
|
||||
## Report Generation
|
||||
|
||||
After processing all input files, the tool creates a timestamped report directory in `report/YYYY-MM-DD-HH-MM/`. The report contains:
|
||||
|
||||
1. A summary.md file with details of all processed issues
|
||||
2. Copies of all processed Markdown files
|
||||
- Files for successfully created issues will have a comment with the issue URL
|
||||
- Files for failed issues will have a comment with the error message
|
||||
|
||||
## Parent-Child Relationship
|
||||
|
||||
If an issue specifies a `parent` field, the tool will add a comment to the created issue linking it to the parent issue. The parent can be specified as:
|
||||
- A GitHub issue number (e.g., `42`)
|
||||
- A full GitHub issue URL (e.g., `https://github.com/owner/repo/issues/42`)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### GitHub CLI Authentication Issues
|
||||
|
||||
If you encounter authentication issues:
|
||||
```bash
|
||||
# Check your GitHub CLI authentication status
|
||||
gh auth status
|
||||
|
||||
# Re-authenticate if needed
|
||||
gh auth login
|
||||
```
|
||||
|
||||
### Permission Issues
|
||||
|
||||
Ensure your GitHub user has permission to create issues in the target repository.
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
If you're creating many issues, you might hit GitHub's API rate limits. The tool doesn't currently implement rate limit handling, so you might need to wait before running again.
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Possible Solution |
|
||||
|-------|------------------|
|
||||
| `No such file or directory` | Check the file paths you're providing |
|
||||
| `Failed to parse YAML front matter` | Ensure your YAML is properly formatted |
|
||||
| `failed to fetch resource: ...` | Check your network connection and GitHub authentication |
|
||||
| `Repository not found` | Verify the repository exists and you have access to it |
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use `--dry-run` to test your issue files before creating actual issues
|
||||
- Organize your issue files in a logical directory structure
|
||||
- Use consistent naming conventions for your issue files
|
||||
- Include detailed information in your issue descriptions to minimize follow-up questions
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## AI-Assisted Issue Generation
|
||||
|
||||
You can use agentic assistants like Claude Projects or Cursor IDE to help generate issue markdown files. Here are template prompts you can use:
|
||||
|
||||
### Prompt for Generating a Single Issue
|
||||
|
||||
```
|
||||
Create a GitHub issue markdown file with YAML front matter for the following project feature:
|
||||
|
||||
Feature description: [your feature description]
|
||||
Key requirements:
|
||||
- [requirement 1]
|
||||
- [requirement 2]
|
||||
|
||||
The issue should include:
|
||||
- A clear title
|
||||
- Appropriate labels (choose from: bug, enhancement, documentation, feature, refactor)
|
||||
- Detailed description
|
||||
- Acceptance criteria
|
||||
- Any technical considerations
|
||||
```
|
||||
|
||||
### Prompt for Generating a Batch of Related Issues
|
||||
|
||||
```
|
||||
Create a batch file containing GitHub issues for a sprint focused on [feature area].
|
||||
|
||||
Include 3-5 related issues that would be needed to implement this feature area.
|
||||
Each issue should have appropriate front matter with title, labels, etc.
|
||||
Make sure the issues are properly separated with the ---ISSUE--- delimiter.
|
||||
|
||||
The issues should cover different aspects like:
|
||||
- Initial implementation
|
||||
- UI/UX improvements
|
||||
- Testing
|
||||
- Documentation
|
||||
```
|
||||
Reference in New Issue
Block a user