# Code host permissions

> Every permission and scope MergeHarbor requests from code hosts, sign-in providers and issue trackers, why it is needed, and how to revoke it.

MergeHarbor requests the smallest set of permissions that its features need. It reads code to review it, and writes only review comments, statuses, webhooks, pull request descriptions and approvals when you turn them on, and the fix pull requests and merges that people start from the console. This page lists every permission by provider.

## GitHub and GitHub Enterprise Server

MergeHarbor connects through a GitHub App. The App only sees the repositories you select when you install it.

| Permission                | Access         | Why MergeHarbor needs it                                                                                       | Feature                                      |
| ------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Contents                  | Read and write | Read: clone and index code to review it. Write: create `mergeharbor/fix-*` branches and merge from the console | Reviews, fix pull requests, merge            |
| Pull requests             | Read and write | Read pull requests and diffs; post reviews, replies and description updates; open fix pull requests            | Reviews, replies, fix pull requests          |
| Checks                    | Read and write | Report the MergeHarbor check run                                                                               | Status check, merge gating                   |
| Actions                   | Read           | Read the logs of failed GitHub Actions jobs on a pull request's head commit                                    | [CI](https://mergeharbor.com/docs/ci): GitHub Actions               |
| Commit statuses           | Read           | Find the failed builds other CI systems (CircleCI, Jenkins, Buildkite) report on a pull request's head commit  | [CI](https://mergeharbor.com/docs/ci): CircleCI, Jenkins, Buildkite |
| Issues                    | Read           | GitHub requires it to deliver comments from the pull request conversation                                      | `@mergeharbor` replies                       |
| Metadata                  | Read           | Required by GitHub for every App; lists repositories and collaborators                                         | Repository list, repository visibility       |
| Members (organization)    | Read           | Read organization teams and check that a linked GitHub account belongs to the organization                     | Team sync, GitHub account linking            |
| Email addresses (account) | Read           | Read your verified email when you sign in with GitHub                                                          | Sign-in                                      |

Webhook events: pull request, issue comment, pull request review comment, and push. GitHub always sends installation events.

