Git Jira Helper (gjh)

A CLI tool that automates Git workflows with Jira integration and AI-powered commit messages.

Features

• 🎫 Smart Ticket Selection: Browse and select your Jira tickets directly from the command line
• 🌿 Automated Branch Creation: Create feature branches with standardized naming conventions
• 🤖 AI-Powered Commits: Generate meaningful commit messages using OpenAI
• 📋 Smart PR Descriptions: Auto-generate comprehensive pull request descriptions
• 🔐 Secure Configuration: Encrypted credential storage in your home directory

Installation

Global Installation (Recommended)

npm install -g git-jira-helper

Local Development

git clone <repository-url>
cd git-jira-helper
npm install
npm link

Note: This package uses CommonJS-compatible versions of dependencies:

• chalk@4 (for colored output)
• inquirer@8 (for interactive prompts)
• ora@5 (for loading spinners)

Quick Start

1. Initial Setup

Run the interactive setup wizard to configure your credentials:

gjh init

This will prompt you for:

• Jira instance URL (e.g., https://company.atlassian.net)
• Jira email address
• Jira API token (How to create one)
• OpenAI API key (Get yours here)
• Branch naming preferences
• Commit message style preferences

2. Start Working on a Ticket

gjh start

This command will:

• Fetch your "To Do" tickets from Jira
• Let you select a ticket to work on
• Switch to main/master and pull latest changes
• Create a new feature branch with the format: feature/TICKET-123-description

3. Make Smart Commits

After making your code changes:

gjh commit

This command will:

• Analyze your staged changes
• Generate an AI-powered commit message using ticket context and code diff
• Let you review, edit, or regenerate the message
• Create the commit

4. Push and Create PR

When you're ready to push your changes:

gjh push

This command will:

• Push your branch to origin
• Fetch full ticket details from Jira
• Analyze all commits on your branch
• Generate a comprehensive PR description with AI
• Provide options to copy description or save to file

Workflow Example

# One-time setup
gjh init

# Start working on a ticket
gjh start
# → Select "PROJ-123: Add user authentication"
# → Creates branch: feature/PROJ-123-add-user-authentication

# Make your code changes
# ... edit files ...

# Commit with AI-generated message
gjh commit
# → Analyzes changes and ticket context
# → Suggests: "feat(auth): implement user login with JWT tokens"

# Push and generate PR description
gjh push
# → Pushes branch to origin
# → Generates comprehensive PR description
# → Copies to clipboard or saves to file

Commands

gjh init

Interactive setup wizard to configure Jira and OpenAI credentials.

What it does:

• Validates Git repository
• Tests Jira connection and fetches projects
• Tests OpenAI API connection
• Saves encrypted configuration to ~/.gjh-config.json

gjh start

Select a Jira ticket and create a new Git branch.

What it does:

• Fetches your "To Do" tickets from Jira
• Shows interactive ticket selection
• Switches to main/master branch
• Pulls latest changes
• Creates feature branch with naming convention

Branch naming format:

• feature/TICKET-123-description
• bugfix/TICKET-123-description
• task/TICKET-123-description
• Custom prefix (configurable)

gjh commit

Analyze code changes and generate smart commit messages with AI.

What it does:

• Checks for staged/unstaged changes
• Stages files if needed
• Generates git diff
• Extracts ticket context from branch name
• Uses OpenAI to generate conventional commit message
• Allows review and editing before committing

Commit message styles:

• Conventional Commits: feat(scope): description
• Simple: Add new feature

gjh push

Push branch and generate PR description from ticket + code changes.

What it does:

• Pushes branch to origin (with upstream if needed)
• Fetches full Jira ticket details
• Analyzes all commits on the branch
• Generates comprehensive diff from main/master
• Creates AI-powered PR description
• Provides options to copy, save, or view instructions

Configuration

Configuration is stored in ~/.gjh-config.json with encrypted credentials.

Manual Configuration Reset

To reset your configuration:

rm ~/.gjh-config.json
gjh init

Configuration Structure

{
  "jira": {
    "url": "https://company.atlassian.net",
    "email": "user@company.com",
    "apiToken": "encrypted_token"
  },
  "openai": {
    "apiKey": "encrypted_key"
  },
  "preferences": {
    "branchPrefix": "feature",
    "commitStyle": "conventional"
  }
}

Requirements

• Node.js: Version 16.0.0 or higher
• Git: Installed and configured
• Jira: Access to Jira instance with API token
• OpenAI: API key with access to GPT models

Security

• All credentials are encrypted using AES encryption
• Configuration file is stored in your home directory
• API keys are never logged or exposed in error messages
• Network requests use HTTPS only

Troubleshooting

Common Issues

"Not configured" error:

gjh init

Jira connection failed:

• Verify your Jira URL format: https://company.atlassian.net
• Check your API token is valid and not expired
• Ensure your email matches your Jira account

OpenAI API errors:

• Verify your API key is valid
• Check your OpenAI account has available credits
• Ensure API key has proper permissions

Git repository errors:

• Run commands inside a Git repository
• Ensure you have proper Git configuration (user.name, user.email)

Branch creation fails:

• Check if branch already exists
• Ensure you have uncommitted changes handled
• Verify main/master branch exists

Debug Mode

For detailed error information, check the error messages provided by each command. The tool provides specific error contexts to help diagnose issues.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Report issues: GitHub Issues
• Feature requests: GitHub Discussions

Happy coding! 🚀