tix

Tix

A CLI tool for creating tickets and branches in Git repositories, with support for both GitHub and GitLab.

Features

• Create tickets in GitHub or GitLab
• Automatically create and checkout branches
• Create draft merge requests/pull requests
• Generate AI-powered descriptions for merge requests and issues
• Mark issues as ready/not ready with configurable labels and status
• Cross-repository issue linking with project-prefixed branch names
• Start branches from existing issues across repositories
• Support for issue-only repositories (no code directory required)
• Support for Git worktrees
• Interactive repository selection
• Auto-detect repository based on current directory
• Configurable default labels and milestone generation
• GitLab issue status updates via GraphQL
• Granular logging levels (WARN/INFO/DEBUG)
• YAML configuration

Installation

go install github.com/tedkulp/tix@latest

Configuration

Create a configuration file at ~/.tix.yml with the following structure:

# Global defaults
ready_label: "ready for review"
ready_status: "in_progress"    # GitLab only
unready_label: "needs-work"    # Optional: label to add when marking as unready
unready_status: "opened"       # GitLab only

repositories:
  - name: my-project
    github_repo: username/repo
    directory: ~/src/my-project
    default_labels: bug,enhancement
    default_branch: main
    ready_label: "needs-review"      # Override global default
    unready_label: "work-needed"     # Override global default
  - name: another-project
    gitlab_repo: group/project
    directory: ~/src/another-project
    default_labels: feature
    ready_label: "review-ready"
    ready_status: "ready"            # GitLab issue status
    unready_label: "blocked"
    unready_status: "opened"         # GitLab issue status
    worktree:
      enabled: true
      default_branch: main
  - name: issues
    gitlab_repo: group/issues
    # No directory - this is an issue-only repository
    default_labels: planning

Configuration Options

Global Options

• ready_label: Default label to add when marking issues as ready (default: "ready")
• ready_status: Default status to set for GitLab issues when marking as ready (GitLab only)
• unready_label: Default label to add when marking issues as unready (optional)
• unready_status: Default status to set for GitLab issues when marking as unready (GitLab only)

Repository Options

• name: Unique name for the repository
• github_repo: GitHub repository in format "owner/repo" (GitHub only)
• gitlab_repo: GitLab repository in format "group/project" (GitLab only)
• directory: Local directory path for the repository (optional - omit for issue-only repositories)
• default_labels: Comma-separated list of labels to add to new issues
• default_branch: Default branch name (default: "main")
• ready_label: Repository-specific ready label (overrides global)
• ready_status: Repository-specific ready status for GitLab (overrides global)
• unready_label: Repository-specific unready label (overrides global)
• unready_status: Repository-specific unready status for GitLab (overrides global)
• worktree.enabled: Enable Git worktree support
• worktree.default_branch: Default branch for worktrees

GitLab Status Updates

When using GitLab repositories, the ready_status and unready_status configurations allow you to automatically update issue status when marking issues as ready or unready. This uses GitLab's GraphQL API to set the issue state. Standard status values include:

• opened (default)
• closed

Note: GitLab also supports custom issue status values if configured in your project settings.

For GitHub repositories, status updates are silently ignored since GitHub doesn't support issue status fields.

Environment Variables

• GITHUB_TOKEN: GitHub API token (required for GitHub repositories)
• GITLAB_TOKEN: GitLab API token (required for GitLab repositories)
• OPENAI_API_KEY: OpenAI API key (required for AI-powered descriptions)

Usage

Create a new ticket and branch

# Create a new ticket interactively
tix create

# Create a new ticket with a specific title
tix create --title "Add new feature"

# Create a new ticket and assign it to yourself
tix create --self-assign

# Create a ticket in a specific issue repository and branch in a code repository
tix create issues my-project

Start a branch from an existing issue

# Start a branch from an issue in the current repository
tix start 123

# Start a branch from an issue in another repository
tix start issues 456

# Interactive mode - prompts for repository and issue number
tix start

The start command creates a new branch based on an existing issue. When the issue is from a different repository than where the branch is created, the branch name will include the project prefix (e.g., issues-456-feature-name). This allows merge requests to properly reference issues across repositories.

Create a merge request/pull request

# Create a merge request/pull request for the current branch
tix mr

# Create a draft merge request/pull request
tix mr --draft

# Use a specific remote (default is 'origin')
tix mr --remote upstream

Mark issues as ready/not ready

# Mark an issue as ready using configured label and status
tix ready

# Mark an issue as not ready (removes the ready label)
tix unready

# Mark as unready and add an unready label
tix unready --unready-label "needs-work"

# Mark as unready and set status
tix unready --status "opened"

# Override the ready label to remove
tix unready --label "review-ready"

# Full unready operation with all options
tix unready --label "ready" --unready-label "blocked" --status "opened"

# Override the default ready label for ready command
tix ready --label "needs-review"

# Override the default ready status (GitLab only)
tix ready --status "ready"

# Override both label and status for ready command
tix ready --label "review-ready" --status "in_progress"

Generate descriptions with AI

# Generate and update descriptions for the current merge request and issue
tix setdesc

# Only update the issue description
tix setdesc --only-issue

# Only update the merge/pull request description
tix setdesc --only-mr

# Force RAG (Retrieval-Augmented Generation) approach for large diffs
tix setdesc --use-rag

# Force direct approach (bypass RAG even for large diffs)
tix setdesc --use-rag=false

The setdesc command uses AI to generate descriptions for merge requests and issues. For large diffs (>50,000 characters), it automatically uses a RAG (Retrieval-Augmented Generation) approach with embeddings to handle content that exceeds the model's context window. The --use-rag flag allows you to override this behavior for testing purposes.

Show version information

# Display version information
tix version

Options

Global options that can be used with any command:

# Default logging level (WARN) - only shows warnings and errors
tix command

# Enable INFO level logging
tix -v command

# Enable DEBUG level logging
tix -vv command

# Use a specific config file
tix --config /path/to/config.yml command

License

MIT

Releasing

This project uses GoReleaser to handle releases. To release a new version:

1. Create and push a new tag with the version (e.g., v0.1.0):

   git tag -a v0.1.0 -m "Release v0.1.0"
   git push origin v0.1.0
   

2. The GitHub Actions workflow will automatically build and release the binaries to GitHub Releases.

Homebrew

Releases are automatically published to the tedkulp/homebrew-tap repository. To install via Homebrew:

brew tap tedkulp/tap
brew install tix

Manual Release

If you need to create a release manually:

1. Install GoReleaser: brew install goreleaser/tap/goreleaser
2. Set your GitHub token: export GITHUB_TOKEN=your_token
3. Run GoReleaser: goreleaser release --clean

For local testing, you can run: goreleaser release --snapshot --clean