Jira Cloud Integration

Complete guide for setting up Jira Cloud integration with OpenHands Cloud, including service account creation, API token generation, webhook configuration, and workspace integration setup.

Jira Cloud Integration

Overview

The Jira Cloud integration enables you to use OpenHands to automatically implement requirements from Jira tickets. When you create a ticket with clear requirements and acceptance criteria, OpenHands can read the ticket, generate an implementation plan, and create a pull request in your linked repository.

How It Works

Once configured, you can request OpenHands to work on a Jira ticket by:

1. Specify the Repository: Include the repository location in either:
   • The ticket body itself, or
   • A comment on the ticket
2. Trigger OpenHands: Activate the agent using one of these methods:
   • Add an openhands label to the ticket
   • Comment with: @openhands please review these requirements, generate a plan, and then proceed with implementation

OpenHands will then read the ticket, understand the requirements, and generate a conversation that results in a pull request implementing the requested changes.

Example Ticket

Here’s an example of how to structure a Jira ticket for OpenHands:

Title: Add SAML Support

Body:

As an administrator for my web app, I want to configure SAML so I can provide secure access to my system.

Repository: AcmeCo/WebApp

AC:
- Verify an administrator can configure SAML settings
- Verify an end user can authenticate via SAML

After creating this ticket, you can either add the openhands label or comment with @openhands please review these requirements, generate a plan, and then proceed with implementation to start the automation process.

---

Platform Configuration

Step 1: Create Service Account

1. Navigate to User Management

   • Go to Atlassian Admin
   • Select your organization
   • Go to Directory > Users

2. Create OpenHands Service Account

   • Click Service accounts
   • Click Create a service account
   • Name: OpenHands Agent
   • Click Next
   • Select User role for Jira app
   • Click Create

Step 2: Generate API Token

1. Access Service Account Configuration
   • Locate the created service account from above step and click on it
   • Click Create API token
   • Set the expiry to 365 days (maximum allowed value)
   • Click Next
   • In Select token scopes screen, filter by following values
     • App: Jira
     • Scope type: Classic
     • Scope actions: Write, Read
   • Select read:me, read:jira-work, and write:jira-work scopes
   • Click Next
   • Review and create API token
   • Important: Copy and securely store the token immediately

Step 3: Configure Webhook

1. Navigate to Webhook Settings

   • Go to Jira Settings > System > WebHooks
   • Click Create a WebHook

2. Configure Webhook

   • Name: OpenHands Cloud Integration
   • Status: Enabled
   • URL: https://app.all-hands.dev/integration/jira/events
   • Issue related events: Select the following:
     • Issue updated
     • Comment created
   • JQL Filter: Leave empty (or customize as needed)
   • Click Create
   • Important: Copy and store the webhook secret securely (you’ll need this for workspace integration)

---

Workspace Integration

Step 1: Log in to OpenHands Cloud

1. Navigate and Authenticate
   • Go to OpenHands Cloud
   • Sign in with your Git provider (GitHub, GitLab, or BitBucket)
   • Important: Make sure you’re signing in with the same Git provider account that contains the repositories you want the OpenHands agent to work on.

Step 2: Configure Jira Integration

1. Access Integration Settings

   • Navigate to Settings > Integrations
   • Locate Jira Cloud section

2. Configure Workspace

   • Click Configure button
   • Enter your workspace name and click Connect
   • Important: Make sure you enter the full workspace name, eg: yourcompany.atlassian.net
     • If no integration exists, you’ll be prompted to enter additional credentials required for the workspace integration:
       • Webhook Secret: The webhook secret from Step 3 above
       • Service Account Email: The service account email from Step 1 above
       • Service Account API Key: The API token from Step 2 above
       • Ensure Active toggle is enabled

Workspace name is the host name when accessing a resource in Jira Cloud.

Eg: https://all-hands.atlassian.net/browse/OH-55

Here the workspace name is all-hands.

3. Complete OAuth Flow
   • You’ll be redirected to Jira Cloud to complete OAuth verification
   • Grant the necessary permissions to verify your workspace access.
   • If successful, you will be redirected back to the Integrations settings in the OpenHands Cloud UI

Managing Your Integration

Edit Configuration:

• Click the Edit button next to your configured platform
• Update any necessary credentials or settings
• Click Update to apply changes
• You will need to repeat the OAuth flow as before
• Important: Only the original user who created the integration can see the edit view

Unlink Workspace:

• In the edit view, click Unlink next to the workspace name
• This will deactivate your workspace link
• Important: If the original user who configured the integration chooses to unlink their integration, any users currently linked to that workspace integration will also be unlinked, and the workspace integration will be deactivated. The integration can only be reactivated by the original user.

Screenshots

Workspace link flow

Workspace Configure flow

Edit view as a user

Edit view as the workspace creator