# GitHub agent apps

> **Available only with SonarQube Cloud.**

Agent Apps for GitHub lets you run AI coding agents inside your repositories. The SonarQube Agent is a GitHub agent app that brings SonarQube into this surface, connecting your work in GitHub to your SonarQube Cloud organization through the [MCP Server](/agent-centric-development-cycle/developer-tools/mcp-server.md). Once installed, you can launch the agent from a repository's **Agents** view or by mentioning it in pull request comments.

This page describes how to install and configure the SonarQube Agent for use through Agent Apps for GitHub.

## Prerequisites

* A working SonarQube Cloud account ([sonarcloud.io](https://sonarcloud.io) or [sonarqube.us](https://sonarqube.us)) using GitHub as the selected DevOps platform. For setup instructions, see the [Getting started with GitHub](/sonarqube-cloud/getting-started/github.md) page in the SonarQube Cloud documentation.
* Access to Agent Apps for GitHub.
* Ability to install apps in your GitHub organization or repository (including personal repositories).

## Getting started

1. Install the [SonarQube Agent](https://github.com/apps/sonarqube-agent) GitHub app in your GitHub organization or repository. Use the [SonarQube Agent US](https://github.com/apps/sonarqube-agent-us) app instead if your SonarQube Cloud organization is in the US region ([sonarqube.us](https://sonarqube.us)).
   * Select **Allow as Agent** before selecting **Install & Authorize**.
2. Every user who wants to use the SonarQube Agent app must authorize the access tokens in SonarQube Cloud.

   * If you are installing the GitHub app, you are automatically redirected to the consent page during installation.
   * Otherwise, navigate to **My account** > **Access tokens**, select the **GitHub Agent** tab, and toggle the **Allow GitHub Agent to create personal access tokens** option. See [Managing your access tokens](/sonarqube-cloud/managing-your-account/managing-tokens.md#github-agent-tokens) in the SonarQube Cloud documentation.

   <div align="left"><figure><img src="/files/iFXcvSPP896GfnBqHChb" alt="The SonarQube Cloud Access tokens page, showing the GitHub Agent tab with the &#x27;Allow GitHub Agent to create personal access tokens&#x27; toggle highlighted." width="563"><figcaption></figcaption></figure></div>
3. If you already had the SonarQube Agent installed, you will need to configure the GitHub app to allow it as an Agent. Go to the organization or repository where the app was installed, open the app page from step 1, and select **Configure**. In the **Agent features** section, select **Allow as Agent**.

   <div align="left"><figure><img src="/files/KYLtTnL4BB4EvqwHJMrQ" alt="A screenshot demonstrating how to allow SonarQube Agent as an Agent, with the &#x27;Allow as Agent&#x27; button highlighted to emphasize the action." width="563"><figcaption></figcaption></figure></div>
4. In GitHub, go to your repository or organization **Settings** > **Secrets and variables** > **Agents**.
5. On the **Agent secrets and variables** page, switch to the **Variables** tab. Create the following variables, copying the names exactly. Your option depends on the level: select **New organization variable** at the organization level, or **New repository variable** at the repository level:

   > **Important:** Use these exact variable names.

   <br>

   | Name                                | Value                                                                                                                                                                                              | Description                                                                                                                                                                     |
   | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `COPILOT_MCP_SONARQUBE_ORG`         | Your SonarQube Cloud [organization key](/sonarqube-cloud/managing-your-projects/retrieving-projects.md#viewing-project-information).                                                               | Required. If your GitHub organization corresponds to a single SonarQube Cloud organization, set this once in organization agent variables and reuse it across all repositories. |
   | `COPILOT_MCP_SONARQUBE_PROJECT_KEY` | The [project key](/sonarqube-cloud/managing-your-projects/retrieving-projects.md#viewing-project-information) inside your SonarQube Cloud organization that is linked with your GitHub repository. | Optional but recommended. Set this under repository agent variables.                                                                                                            |

   > **Note:** When `COPILOT_MCP_SONARQUBE_ORG` is set at both the GitHub organization and repository levels, the repository-level value overrides the organization-level value.

   <br>

   <div align="left"><figure><img src="/files/X3YFBXufbMTnLGLd439T" alt="The Variables tab on the GitHub Agent secrets and variables page, showing COPILOT_MCP_SONARQUBE_ORG and COPILOT_MCP_SONARQUBE_PROJECT_KEY listed as repository variables." width="563"><figcaption></figcaption></figure></div>
6. You are ready to use the SonarQube Agent through Agent Apps for GitHub. Go to your repository > **Agents**, select **SonarQube Agent** in the dropdown, and submit a prompt.

   <div align="left"><figure><img src="/files/qDU4IwGADPezx5FYKF2i" alt="The Agents dropdown in a GitHub repository showing SonarQube Agent alongside Copilot." width="563"><figcaption></figcaption></figure></div>

   You can also mention the agent in your pull request comments.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sonarsource.com/agent-centric-development-cycle/developer-tools/agent-plugins/github-agent-apps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.