Jira Issue To PR

Jira → GitHub PR Automation

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 GitHub repository specified in the ticket body, creates a branch, implements or placeholders the requested change, and opens a pull request. 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, POST /rest/api/3/search/jql on the Jira Cloud instance to find open issues with the configured label.
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 GitHub repository (owner/repo) 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:

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

Gather the following from the user before proceeding:

Note: The GitHub repository is not configured here. Each Jira ticket body must include a reference to the target GitHub repo in owner/repo format (e.g. acme-org/backend). The spawned agent extracts it from the ticket text.

Step 2 - Create config.json

Create config.json next to scripts/main.py when packaging:

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

Step 3 - Package the tarball

Copy scripts/main.py from this skill and package it with the config.json:

WORK=$(mktemp -d)
cp <skill-dir>/scripts/main.py "$WORK/main.py"
# write config.json into $WORK/config.json (see Step 2)
tar -czf /tmp/jira-issue-to-pr.tar.gz -C "$WORK" .
python3 -m py_compile "$WORK/main.py"   # validate syntax before uploading

Step 4 - Upload the tarball

TARBALL_PATH=$(curl -s -X POST \
  "${OPENHANDS_HOST}/api/automation/v1/uploads?name=jira-issue-to-pr" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/gzip" \
  --data-binary @/tmp/jira-issue-to-pr.tar.gz \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['tarball_path'])")

Step 5 - Create the automation

curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Jira issue-to-PR Poller\",
    \"trigger\": {
      \"type\":     \"cron\",
      \"schedule\": \"*/5 * * * *\",
      \"timezone\": \"UTC\"
    },
    \"tarball_path\": \"$TARBALL_PATH\",
    \"entrypoint\":   \"python3 main.py\",
    \"timeout\":      540
  }" | python3 -m json.tool

Save the returned id - use it for updates and monitoring.

Step 6 - Verify with a test dispatch

curl -s -X POST \
  "${OPENHANDS_HOST}/api/automation/v1/<AUTOMATION_ID>/dispatch" \
  -H "$AUTH_HEADER" | python3 -m json.tool

# After ~30 seconds, check the run status:
curl -s "${OPENHANDS_HOST}/api/automation/v1/<AUTOMATION_ID>/runs?limit=1" \
  -H "$AUTH_HEADER" \
  | python3 -c "import sys,json; r=json.load(sys.stdin)['runs'][0]; print(r['status'], r.get('error_detail'))"

Event-Based Alternative

Where Jira can reach the deployment over the internet (OpenHands Cloud and Enterprise), Jira can push label events instead of being polled. That is a different automation from the poller above: a prompt automation triggered by a Jira webhook, created with the openhands-automation skill (see its "Custom Webhook Example: Jira Cloud"). scripts/main.py is not used, so its KV-backed deduplication and its "I'm on it" comment do not apply; the prompt has to ask for whatever of that is wanted.

Set up the webhook

The webhook is a pair: a custom webhook source in OpenHands and an admin webhook in Jira, sharing a signing secret. scripts/setup_webhook.py creates both, so the user does not have to open Jira or copy a URL and secret by hand. It needs the API token of an account with the Administer Jira permission, stored as an OpenHands secret.

1. Collect the Jira site URL, the account email, the name of the secret holding that account's API token, and the label. A token used only for this step (for example JIRA_ADMIN_TOKEN) can be deleted from the user's secrets afterwards.

2. Dry run, then ask. Registering a webhook changes the user's Jira site, so show what will be created and wait for the user to confirm:

   OPENHANDS_API_KEY="$OPENHANDS_API_KEY" python3 <skill-dir>/scripts/setup_webhook.py apply --dry-run \
     --jira-base-url "https://acme.atlassian.net" --jira-email "alice@acme.com" \
     --jira-token-env JIRA_ADMIN_TOKEN --openhands-host "$OPENHANDS_HOST" --label create-pr

   The command has to name the secret (--jira-token-env JIRA_ADMIN_TOKEN): naming it is what makes its value available to the command.

3. Apply - the same command without --dry-run. It registers the OpenHands webhook (source jira, webhookEvent, X-Hub-Signature), creates the Jira webhook for Issue created and Issue updated limited to labels = "create-pr", and sends one signed test request. "signed_delivery_check": "ok" in its output means the pair works. Running it again updates the Jira webhook in place and keeps the secret, so a failure half way cannot break a working pair. Add --rotate-secret when the two sides have drifted apart, for instance after the deployment was reinstalled.

   The secret is generated inside the script and is never printed. Do not ask the user for it, and do not try to read or echo it.

4. If it exits with code 3, the account is not a Jira administrator. Fall back to Manual webhook setup.

To stop Jira sending events, for example when the automation is deleted, run the same command with delete in place of apply.

Create the event-triggered automation

Create the automation with this trigger:

{
  "type": "event",
  "source": "jira",
  "on": ["jira:issue_created", "jira:issue_updated"],
  "filter": "contains(issue.fields.labels, 'create-pr') && (webhookEvent == 'jira:issue_created' || length(changelog.items[?field == 'labels'] || `[]`) > `0`)"
}

Jira sends labels as plain strings, so the filter reads issue.fields.labels, not issue.fields.labels[].name. The changelog check limits updates to those that change the labels; without it every later edit of a labelled issue starts another run. It still fires when another label is added to or removed from an issue that carries the label, so have the prompt skip an issue that already has a pull request.

To verify, add the label to an issue and check the automation's runs.