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