Expand Jira integration docs with use case and examples #428
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,10 +1,49 @@ | ||||||
| --- | ||||||
| title: Jira Cloud Integration | ||||||
| description: 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. | ||||||
|
Check warning on line 10 in openhands/usage/cloud/project-management/jira-integration.mdx
|
||||||
|
|
||||||
| ### 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: | ||||||
|
Contributor
There was a problem hiding this comment. 🟢 Acceptable: The documentation says "either the ticket body itself, or a comment" which is clear enough. The implementation ( Might optionally clarify that both are searched together (not mutually exclusive), but not critical. |
||||||
| - 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` | ||||||
|
Contributor
There was a problem hiding this comment. 🟠 Important: This is misleading. The exact text after I verified in the source code ( Suggested fix:
Suggested change
Or provide a more accurate example like: But clarify that the text after There was a problem hiding this comment. I'm on it! all-hands-bot can track my progress at all-hands.dev |
||||||
|
|
||||||
| 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 | ||||||
|
|
@@ -19,7 +58,7 @@ | |||||
| - Click **Create a service account** | ||||||
| - Name: `OpenHands Agent` | ||||||
| - Click **Next** | ||||||
| - Select **User** role for Jira app | ||||||
| - Click **Create** | ||||||
|
|
||||||
| ### Step 2: Generate API Token | ||||||
|
|
@@ -30,7 +69,7 @@ | |||||
| - 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 | ||||||
|
|
@@ -41,7 +80,7 @@ | |||||
| ### Step 3: Configure Webhook | ||||||
|
|
||||||
| 1. **Navigate to Webhook Settings** | ||||||
| - Go to **Jira Settings** > **System** > **WebHooks** | ||||||
| - Click **Create a WebHook** | ||||||
|
|
||||||
| 2. **Configure Webhook** | ||||||
|
|
@@ -66,16 +105,16 @@ | |||||
| - 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 | ||||||
|
|
@@ -83,7 +122,7 @@ | |||||
| - Ensure **Active** toggle is enabled | ||||||
|
|
||||||
| <Note> | ||||||
| Workspace name is the host name when accessing a resource in Jira Cloud. | ||||||
|
|
||||||
| Eg: https://all-hands.atlassian.net/browse/OH-55 | ||||||
|
|
||||||
|
|
@@ -91,7 +130,7 @@ | |||||
| </Note> | ||||||
|
|
||||||
| 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 | ||||||
|
|
||||||
|
|
||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟠 Important: Same issue as jira-integration.mdx line 22. The exact text after
@openhandsdoesn't matter - any comment containing the mention will trigger OpenHands.See my comment on the other file for details and suggested fixes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm on it! all-hands-bot can track my progress at all-hands.dev