Gong

<div align="center"> <img src="assets/logo.svg" width="300" alt="Gong Logo" /> <p><strong>A command-line tool for seamless Git and issue tracker integration</strong></p>

</div>

---

Table of Contents

• Overview
• Quick Start
• Installation
• Commands
  • gong login
  • gong create (NEW)
  • gong start
  • gong browse
  • gong comment
  • gong install-hooks (NEW)
• Complete Workflows
• Configuration
• Development
• Changelog

---

Overview

Gong is a CLI tool that bridges the gap between issue trackers and Git workflows. Stay in your terminal and maintain your development flow while working with Jira and other project management tools.

Key Features:

• 🎯 Create issues interactively with a minimal TUI - no browser needed
• 🌿 Auto-create Git branches with proper naming conventions (feature/PROJ-123-issue-title)
• 🔗 Auto-link commits to issues with intelligent git hook installation
• 🚀 Transition issues to "started" state automatically
• 💬 Comment on issues via stdin pipes (perfect for sending diffs or file contents)
• 🌐 Browse issues in your default browser from the command line
• ✏️ Multi-line descriptions using your preferred editor

Quick Start

# 1. Install gong
go install github.com/KensoDev/gong/cmd/gong@latest

# 2. Login to your JIRA instance
gong login jira

# 3. Create a new issue interactively
gong create OPS
# - Select issue type (Bug, Story, Task, etc.)
# - Enter summary
# - Add description (opens your editor)
# - Branch created automatically!

# 4. All your commits will now include the JIRA ticket link!
git commit -m "Implement new feature"
# Result: "Implement new feature\n\n[OPS-123](https://your-jira.com/browse/OPS-123)"

Installation

Pre-built Binaries

Download the latest release from GitHub Releases for your platform:

• macOS (Darwin)
• Linux
• Windows (community tested)

Place the binary in your PATH and make it executable:

# Example for macOS/Linux
chmod +x gong
sudo mv gong /usr/local/bin/

From Source

go install github.com/KensoDev/gong/cmd/gong@latest

Using Homebrew (macOS/Linux)

# Coming soon
brew install gong

Supported Issue Trackers

| Tracker | Status | Notes | |---------|--------|-------| | Jira | ✅ Full support | Username/password or API token |

Want to add support for another tracker? Contributions are welcome! The codebase uses a generic Client interface that makes adding new trackers straightforward.

Commands

gong login - Authenticate with JIRA

Before using gong, you need to authenticate with your JIRA instance.

gong login jira

You'll be prompted for:

• Username: Your JIRA username or email
• Domain: Your JIRA instance (e.g., yourcompany.atlassian.net)
• Password: Your password or API token (recommended)
• Project Prefix: Default project key prefix (optional)
• Transitions: Comma-separated list of allowed issue transitions (e.g., In Progress,Started)

Using API Tokens (Recommended):

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Create a new API token
3. Use the token as your password when logging in

gong start - Start Working on Existing Issue

Start working on an existing JIRA issue.

gong start <ISSUE-ID> [--type <branch-type>]

Examples:

# Start working on a story/task (default: feature)
gong start PROJ-123

# Start working on a bug
gong start PROJ-456 --type bugfix

# Start working with custom branch type
gong start PROJ-789 --type hotfix

What it does:

1. Fetches the issue title from JIRA
2. Creates a branch: {type}/{issue-id}-{slugified-title}
3. Transitions the issue to "started" state (based on your configured transitions)
4. Checks out the new branch
5. Prompts to install git hooks (first time only)

Example:

gong start OPS-123 --type feature
# Creates branch: feature/OPS-123-implement-user-authentication
# Transitions OPS-123 to "In Progress"
# Checks out the branch

Flags:

• --type: Branch type prefix (default: feature)
  • Common types: feature, bugfix, hotfix, chore, docs
  • Or set GONG_DEFAULT_BRANCH_TYPE environment variable

gong browse - Open Issue in Browser

Opens the current issue in your default browser.

gong browse

What it does:

• Extracts the JIRA ticket ID from your current branch name
• Opens the issue in your default browser

