> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/project-administration/maintaining-project/changing-project-binding.md).

# Changing your project binding

In SonarQube Server 2026.5, you can bind an unbound project and you can change the binding of a bound project.

You must be an administrator of your project.

## Unbinding or changing the binding of a bound project

1. Retrieve your project. For more information, see [Retrieving projects](https://docs.sonarsource.com/sonarqube-server/user-guide/viewing-projects/retrieving-projects.md).
2. Go to **Project settings** > **General settings** > **DevOps platform integration**.
3. In the bottom of the page, select **Reset**. The project is unbound.
4. To bind the project to another repository, see [#binding-an-unbound-project](#binding-an-unbound-project "mention").

## Binding an unbound project

If you created your project manually, you can bind it to its DevOps platform repository to benefit from the features of a bound project.

### Credentials you need

To bind a project, SonarQube Server uses a credential stored in SonarQube Server for your user account. The credentials set on the global DevOps platform integration are not used for this, so you can only bind projects to repositories you have access to on the DevOps platform.

The credential depends on your DevOps platform:

| DevOps platform       | Credential                                    | How to get it                                                                                                                                                                  |
| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GitLab                | Legacy personal access token                  | [Importing your GitLab repository](https://docs.sonarsource.com/sonarqube-server/project-administration/creating-project/gitlab/import-repos.md)                               |
| Azure DevOps          | Personal access token                         | [Importing your Azure DevOps repository](https://docs.sonarsource.com/sonarqube-server/project-administration/creating-project/azure-devops/import-repos.md)                   |
| Bitbucket Data Center | Personal access token                         | [Importing your Bitbucket Data Center repository](https://docs.sonarsource.com/sonarqube-server/project-administration/creating-project/bitbucket-data-center/import-repos.md) |
| Bitbucket Cloud       | Atlassian account email address and API token | [Importing your Bitbucket Cloud repository](https://docs.sonarsource.com/sonarqube-server/project-administration/creating-project/bitbucket-cloud/import-repos.md)             |
| GitHub                | GitHub authorization                          | [#authorizing-sonarqube-server-on-github](#authorizing-sonarqube-server-on-github "mention")                                                                                   |

For GitLab, create a legacy personal access token with the `read_api` scope. In GitLab, choose the legacy token type when you generate the token. Do not use a fine-grained token.

For Azure DevOps Services, set **Organization** to one organization when you create the token. Do not select **All accessible organizations**. This does not apply to Azure DevOps Server.

For GitLab, Azure DevOps, Bitbucket Cloud, and Bitbucket Data Center, the **DevOps Platform Integration** page asks for your credential when you bind the project, if you have no valid one stored and you have the Create Projects permission.

If you do not have the Create Projects permission, the page does not show **Save** for any DevOps platform. Ask your system administrator to give you the permission. For GitHub, see [#authorizing-sonarqube-server-on-github](#authorizing-sonarqube-server-on-github "mention").

After you have the permission, you can also store a token for your user account first. Do one of the following:

* Start a repository import through **Create project** and select your DevOps platform. Before it lists your repositories, the import flow prompts you for a token.
* Call the `POST api/alm_integrations/set_pat` web API endpoint while signed in as the user who will save the binding. That user account needs the Create Projects permission. Set the `almSetting` parameter to the name of the DevOps platform configuration and the `pat` parameter to a valid token. For Bitbucket Cloud, also set the `username` parameter to your Atlassian account email address.

If you bind a project to a GitLab, Azure DevOps, Bitbucket Cloud, or Bitbucket Data Center repository through the web API and no token is stored for your user account, the call fails with the message *personal access token for '\<configuration name>' is missing*.

### Authorizing SonarQube Server on GitHub

For GitHub, you do not create a token. SonarQube Server stores a GitHub App user access token for your user account when you authorize the GitHub App. You authorize once for each GitHub configuration. To authorize, you need the Create Projects permission. Until you authorize, saving the binding fails with the message *No GitHub authorization found for your user*.

To authorize SonarQube Server on GitHub:

1. Select **Projects** > **Create project** > **Import from DevOps platforms**.
2. In the **Import from GitHub** section, select **Setup**. The **GitHub project onboarding** page opens.
3. Select your GitHub organization and wait for the repositories to load. You do not need to import a repository.
4. Go back to your project and bind it.

If saving the binding fails because SonarQube Server cannot find the repository, check that:

* The GitHub App is installed on the GitHub organization that owns the repository.
* Your GitHub account has access to the repository.

### Binding steps

To bind the project:

1. Retrieve your project in SonarQube Server. For more information, see [Retrieving projects](https://docs.sonarsource.com/sonarqube-server/user-guide/viewing-projects/retrieving-projects.md).
2. Select **Bind project**. It's available on both of these pages:

   * The **Overview** page, which opens when you retrieve the project.
   * The **Summary** page, which shows the quality gate status and the analysis results. Go to *your project* > **Analysis** > **Summary**.

   The DevOps Platform Integration page opens.

<div align="left"><figure><img src="https://4213461411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmX1WoFEHhJp6VdSbyTDi%2Fuploads%2Fgit-blob-70567ae20e0cf53119bbca2d11686c10fd2517b7%2Fsonarqube-server-bind-project.png?alt=media" alt="Overview page of a project in SonarQube Server with the Bind project button next to the Downloadable reports menu and the Set as homepage button." width="563"><figcaption></figcaption></figure></div>

3. In **Configuration name**, enter the Configuration record used to manage your DevOps platform integration at the global level. Ask your system administrator.
4. This step depends on your DevOps platform:
   * GitHub: In **Repository name**, enter the name of the GitHub repository you want to bind.\
     You can enable the [analysis summary under the GitHub Conversation tab](https://docs.sonarsource.com/sonarqube-server/user-guide/issues/in-devops-platform/github#pull-request-decoration).
   * Bitbucket Data Center: In **Project key** and **Repository slug**, enter the project key and the repository slug of the Bitbucket Data Center repository you want to bind. Both are part of the repository URL: `.../projects/<key>/repos/<slug>/browse`.
   * Bitbucket Cloud: In **Repository slug**, enter the URL of the Bitbucket Cloud repository you want to bind.
   * GitLab: In **Project ID**, enter the unique identifier of your GitLab project you want to bind.
   * Azure DevOps:
     * In **Project name**, enter the name of the Azure DevOps project containing your repository.
     * In **Repository name**, enter the name of the Azure DevOps repository you want to bind.
     * By default, [pull request annotations](https://docs.sonarsource.com/sonarqube-server/user-guide/issues/in-devops-platform/azure-devops#pull-request-decoration) are enabled. You can disable them.
5. If you have no valid credential stored and you have the Create Projects permission, the page shows a **Grant access to your repositories** section. Enter your credential:

   * GitLab: In **Personal Access Token**, enter your legacy personal access token. Do not use a fine-grained token.
   * Azure DevOps and Bitbucket Data Center: In **Personal Access Token**, enter your personal access token.
   * Bitbucket Cloud: In **Atlassian account email address**, enter your Atlassian account email address. In **API token**, enter your API token.

   If the token you stored before has expired or has been revoked, the page asks you to enter it again.

   For GitHub, the page does not show this section. Authorize SonarQube Server on GitHub first. See [#authorizing-sonarqube-server-on-github](#authorizing-sonarqube-server-on-github "mention").
6. Select **Save**. SonarQube Server saves your credential, checks it, and then saves the new binding. If the check fails, the page shows the error and does not save the binding.
7. Select **Check configuration**. SonarQube Server checks if the entered DevOps platform repository exists and you have access to it.

{% hint style="info" %}
The project binding (including the configuration check) is logged in the [audit logs](https://docs.sonarsource.com/sonarqube-server/instance-administration/security/audit-logs.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-server/project-administration/maintaining-project/changing-project-binding.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
