2ticketss/01-gh-issue-generator/README.md

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 installed and authenticated
• Rust installed (cargo, rustc)

Installation

Option 1: Build from source

1. Clone this repository

git clone https://github.com/bee8333/2ticketss.git
cd 2ticketss/01-gh-issue-generator

2. Build the application:

cargo build --release

3. The executable will be in target/release/gh-issue-generator

4. Optional: Add to your PATH

# 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:

cargo install --path .

GitHub CLI Authentication

Before using this tool, you must authenticate the GitHub CLI:

# 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

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:

   # 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:

# 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

# 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:

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:

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:

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:

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:

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

---
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

# 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:

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:

# 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