jira-issue-to-pr

Files (8)

• .claude-plugin
• .codex-plugin
• plugin.json · .plugin/
• README.md
• SKILL.md
• setup.md · references/
• main.py · scripts/
• setup_webhook.py · scripts/

SKILL.md (first lines)

# Jira → Pull Request Automation (GitHub, GitLab, Bitbucket)

Deploys a cron automation that polls a Jira Cloud instance for open issues carrying a
configurable label and, for each new issue, starts an OpenHands agent conversation that
clones the repository specified in the ticket body on the configured git provider (GitHub
by default, GitLab or Bitbucket with `git_provider`), creates a branch, implements or
placeholders the requested change, and opens a pull request (a merge request on GitLab).
Once the conversation
starts, it also posts a comment on the Jira ticket: "I'm on it: <conversation URL>".

## How It Works

1. **Poll** - every N minutes, search the Jira Cloud instance for open issues with the
   configured label: through the user's connected Atlassian Rovo MCP server on OpenHands
   Cloud and Enterprise, or with `POST /rest/api/3/search/jql` and an API token.
2. **Deduplicate** - on the very first run the script records a `first_run_at` baseline
   timestamp in the KV store; any issue whose `updated` timestamp predates that baseline
   is skipped (no backfill blast on first deploy). Using `updated` rather than `created`
   means an old issue that has its label added after the automation is deployed will still
   be picked up. Subsequent runs filter by both `first_run_at` and a KV-backed set of
   already-processed issue keys. A `max_new_per_run` cap (default 5) limits conversations
   started per cron firing as additional defense-in-depth.
3. **Dispatch** - for each new issue, start an independent agent conversation with a
   PR-creation prompt: `POST /api/conversations` on the agent server when running locally,
   or `POST /api/v1/app-conversations` on OpenHands Cloud. The prompt instructs the agent
   to extract the target repository (`owner/repo` on GitHub; `group/project` or a URL on GitLab;
   `workspace/repo` on Bitbucket) from the ticket body.
4. **Comment** - immediately after the conversation is created, post a Jira comment on the
   issue: `I'm on it: <conversation URL>`.
5. **Persist** - record the processed issue key so re-runs never duplicate work.

The polling run is lightweight (stdlib only, no SDK install); LLM costs are incurred only
when new issues are actually found.

## Prerequisites

Before deploying, ensure the following are in place:

| Requirement | Details |
|---|---|
| **Jira access** | OpenHands Cloud and Enterprise: the user's connected Atlassian Rovo MCP server, with no API token. Local, or without that connection: a Jira API token stored as an OpenHands secret (see [Jira API token setup](#jira-api-token)) |
| **Git provider access** | OpenHands Cloud and Enterprise: the user's connected GitHub, GitLab or Bitbucket integration, whichever `git_provider` names. A connected MCP server also works - GitHub's (with the saved access token), GitLab's, or Atlassian Rovo for Bitbucket - with a private repository read through the tools rather than cloned. Local: a token for that provider stored as an OpenHands secret (`GITHUB_TOKEN` with `repo` + `workflow`, `GITLAB_TOKEN` with `api`, `BITBUCKET_TOKEN`) so the spawned conversation can push branches and open the request |
| **KV store** (OpenHands Cloud only) | The automation service must have its KV store enabled (`kvStore` in `GET /api/automation/v1/capabilities`); each cloud run starts in a fresh sandbox, so processed issues are remembered there |
| **Jira label** | The label to watch for (default: `create-pr`) must exist in the Jira project |
| **Target repository** | Must exist on the configured provider; the connected integration or token must have write access |

## Deploying the Automation

### Determine the API host and auth

Set `OPENHANDS_HOST` and `AUTH_HEADER` for the curl commands below:

- **OpenHands Cloud** - a `<HOST>` value is present in the system prompt:
  ```bash
  OPENHANDS_HOST="<HOST value>"
  AUTH_HEADER="Authorization: Bearer $OPENHANDS_API_KEY"
  ```
- **Local Agent Canvas** - no `<HOST>` value:
  ```bash
  OPENHANDS_HOST="http://localhost:8000"
  AUTH_HEADER="X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"
  ```

### Step 1 - Collect parameters

First decide how the poller reaches Jira:

- **Connected Atlassian Rovo MCP server** - on OpenHands Cloud and Enterprise, when the
  user has connected it. OpenHands calls Jira for the poller through that connection, so
  do not ask for a Jira email or an API token and do not create a secret.
- **Jira API token** - on a local Agent Canvas, or when the Rovo server is not connected.

Then pick `git_provider` from the automation the user asked for: `github` for *Jira issue to
GitHub PR* (the default, so it can be left out), `gitlab` for *Jira issue to GitLab MR*,
`bitbucket` for *Jira issue to Bitbucket PR*. It changes only what the conversation is told;
the conversation pushes with the user's connected integration for that provider, or delivers
through the connected MCP server's tools when it has no token.

Then gather the parameters for that route, plus the shared ones, before proceeding:

| Parameter | Example | Notes |
|---|---|---|
| `jira_mcp_server` | `atlassian-rovo` | Rovo connection only. The name the server is stored under: the key in `agent_settings.mcp_config` of `GET ${OPENHANDS_HOST}/api/v1/settings` whose `url` is on `mcp.atlassian.com`. Look it up; do not ask the user |
| `jira_cloud_id` | `1324a887-45db-1bf4-1e99-ef0ff456d421` | Rovo connection only. The `id` of the Jira site, from the Rovo tool `getAccessibleAtlassianResources`. Ask which site only when it lists several |
| `jira_base_url` | `https://acme.atlassian.net` | API token only. No trailing slash |
| `jira_email` | `alice@acme.com` | API token only. Atlassian account email for Basic auth |
| `jira_token_secret` | `JIRA_CLOUD_KEY` | API token only. Name of the OpenHands secret holding the API token |
| `jira_label` | `create-pr` | Label to watch for (optional, defaults to `create-pr`) |
| `git_provider` | `gitlab` | `github` (default), `gitlab` or `bitbucket` - the provider the ticket names its repository on (optional) |
| `max_new_per_run` | `5` | Max conversations dispatched per cron firing (optional, defaults to `5`) |
| `cron_schedule` | `*/5 * * * *` | Polling frequency in cron syntax |

> **Note**: The repository is not configured here. Each Jira ticket body must name it:
> `owner/repo` on GitHub, `group/subgroup/project` or a full URL on GitLab (self-managed
> hosts included), `workspace/repo` on bitbucket.org. The spawned agent extracts it from
> the ticket text.

### Step 2 - Create config.json

Create `config.json` next to `scripts/main.py` when packaging. With the connected
Atlassian Rovo MCP server:

```json
{
  "jira_mcp_server": "atlassian-rovo",
  "jira_cloud_id":   "1324a887-45db-1bf4-1e99-ef0ff456d421",
  "jira_label":      "create-pr",
  "max_new_per_run": 5
}
```

With a Jira API token:

```json
{
  "jira_base_url":     "https://acme.atlassian.net",
  "jira_email":        "alice@acme.com",
  "jira_token_secret": "JIRA_CLOUD_KEY",
  "jira_label":        "create-pr",

From OpenHands/extensions, MIT.

More from OpenHands/extensions