Sherpa extension for GitHub CLI

Sherpa for GitHub CLI makes it easy for you to create branches and pull requests associated with any GitHub or Jira issue.

This extension retrieves the type of issue (User Story, Bug, Technical Improvement, etc) and creates a branch or pull request associated with that issue, following the contribution model you define in a configuration file.

Table of contents

• Prerequisites
• Installation
• Configuration
• Usage
• AI-assisted development
• Contribute

Prerequisites

• An available GitHub account.
• GitHub CLI (version 2.0.0 or higher) configured and authenticated in your development environment.
• Bash: Supports Linux, MacOS and Windows (for the latter, we recommend using WSL2).

Installation

Make sure you meet the prerequisites first.

You can install this extension just running this command from your terminal:

gh extension install InditexTech/gh-sherpa

Upgrade

If you have already installed this extension and you want to upgrade it, so, you should run this command from your terminal:

gh extension upgrade sherpa

Remove

To remove this extension just run:

gh extension remove sherpa

Configuration

Sherpa uses different issue types (feature, bugfix, hotfix, refactoring, etc) when mapping an issue with its corresponding branch prefix.

Default configuration

By default, it will use the internal/config/default-config.yml configuration file to perform these mappings.

Custom configuration

Otherwise, if you wish customize the different issue types, branch prefixes, etc, so, you can create your own configuration file located in $HOME/.config/sherpa/config.yml from the default config file.

If you are using Jira as issue tracker, so, the first time you run a command it will ask you to configure Jira credentials and then proceed to create the custom configuration file with the provided Jira credentials.

Usage

After installing this extension in your development environment, you can know the available commands in the USAGE.md file.

AI-assisted development

Sherpa is designed to be fully driven by AI coding agents without requiring any interactive terminal input.

All branch naming decisions and PR metadata can be specified via CLI flags — no stdin prompts are needed when using -y/--yes together with the new flags.

Typical AI agent workflow

Create a branch for an issue with a known type:

gh sherpa create-branch --issue 42 --yes \
  --branch-type feature \
  --branch-description "implement-oauth"
# Output: feature/GH-42-implement-oauth

Create a fully configured draft PR in one command:

gh sherpa create-pr --issue 42 --yes \
  --branch-type feature \
  --branch-description "implement-oauth" \
  --pr-title "feat(auth): implement OAuth2 login" \
  --pr-body "Closes #42\n\nImplements OAuth2 login flow." \
  --reviewer alice \
  --assignee bob \
  --label "priority/high"

Get machine-readable output for chaining with other tools:

BRANCH=$(gh sherpa create-branch --issue 42 --yes --branch-type bugfix --output json | jq -r .branch)

Preview without side effects:

gh sherpa create-pr --issue 42 --yes --branch-type feature --dry-run

When a branch already exists for the issue, Sherpa automatically reuses it in non-interactive mode (-y). To opt out of this behavior and force an error instead, use --no-use-existing-branch.

Contribute

Before developing any new feature or fix, please, check the CONTRIBUTING.md file. You will find there the steps to contribute along with development and testing guidelines.

Security

If you find a security vulnerability in this project, please, check the SECURITY.md file to know how to report it.