> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations Settings

> How to setup and modify the various integrations in OpenHands.

## 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](/openhands/usage/cloud/openhands-cloud) or
[running OpenHands on your own](/openhands/usage/run-openhands/local-setup).

## OpenHands Cloud Integrations Settings

<Note>
  These settings are only available in [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud).
</Note>

### GitHub Settings

* `Configure GitHub Repositories` - Allows you to
  [modify GitHub repository access](/openhands/usage/cloud/github-installation#modifying-repository-access) for OpenHands.

### Slack Settings

* `Install OpenHands Slack App` - Install [the OpenHands Slack app](/openhands/usage/cloud/slack-installation) in
  your Slack workspace. Make sure your Slack workspace admin/owner has installed the OpenHands Slack app first.

## Running on Your Own Integrations Settings

<Note>
  These settings are only available in [OpenHands Local GUI](/openhands/usage/run-openhands/local-setup).
</Note>

### Version Control Integrations

#### GitHub Setup

OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if provided:

<AccordionGroup>
  <Accordion title="Setting Up a GitHub Token">
    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)

    2. **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](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization).

    2. **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.
  </Accordion>

  <Accordion title="Troubleshooting">
    * **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.
  </Accordion>
</AccordionGroup>

#### GitLab Setup

OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if provided:

<AccordionGroup>
  <Accordion title="Setting Up a GitLab Token">
    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.

    2. **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.

    3. **(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.
  </Accordion>

  <Accordion title="Troubleshooting">
    * **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.
  </Accordion>
</AccordionGroup>

#### BitBucket Setup

<AccordionGroup>
  <Accordion title="Setting Up a Bitbucket Password">
    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.
  </Accordion>

  <Accordion title="Troubleshooting">
    * **Token Not Recognized**:
      * Check that the token hasn't expired.
      * Verify the token has the required scopes.
  </Accordion>
</AccordionGroup>