/jira-issue-to-pr

name: jira-issue-to-pr
description: >
  This skill should be used when the user asks to "set up a Jira automation to create pull requests",
  "poll Jira for create-pr issues", "automatically create GitHub PRs from Jira tickets",
  "deploy a Jira issue-to-PR automation", "create a Jira to GitHub PR workflow",
  "set up the Jira issue to GitLab MR automation", "set up the Jira issue to Bitbucket PR automation",
  "open GitLab merge requests from Jira tickets", "open Bitbucket pull requests from Jira tickets",
  or mentions automating pull request or merge request creation from a Jira label.
  Deploys a cron-based OpenHands automation that watches a Jira Cloud project for issues
  labeled with a configurable label (default: "create-pr") and spawns an agent conversation
  that opens a pull request on GitHub (the default), a merge request on GitLab, or a pull
  request on Bitbucket for each new issue found, chosen with git_provider. The target
  repository is read from the body of the Jira ticket - no repo parameter is required at deploy time.

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:

  OPENHANDS_HOST="<HOST value>"
  AUTH_HEADER="Authorization: Bearer $OPENHANDS_API_KEY"

• **Local Agent Canvas** - no `<HOST>` value:

  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 i