**Actions** and **Commit statuses** were added for [CI connections](https://mergeharbor.com/docs/ci). GitHub asks the owner of each existing installation to approve them (**Settings → GitHub Apps → MergeHarbor → Review request**). Until they are approved, everything else keeps working and CI connections cannot read failed jobs. MergeHarbor never re-runs, cancels or changes workflows.

MergeHarbor never pushes to a pull request's own branch. It writes only `mergeharbor/fix-*` branches, and only when someone with the `pulls.fix` permission asks for a fix pull request. If you grant **Contents: Read** instead of write, everything except fix pull requests and merging from the console keeps working.

**Sign in with GitHub** through a separate OAuth App requests only the `user:email` scope. Your public profile needs no scope.

## GitLab and GitLab Self-Managed

| Scope | Access         | Why MergeHarbor needs it                                                                                                                  | Feature                                     |
| ----- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `api` | Read and write | Read projects, merge requests and code; post merge request discussions and commit statuses; register project webhooks; read group members | Reviews, status, webhooks, team sync, merge |

GitLab has no narrower scope that allows posting merge request comments or commit statuses. `read_api` is read-only, and `write_repository` covers only Git pushes. The token can still do only what its user or access token role allows, so use an access token with the **Developer** role rather than an administrator's token.

[GitLab CI](https://mergeharbor.com/docs/ci) reads pipelines and the logs of failed jobs with the same `api` scope; it needs no other permission.

Webhook events: merge request, comments, and push.

**Sign in with GitLab** requests `openid`, `profile` and `email`, which give MergeHarbor your identity only. It has no access to your projects.

## Bitbucket Cloud

Bitbucket sets permissions on the OAuth consumer, not per request.

| Permission    | Access         | Why MergeHarbor needs it                                                         | Feature                 |
| ------------- | -------------- | -------------------------------------------------------------------------------- | ----------------------- |
| Account       | Read           | Identify the connected account                                                   | Connection              |
| Repositories  | Write          | Read code; report build statuses. Bitbucket requires it for Pull requests: Write | Reviews, status         |
| Pull requests | Write          | Read pull requests; post comments; approve, merge and close from the console     | Reviews, replies, merge |
| Webhooks      | Read and write | Register webhooks on the repositories you enable                                 | Automatic reviews       |

With an access token instead of OAuth, use **Repositories: Read**, **Pull requests: Write** and **Webhooks: Read and write**.

## Bitbucket Data Center

A project or repository HTTP access token with **write** permission. Bitbucket Data Center has no finer permission for posting comments, approving pull requests and managing webhooks. Scope the token to one project or repository to limit what it can reach.

## Azure DevOps

| Scope                            | Access         | Why MergeHarbor needs it                                             | Feature                 |
| -------------------------------- | -------------- | -------------------------------------------------------------------- | ----------------------- |
| Code (`vso.code_write`)          | Read and write | Read code and pull requests; post threads and votes; merge and close | Reviews, replies, merge |
| Code status (`vso.code_status`)  | Read and write | Report the `mergeharbor/review` status                               | Status, branch policy   |
| Project and team (`vso.project`) | Read           | List projects and their repositories                                 | Repository list         |
| User profile (`vso.profile`)     | Read           | Identify the connected user and the organizations they belong to     | Connection              |
| `offline_access`                 | -              | Refresh the connection without signing in again                      | Connection              |

Personal access tokens need these scopes: **Code (Read & write)**, **Code (Status)**, **Service Hooks (Read & write)** and **Project and Team (Read)**.

## Gitea and Forgejo

| Scope              | Access | Why MergeHarbor needs it                                                         | Feature                |
| ------------------ | ------ | -------------------------------------------------------------------------------- | ---------------------- |
| `write:repository` | Write  | Read code and pull requests; post reviews and statuses; register webhooks; merge | Reviews, status, merge |
| `write:issue`      | Write  | Post replies in the pull request conversation                                    | Replies                |
| `read:user`        | Read   | Identify the token's user                                                        | Connection             |

## Sign-in providers

| Provider                         | Scopes                                           | Why                                                              |
| -------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
| GitHub (OAuth App)               | `user:email`                                     | Your verified primary email; your public profile needs no scope  |
| GitLab                           | `openid`, `profile`, `email`                     | Your identity and verified email                                 |
| Azure DevOps (Microsoft sign-in) | `openid`, `profile`, `email`                     | Your identity and verified email                                 |
| Bitbucket                        | `account`, `email`                               | Your identity and verified email                                 |
| Google                           | `openid`, `profile`, `email`                     | Your identity and verified email                                 |
| Your SSO (OIDC)                  | `openid` plus what your administrator configures | Your identity, and `offline_access` if sessions are re-validated |

Sign-in never gives MergeHarbor access to your repositories.

## Issue trackers and error monitoring

Integrations are read-only unless you turn on write-back. See [Jira](https://mergeharbor.com/docs/jira), [Linear](https://mergeharbor.com/docs/linear), [Sentry](https://mergeharbor.com/docs/sentry), [Notion](https://mergeharbor.com/docs/notion) and the other [context connectors](https://mergeharbor.com/docs/connectors) for details.

| Integration          | Read scopes                                                                                                              | Only with write-back     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
| Jira Cloud           | `read:jira-work`, `read:confluence-content.all`, `read:confluence-space.summary`, `search:confluence`, `offline_access`  | `write:jira-work`        |
| Linear               | `read`                                                                                                                   | `comments:create`        |
| Sentry               | `org:read`, `project:read`, `event:read` (token you create)                                                              | -                        |
| Notion               | **Read content** capability only, no user information; only the pages you share with the connection                      | -                        |
| ClickUp              | No scopes: the connecting person's own permissions; only linked tasks are read                                           | Comments on linked tasks |
| Trello               | API key and token that act as the connecting member; only linked cards are read                                          | Comments on linked cards |
| Figma                | `current_user:read`, `file_content:read`, `file_comments:read`, `file_dev_resources:read`                                | -                        |
| AWS CloudWatch Logs  | A role you create with `logs:FilterLogEvents` and `logs:DescribeLogGroups`, assumed with your organization's external ID | -                        |
| Google Cloud Logging | A service account with **Logs Viewer** (`roles/logging.viewer`); token scope `logging.read`                              | -                        |
| CircleCI, Jenkins    | A token that reads the jobs you can see (Jenkins: **Overall/Read** and **Job/Read**)                                     | -                        |
| Buildkite            | `read_builds`, `read_build_logs`                                                                                         | -                        |
| Zendesk              | An agent's API token; only linked tickets and open tickets with mapped tags are read                                     | -                        |
| Intercom             | Read conversations, read tags, read admins                                                                               | -                        |

## What MergeHarbor never requests

- Administration of repositories, organizations, groups or workspaces.
- Permission to change branch protection, repository settings, secrets, deploy keys or CI configuration.
- Access to repositories you have not selected (GitHub) or that the connected token cannot already see (other hosts).
- Pushes to your pull request branches or default branch. Fix pull requests use their own `mergeharbor/fix-*` branches.
- Write access to workflows, packages or GitHub Actions. **Actions** is read-only and used only to read failed job logs.
- `sudo`, `admin_mode` or `read_user` on GitLab, or `repo`, `admin:org` and `delete_repo` on GitHub.

## Revoke access

First choose **Disconnect** on the connection in **Integrations → Code hosts**. While the token still works, MergeHarbor deletes the webhooks it registered on GitLab, Bitbucket Cloud, Bitbucket Data Center, Azure DevOps and Gitea repositories. It then stops reviewing the connection's repositories and deletes the connection and its stored tokens. Then remove access at the host:

- **GitHub:** uninstall the App under the organization's **Settings → GitHub Apps** (or your personal **Settings → Applications**), or remove repositories from it. Revoke sign-in under **Settings → Applications → Authorized OAuth Apps**.
- **GitLab:** revoke MergeHarbor under **Edit profile → Applications → Authorized applications**, or delete the access token.
- **Bitbucket Cloud:** revoke MergeHarbor under **Personal settings → App authorizations**, or delete the access token.
- **Bitbucket Data Center:** delete the HTTP access token.
- **Azure DevOps:** revoke the app at [myapplications.microsoft.com](https://myapplications.microsoft.com) or remove it in Microsoft Entra **Enterprise applications**, or revoke the personal access token.
- **Gitea and Forgejo:** delete the access token.

Webhook removal is best effort and never blocks disconnecting. A webhook can be left behind if the host was unreachable, the token had already been revoked, or someone changed the hook. A leftover webhook grants no access: MergeHarbor rejects its deliveries once the connection is gone. You can delete it in the repository's webhook or service hook settings. Revoking access at the host before you disconnect also leaves the webhooks in place, so disconnect first.