Skip to main content

​
Overview

OpenHands offers several integrations, including GitHub, GitLab, Bitbucket, and Slack, with more to come. Some integrations, like Slack, are only available in OpenHands Cloud. Configuration may also vary depending on whether you’re using OpenHands Cloud or running OpenHands on your own.

​
OpenHands Cloud Integrations Settings

​
GitHub Settings

​
Slack Settings

  • Install OpenHands Slack App - Install the OpenHands Slack app in your Slack workspace. Make sure your Slack workspace admin/owner has installed the OpenHands Slack app first.

​
Running on Your Own Integrations Settings

​
Version Control Integrations

​
GitHub Setup

OpenHands automatically exports a GITHUB_TOKEN to the shell environment if provided:
  1. Generate a Personal Access Token (PAT):
  • On GitHub, go to Settings > Developer Settings > Personal Access Tokens.
  • Tokens (classic)
    • Required scopes:
      • repo (Full control of private repositories)
  • Fine-grained tokens
    • All Repositories (You can select specific repositories, but this will impact what returns in repo search)
    • Minimal Permissions (Select Meta Data = Read-only read for search, Pull Requests = Read and Write and Content = Read and Write for branch creation)
  1. Enter token in OpenHands:
  • Navigate to the Settings > Integrations page.
  • Paste your token in the GitHub Token field.
  • Click Save Changes to apply the changes.
If you’re working with organizational repositories, additional setup may be required:
  1. Check organization requirements:
  • Organization admins may enforce specific token policies.
  • Some organizations require tokens to be created with SSO enabled.
  • Review your organization’s token policy settings.
  1. Verify organization access:
  • Go to your token settings on GitHub.
  • Look for the organization under Organization access.
  • If required, click Enable SSO next to your organization.
  • Complete the SSO authorization process.
  • Token Not Recognized:
    • Check that the token hasn’t expired.
    • Verify the token has the required scopes.
    • Try regenerating the token.
  • Organization Access Denied:
    • Check if SSO is required but not enabled.
    • Verify organization membership.
    • Contact organization admin if token policies are blocking access.

​
GitLab Setup

OpenHands automatically exports a GITLAB_TOKEN to the shell environment if provided:
  1. Generate a Personal Access Token (PAT):
  • On GitLab, go to User Settings > Access Tokens.
  • Create a new token with the following scopes:
    • api (API access)
    • read_user (Read user information)
    • read_repository (Read repository)
    • write_repository (Write repository)
  • Set an expiration date or leave it blank for a non-expiring token.
  1. Enter token in OpenHands:
  • Navigate to the Settings > Integrations page.
  • Paste your token in the GitLab Token field.
  • Click Save Changes to apply the changes.
  1. (Optional): Restrict agent permissions
  • Create another PAT using Step 1 and exclude api scope .
  • In the Settings > Secrets page, create a new secret GITLAB_TOKEN and paste your lower scope token.
  • OpenHands will use the higher scope token, and the agent will use the lower scope token.
  • Token Not Recognized:
    • Check that the token hasn’t expired.
    • Verify the token has the required scopes.
  • Access Denied:
    • Verify project access permissions.
    • Check if the token has the necessary scopes.
    • For group/organization repositories, ensure you have proper access.

​
BitBucket Setup

  1. Generate an App password:
    • On Bitbucket, go to Account Settings > App Password.
    • Create a new password with the following scopes:
      • account: read
      • repository: write
      • pull requests: write
      • issues: write
    • App passwords are non-expiring token. OpenHands will migrate to using API tokens in the future.
  2. Enter token in OpenHands:
  • Navigate to the Settings > Integrations page.
  • Paste your token in the BitBucket Token field.
  • Click Save Changes to apply the changes.
  • Token Not Recognized:
    • Check that the token hasn’t expired.
    • Verify the token has the required scopes.