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:

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

shCopy
gh extension upgrade sherpa

Remove

To remove this extension just run:

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

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

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

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

Preview without side effects:

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