Example:

# On branch: feature/OPS-123-new-feature
gong browse
# Opens: https://your-jira.atlassian.net/browse/OPS-123

gong comment - Add Comments via Pipe

Add comments to the current issue by piping content through stdin.

<command> | gong comment

Why a pipe? This design allows you to send any output directly to JIRA comments:

• Git diffs
• File contents
• Command outputs
• Vim buffers
• Test results

Examples:

# Send a simple message
echo "Fixed the authentication bug" | gong comment

# Send git diff
git diff | gong comment

# Send file contents
cat error.log | gong comment

# Send test results
npm test | gong comment

# From vim: select lines and run
:'<,'>!gong comment

What it does:

• Extracts ticket ID from current branch name
• Posts the piped content as a comment to the JIRA issue
• Preserves formatting (great for code snippets and logs)

](https://asciinema.org/a/d0rcjavbv55lbq1xpsrqiyyu6)

gong install-hooks - Auto-Link Commits to Issues ✨ NEW

Automatically install git hooks that add JIRA ticket links to every commit.

gong install-hooks

What it does:

• Installs prepare-commit-msg hook in .git/hooks/
• Automatically extracts ticket ID from branch name
• Adds JIRA link to every commit message
• Smart installation: Appends to existing hooks instead of replacing them

Automatic Installation: When you run gong create or gong start for the first time in a repo, you'll be prompted:

Git hook not installed. Install prepare-commit-msg hook to auto-add ticket IDs to commits? (y/n)

Example:

# On branch: feature/OPS-123-new-feature
git commit -m "Implement authentication"

# Commit message becomes:
# Implement authentication
#
# [OPS-123](https://your-jira.atlassian.net/browse/OPS-123)

Manual Installation (Alternative):

curl https://raw.githubusercontent.com/KensoDev/gong/main/git-hooks/prepare-commit-msg > .git/hooks/prepare-commit-msg
chmod +x .git/hooks/prepare-commit-msg

Note: If you already have a prepare-commit-msg hook, gong will append its logic to preserve your existing hooks.

gong prepare-commit-message

This command is used internally by the git hook. You typically don't need to run it directly.

It extracts the JIRA ticket ID from your branch name and formats it as a markdown link.

gong create - Create Issues Interactively ✨ NEW

Create JIRA issues directly from your terminal with an interactive TUI.

gong create <PROJECT-KEY>

Example:

gong create OPS

Interactive Workflow:

1. Select Issue Type: Choose from Bug, Story, Task, Epic, etc.
2. Enter Summary: One-line title for the issue
3. Add Description: Press Enter to open your editor ($EDITOR or vim) for multi-line descriptions
4. Issue Created: JIRA issue created automatically
5. Branch Created: Git branch created and checked out with format {type}/{ISSUE-ID}-{slugified-title}
6. Git Hook Installed: On first use, prompts to install commit hooks for auto-linking

Branch Type Mapping:

• Bug/Defect → bugfix/
• Story/Task/Feature → feature/
• Epic → epic/
• Improvement/Enhancement → enhancement/
• Sub-task → task/

Example Output:

Select issue type
▸ Task
  Story
  Bug
  Epic

Summary: Implement user authentication
Description (optional, press Enter to skip): [Opens editor]

Creating issue...
✓ Created issue: OPS-123
✓ Created and checked out branch: feature/OPS-123-implement-user-authentication
Success! Now working on branch: feature/OPS-123-implement-user-authentication

Environment Variables:

• GONG_DEFAULT_BRANCH_TYPE: Override branch type (e.g., export GONG_DEFAULT_BRANCH_TYPE=custom)
• EDITOR: Set your preferred editor for descriptions (default: vim)

---

Complete Workflows

Workflow 1: Create New Issue from Scratch

# Create issue interactively
gong create OPS
# 1. Select issue type (Bug, Story, Task...)
# 2. Enter summary
# 3. Add description (opens editor)
# 4. Issue created: OPS-456
# 5. Branch created: feature/OPS-456-your-issue-title
# 6. Git hook installed (prompts on first use)

# Make