​
Project Management Tool Integrations

​
Overview

OpenHands Cloud integrates with project management platforms (Jira Cloud, Jira Data Center, and Linear) to enable AI-powered task delegation. Users can invoke the OpenHands agent by:
  • Adding @openhands in ticket comments
  • Adding the openhands label to tickets

​
Prerequisites

Integration requires two levels of setup:
  1. Platform Configuration - Administrative setup of service accounts and webhooks on your project management platform (see individual platform documentation below)
  2. Workspace Integration - Self-service configuration through the OpenHands Cloud UI to link your OpenHands account to the target workspace

​
Platform-Specific Setup Guides:

​
Usage

Once both the platform configuration and workspace integration are completed, users can trigger the OpenHands agent within their project management platforms using two methods:

​
Method 1: Comment Mention

Add a comment to any issue with @openhands followed by your task description: 
@openhands Please implement the user authentication feature described in this ticket

​
Method 2: Label-based Delegation

Add the label openhands to any issue. The OpenHands agent will automatically process the issue based on its description and requirements.

​
Git Repository Detection

The OpenHands agent needs to identify which Git repository to work with when processing your issues. Here’s how to ensure proper repository detection:

​
Specifying the Target Repository

Required: Include the target Git repository in your issue description or comment to ensure the agent works with the correct codebase. Supported Repository Formats:
  • Full HTTPS URL: https://github.com/owner/repository.git
  • GitHub URL without .git: https://github.com/owner/repository
  • Owner/repository format: owner/repository

​
Platform-Specific Behavior

Linear Integration: When GitHub integration is enabled for your Linear workspace with issue sync activated, the target repository is automatically detected from the linked GitHub issue. Manual specification is not required in this configuration. Jira Integrations: Always include the repository information in your issue description or @openhands comment to ensure proper repository detection.

​
Troubleshooting

​
Platform Configuration Issues

  • Webhook not triggering: Verify the webhook URL is correct and the proper event types are selected (Comment, Issue updated)
  • API authentication failing: Check API key/token validity and ensure required scopes are granted. If your current API token is expired, make sure to update it in the respective integration settings
  • Permission errors: Ensure the service account has access to relevant projects/teams and appropriate permissions

​
Workspace Integration Issues

  • Workspace linking requests credentials: If there are no active workspace integrations for the workspace you specified, you need to configure it first. Contact your platform administrator that you want to integrate with (eg: Jira, Linear)
  • Integration not found: Verify the workspace name matches exactly and that platform configuration was completed first
  • OAuth flow fails: Make sure that you’re authorizing with the correct account with proper workspace access

​
General Issues

  • Agent not responding: Check webhook logs in your platform settings and verify service account status
  • Authentication errors: Verify Git provider permissions and OpenHands Cloud access
  • Agent fails to identify git repo: Ensure you’re signing in with the same Git provider account that contains the repositories you want OpenHands to work on
  • Partial functionality: Ensure both platform configuration and workspace integration are properly completed

​
Getting Help

For additional support, contact OpenHands Cloud support with:
  • Your integration platform (Linear, Jira Cloud, or Jira Data Center)
  • Workspace name
  • Error logs from webhook/integration attempts
  • Screenshots of configuration settings (without sensitive credentials)