jps-jira-workspace-utils

Utilities for automating Jira-related workspace and branch management tasks.
Includes CLI tools for creating Jira workspaces and Git branches that follow team conventions.

---

🧩 Installation

pip install jps-jira-workspace-utils

or install in editable mode for local development:

git clone git@github.com:jai-python3/jps-jira-workspace-utils.git  
cd jps-jira-workspace-utils  
pip install -e .

---

1. 🧩 create-jira-workspace

This utility initializes a Jira workspace with a standardized directory structure and a seeded README.md file.

1.1. Usage

create-jira-workspace --jira-id JPS-123 --project carrier-var

1.2. Options

Option	Description	Default
--jira-id	Jira issue key (e.g., JPS-123)	(required)
--project	Project or codebase name	(required)
--path	Base path where workspace will be created	Current directory
--open	Open workspace in VSCode after creation	False

1.3. Example

create-jira-workspace --jira-id JPS-123 --project carrier-var --open

This creates a directory like:

~/jira/JPS-123-carrier-var/

and seeds it with:

README.md  

---

2. 🧩 create-git-branch-for-jira-issue

This utility automates creating Git branches that follow the Jira naming convention.

2.1. Usage

create-git-branch-for-jira-issue --jira-id JPS-123 --codebase carrier-var --branch-type feature

2.2. Options

Option	Description	Default
--jira-id	Jira issue key (e.g., JPS-123)	(required)
--codebase	Codebase name (e.g., carrier-var)	(required)
--source-branch	Source branch to base from	development
--branch-type	Branch type (feature, bugfix, hotfix)	feature

2.3. Example

create-git-branch-for-jira-issue --jira-id JPS-321 --codebase carrier-var --branch-type bugfix

This creates a new branch named:

bugfix/JPS-321-carrier-var

If a ~/.jira.env file exists, it will automatically load Jira-related environment variables (such as JIRA_USER and JIRA_TOKEN).
If no .jira.env is found, it will rely on environment variables already defined in your shell.

⚙️ Required Configuration File (~/.my_git_jira.conf)

The create-git-branch-for-jira-issue utility uses an optional configuration file to locate Git repositories by their short codebase identifiers.

📄 Location

~/.my_git_jira.conf

🧩 Purpose

This configuration maps human-readable codebase names (like project1) to their full Git repository URLs.
It allows you to specify a short --codebase name on the command line instead of typing a long Azure DevOps URL each time.

When a --codebase is provided, the utility looks up its corresponding URL from this configuration, navigates to the local clone (if it exists), and creates the new branch from the appropriate source branch.

---

🧾 Example Configuration

[codebases]
project1 = git@ssh.dev.azure.com:v3/org1/Org1/project1
project2 = git@ssh.dev.azure.com:v3/org1/Org1/project2

---

🧠 Notes

• The [codebases] section is required; each key represents a codebase short name.
• Values must be valid SSH URLs to Azure DevOps or GitHub repositories.
• The CLI uses this mapping to locate the right Git repository automatically.

---

✅ Example Workflow

create-git-branch-for-jira-issue --jira-id JPS-987 --codebase project1 --branch-type feature

This command will:

1️⃣ Read ~/.my_git_jira.conf
2️⃣ Find the SSH URL for project1
3️⃣ Verify or locate the local Git repository
4️⃣ Checkout the source branch (e.g., development)
5️⃣ Create and switch to:

feature/JPS-987-project1

---

🧪 Development and Testing

Install dependencies for linting, formatting, and testing:

pip install -e '.[dev]'

Run all lint and test checks:

make lint  
make test

---

🧾 License

MIT License
© 2025 Jaideep Sundaram