jira-autofix
Automates resolving Jira issues — from reading the ticket to opening a pull request with the fix
Open source Open in the app JSON README (API)
About
Automates resolving Jira issues — from reading the ticket to opening a pull request with the fix
Details
- Kind
- Plugins
- Topic
- Productivity
- Publisher
- weitzer-org
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Forks
- 1
- Open pull requests
- 2
- Last push
- 2026-02-10T18:15:59Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
weitzer-org/jira-autofix-extension
README
# Jira Autofix Extension for Gemini CLI
An extension for [Gemini CLI](https://github.com/google-gemini/gemini-cli) that automates the workflow of resolving Jira issues — from reading the ticket to opening a pull request with the fix.
## Overview
The Jira Autofix extension provides a single command (`/jira-autofix`) that orchestrates the full lifecycle of fixing a Jira issue: fetching context from Jira, cloning the relevant repo, planning a fix, implementing it, reviewing the code, opening a PR on GitHub, and posting the result back to Jira.
---
## Prerequisites
- [Gemini CLI](https://github.com/google-gemini/gemini-cli) v0.4.0 or newer
- [Docker](https://docs.docker.com/get-docker/) (for the GitHub MCP server)
- [Node.js](https://nodejs.org/) v18+ and npm (optional, for development)
- A **GitHub Personal Access Token** with `repo` scope — [create one here](https://github.com/settings/tokens)
- A **Jira API Token** — [create one here](https://id.atlassian.com/manage-profile/security/api-tokens)
### How to generate a Jira API Token
1. Log in to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Click **Create API token**.
3. Give it a label (e.g., "Gemini CLI").
4. Copy the token to your clipboard—you will need it for the installation prompt.
## Installing Gemini CLI
If you don't have Gemini CLI installed yet:
```bash
# Install via npm (requires Node.js 18+)
npm install -g @anthropic-ai/gemini-cli
# Or install via the official installer
curl -fsSL https://cli.gemini.google.dev/install.sh | bash
```
Verify the installation:
```bash
gemini --version
```
For detailed instructions, see the [Gemini CLI Getting Started guide](https://github.com/google-gemini/gemini-cli#getting-started).
## Installing This Extension
### Installing This Extension
You have two options:
1. **Production / Cloud Shell Usage** (Designated for seamless use with Docker)
2. **Local Development** (For advanced users iterating on the extension code)
#### Option 1: Production / Cloud Shell (Recommended)
Run this command to install the extension directly from GitHub:
```bash
gemini extensions install https://github.com/weitzer-org/jira-autofix-extension
```
During installation you will be prompted for:
| Prompt | What to enter |
|---|---|
| **GitHub Personal Access Token** | A PAT with `repo` scope. |
| **Jira URL** | Your Jira instance URL (e.g., `https://myorg.atlassian.net`). |
| **Jira Email** | The email address you use to log in to Jira. |
| **Jira API Token** | A Jira API token. Create one at [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens). |
##### Important: Shell Environment Setup (Required for Cloning External Repos)
If your workflow involves cloning repositories (not using the current directory), you must also export the GitHub PAT to your shell environment. This is a one-time setup:
```bash
# Add to your shell profile (run once)
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="your-pat-here"' >> ~/.bashrc
source ~/.bashrc
```
> **Why?** The PAT entered during installation is only available to the MCP servers (Docker containers). For git commands like `clone` and `push`, the PAT must also be in the shell environment.
**For Cloud Shell users**: Run the above commands, replacing `your-pat-here` with your actual PAT.
#### Option 2: Local Development (Advanced)
If you are developing the extension locally and want to use your local Python environment (bypassing Docker), follow these steps:
1. Clone the repo:
```bash
git clone https://github.com/weitzer-org/jira-autofix-extension
cd jira-autofix-extension
```
2. Create a `.env` file (optional, to save typing credentials):
```bash
JIRA_URL=https://your-domain.atlassian.net
JIRA_EMAIL=user@example.com
JIRA_API_TOKEN=your-token
GITHUB_PERSONAL_ACCESS_TOKEN=your-pat
```
3. Run the setup script:
```bash
./setup_local_native.sh
```
This script will set up a virtual environment, install dependencies, and configure the extension to run natively on your machine using the local code.
### Step 3: Verify the extension is installed
```bash
gemini extensions list
```
You should see `jira-autofix` in the list.
### Debug Mode
If you encounter issues or want to see exactly what the extension is doing, you can run it with the `--debug` flag:
```bash
gemini run jira-autofix "<JIRA-URL> --debug"
```
This will print detailed logs (prefixed with `🐛 [DEBUG]:`) before every tool execution.
### Optional: Enhanced Security & Code Review
For improved security scanning and code review, you can install the official Gemini CLI extensions:
```bash
# Security extension (finds vulnerabilities, dependency scans)
gemini extensions install https://github.com/gemini-cli-extensions/security
# Code review extension (reviews code quality)
gemini extensions install https://github.com/gemini-cli-extensions/code-review
```
If installed, `/jira-autofix` will automatically use these extensions during the review phase. If not installed, it falls back to built-in review.
### Managing the extension
```bash
# Update to the latest version
gemini extensions update jira-autofix
# Uninstall
gemini extensions uninstall jira-autofix
```
## Usage
### Basic Usage
**Important**: You must use `gemini run` to execute this command.
```bash
gemini run jira-autofix "<ISSUE_KEY_OR_URL>"
```
Example:
```bash
gemini run jira-autofix "SCRUM-1"
```
### From inside a repository
The extension is smart! If you run it from inside the relevant git repository, it will detect the context and ask if you want to use the current directory instead of cloning a fresh copy.
```bash
cd ~/projects/my-service
gemini run jira-autofix "PROJ-1234"
```
If you're **not** inside the repo, the extension will ask you for the GitHub repo URL and clone it automatically.
### With Debug Mode
To see verbose logs, append the `--debug` flag **inside the quotes**:
```bash
gemini run jira-autofix "SCRUM-1 --debug"
```
> [!TIP]
> **Cloud Shell Users**: If you see an authentication error like `Cannot create property 'refresh_token'`, run this command to refresh your Cloud Shell credentials:
> ```bash
> gcloud auth application-default login
> ```
### Interactive Mode
Alternatively, start the interactive shell:
```bash
gemini
> /jira-autofix SCRUM-1 --debug
```
## What Happens
When you run `/jira-autofix`, the extension walks through these steps:
| Step | What happens | Your input needed |
|---|---|---|
| 1. Fetch Jira context | Reads the issue, related issues, and comments from Jira | None |
| 2. Set up repository | Detects or clones the GitHub repo | Repo URL (if not detected) |
| 3. Plan the fix | Analyzes the codebase and presents a fix plan | Approve or revise the plan |
| 4. Implement the fix | Makes code changes and runs tests | None (reviews results) |
| 5. Review changes | Runs security and code quality review on the diff | Address critical findings (if any) |
| 6. Open pull request | Creates a branch, commits, pushes, and opens a PR | None |
| 7. Update Jira | Posts a comment on the Jira issue with the PR link | None |
### Developer Checkpoints
The extension pauses for your input at two key points:
1. **Plan approval** (Step 3) — You must approve the plan before any code is written. You can provide feedback to revise it.
2. **Critical findings** (Step 5) — If the security review finds CRITICAL issues, the extension stops and asks how you want to proceed.
## Configuration
### Extension Settings
Settings are managed via Gemini CLI:
```bash
# View current settings
gemini extensions list
# Update a setting
gemini extensions config jira-autofix "GitHub Personal Access Token"
# Update for a specific workspace
gemini extensions config jira-autofix "GitHub Personal Access Token" --scope workspace
# Update Jira settings
gemini extensions config jira-autofix "Jira URL"
gemini extensions config jira-autofix "Jira Email"
gemini extensions config jira-autofix "Jira API Token"
```
> [!WARNING]
> The **GitHub Personal Access Token** and **Jira API Token** are stored in plain text in your configuration file. Ensure this file is not shared.
### GitHub Token Scopes
The minimum required scope for your GitHub PAT is `repo`. This grants:
- Read access to repository contents
- Write access to create branches, push commits, and open PRs
### Atlassian Auth
The Atlassian MCP server uses **API Tokens** for authentication. This eliminates the need for interactive OAuth flows. Your credentials are securely passed to the Docker container via environment variables.
To connect to a different Atlassian tenant, simply update the extension configuration using `gemini extensions config`.
## Development
To develop this extension locally:
```bash
git clone https://github.com/weitzer-org/jira-autofix-extension
cd jira-autofix-extension
gemini extensions link .
```
Changes to `GEMINI.md`, `gemini-extension.json`, and `commands/jira-autofix.toml` are reflected immediately — no reinstall needed.
## File Structure
```
jira-autofix-extension/
├── gemini-extension.json # Extension manifest (MCP servers, settings)
├── GEMINI.md # Model context loaded every session
├── README.md # This file
└── commands/
└── jira-autofix.toml # Main command prompt
```
---
## Workflow Details
### Step 1: Fetch Jira Issue Context
The extension uses the **Atlassian MCP server** to:
- Retrieve the issue summary, description, acceptance criteria, and comments
- Fetch linked/related issues (parent epics, blockers, subtasks) for additional context
- Identify relevant labels, components, and priority
### Step 2: Set Up Repository
The developer specifies the GitHub repository associated with the issue:
- If already inside the repo, the extension detects it and confirms
- Otherwise, the developer provides the repo URL
- The extension clones the repo and checks out the default branch
### Step 3: Plan the Fix
The Gemini model:
- Analyzes the Jira issue context alongside the codebase
- Produces a structured plan detailing which files to change, what logic to add/modify, and why
- Presents the plan to the developer for review
- The developer **approves** the plan or **provides feedback** to revise it
### Step 4: Implement the Fix
After plan approval, the Gemini model:
- Makes the code changes described in the approved plan
- Runs any available test suites to validate the fix
- Reports results back to the developer
### Step 5: Review Changes
The extension performs inline analysis of the diff to:
- Scan for security vulnerabilities (injection, secrets, weak crypto, etc.)
- Review code changes for bugs, performance issues, and maintainability
- Present findings classified as CRITICAL, HIGH, MEDIUM, or LOW
- Critical findings block progression until the developer responds
### Step 6: Open Pull Request
Using the **GitHub MCP server**, the extension:
- Creates a feature branch (e.g., `fix/PROJ-1234-short-description`)
- Commits all changes with a descriptive message referencing the Jira ticket
- Pushes the branch and opens a pull request with a structured body
### Step 7: Update Jira
Using the **Atlassian MCP server**, the extension posts a comment on the Jira issue with:
- A summary of what was fixed
- A link to the GitHub pull request
- The security and code review status
---
## Sequence Diagram
```
Developer Gemini CLI Jira MCP GitHub MCP
│ │ │ │
│ /jira-autofix │ │ │
│ + ticket URL │ │ │
│─────────────────>│ │ │
│ │ get issue details │ │
│ │───────────────────>│ │
│ │ issue context │ │
│ │<───────────────────│ │
│ provide repo │ │ │
│─────────────────>│ │ │
│ │ clone repo (shell)│ │
│ │──────────┐ │ │
│ │<─────────┘ │ │
│ review plan │ │ │
│<─────────────────│ │ │
│ approve/revise │ │ │
│─────────────────>│ │ │
│ │ implement fix │ │
│ │──────────┐ │ │
│ │<─────────┘ │ │
│ │ security + review │ │
│ │──────────┐ │ │
│ │<─────────┘ │ │
│ review results │ │ │
│<─────────────────│ │ │
│ │ create branch+PR │ │
│ │──────────────────────────────────────>│
│ │ PR link │ │
│ │<──────────────────────────────────────│
│ │ post comment │ │
│ │───────────────────>│ │
│ │ confirmed │ │
│ │<───────────────────│ │
│ done + PR link │ │ │
│<─────────────────│ │ │
```
---
## Design Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Jira MCP server | Docker `ghcr.io/sooperset/mcp-atlassian` | Supports API token auth, no hang on startup |
| GitHub MCP server | Official (`github/github-mcp-server`) via Docker | Maintained by GitHub, broadest tool support |
| Jira auth | API Token (env vars) | Configuration-based, non-interactive |
| GitHub auth | PAT via extension settings (`sensitive: false`) | Stored in extension config (plain text) |
| Repo handling | Detect local repo or clone | Avoids unnecessary cloning |
| Test execution | Auto-detect and run | Reports results but does not block |
| Security/Code review | Extensions if installed, else built-in | Uses `/security:analyze` and `/code-review` if available |
| Branch naming | `fix/<issue-key>-<description>` | Consistent convention for all issue types |
| Jira updates | Comment only | Less risky than status transitions |
| PR reviewers | Not auto-assigned | Left to the developer |
| Failure handling | Pause and present | Developer decides how to proceed |
| Issue types | All types supported | Workflow is the same regardless |
## License
Apache-2.0