> 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-community-build/project-administration/maintaining-project/changing-project-binding.md).

# Changing your project binding

You can bind an unbound project and you can change the binding of a bound project.

To bind a project in the UI, you must be a system administrator and have the Create Projects permission. To bind a project with the web API, you need the Administer permission on the project and the Create Projects permission.

## Changing the binding of a bound project

The UI does not let you change the binding of a bound project. To change it, use the `PUT api/v2/dop-translation/bound-projects` web API endpoint.

## **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 Community Build uses a credential stored in SonarQube Community Build 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 repositories](https://docs.sonarsource.com/sonarqube-community-build/devops-platform-integration/gitlab-integration/importing-repos.md)                                             |
| Azure DevOps          | Personal access token                         | [Creating and configuring your Azure DevOps project](https://docs.sonarsource.com/sonarqube-community-build/devops-platform-integration/azure-devops-integration/creating-your-project.md)                 |
| Bitbucket Data Center | Personal access token                         | [Importing your Bitbucket Data Center repositories](https://docs.sonarsource.com/sonarqube-community-build/devops-platform-integration/bitbucket-integration/bitbucket-server-integration/import-repos.md) |
| Bitbucket Cloud       | Atlassian account email address and API token | [Importing Bitbucket Cloud repositories](https://docs.sonarsource.com/sonarqube-community-build/devops-platform-integration/bitbucket-integration/bitbucket-cloud-integration/import-repos.md)             |
| GitHub                | GitHub authorization                          | [#authorizing-sonarqube-community-build-on-github](#authorizing-sonarqube-community-build-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-community-build-on-github](#authorizing-sonarqube-community-build-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 Community Build on GitHub

For GitHub, you do not create a token. SonarQube Community Build 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 Community Build on GitHub:

1. Select **Projects** > **Create project** > **From GitHub**, and authorize the GitHub App on GitHub.
2. Select your GitHub organization and wait for the repositories to load. You do not need to import a repository.
3. Bind the project. See [#binding-steps](#binding-steps "mention").

If saving the binding fails because SonarQube Community Build 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

In the UI, you can bind a project only if it is not bound and has no analysis yet. For other projects, use the `PUT api/v2/dop-translation/bound-projects` web API endpoint.

To bind the project:

1. Go to **Administration** > **Project coverage**.
2. In the **All projects** table, open the actions menu of your project and select **Bind project**. The **DevOps Platform Integration** page opens.

<figure><img src="broken://spaces/KXW79zfYFiA8incTvwZK/files/RRLa1nm2q05TNwhbTRBJ" alt="Select bind project from the project overview page."><figcaption></figcaption></figure>

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.
   * 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. The Repository slug is part of your Bitbucket Cloud URL. For example, `https://bitbucket.org/<workspace>/<repository>`
   * 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.
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 Community Build on GitHub first. See [#authorizing-sonarqube-community-build-on-github](#authorizing-sonarqube-community-build-on-github "mention").
6. Select **Save**. SonarQube Community Build 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 Community Build checks if the entered DevOps platform repository exists and you have access to it.


---

# 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-community-build/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.
