mirror of
https://github.com/OpenHands/OpenHands.git
synced 2025-12-26 05:48:36 +08:00
81 lines
4.4 KiB
Plaintext
81 lines
4.4 KiB
Plaintext
---
|
|
title: Project Management Tool Integrations
|
|
description: Overview of OpenHands Cloud integrations with project management platforms including Jira Cloud, Jira Data Center, and Linear. Learn about setup requirements, usage methods, and troubleshooting.
|
|
---
|
|
|
|
# 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:
|
|
- [Jira Cloud Integration](./jira-integration.md)
|
|
- [Jira Data Center Integration](./jira-dc-integration.md)
|
|
- [Linear Integration](./linear-integration.md)
|
|
|
|
## 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)
|