> 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-cloud/analyzing-source-code/ci-based-analysis/github-actions-for-sonarcloud.md). # Github Actions Configure an analysis of your SonarQube Cloud project using GitHub Actions. To configure an analysis of your project using GitHub Actions, you will use the SonarQube Scan GitHub Action. ## Prerequisites From SonarQube Scan GitHub Action version 5.0.0 (`sonarqube-scan-action`): * If your runner is [GitHub-hosted](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners), all required utilities should be already provided by default. * If your runner is [self-hosted](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners), you need to ensure that the following utilities are installed and available in the `PATH`: `unzip`, `wget` or `curl`, `gpg` and `dirmngr`. ## SonarQube Scan GitHub Action update notes
In v8, the SonarQube Scan GitHub Action uses GPG to validate the integrity of the Scanner CLI. The SonarQube Scan GitHub Action version 8 uses GPG to validate the integrity of the Scanner CLI. Please see this [release note for the SonarQube Scan GitHub Action](https://github.com/SonarSource/sonarqube-scan-action/releases/tag/v8.0.0).
in v7, the SonarQube Scan GitHub Action uses Scanner CLI v8 The SonarQube Scan GitHub Action version 7 uses the Scanner CLI v8. Please see this [release note for the SonarQube Scan GitHub Action](https://github.com/SonarSource/sonarqube-scan-action/releases/tag/v7.0.0). * The main change on Scanner CLI v8 is related to the embedded JRE version which is now Java 21. Please see [this release note for the SonarScanner CLI](https://github.com/SonarSource/sonar-scanner-cli/releases/tag/8.0.0.6341).
In v6, the SonarQube Scan GitHub Action handles arguments differently The `args` input is parsed differently in `v6`. When updating to `v6`, you might have to update your workflow to change how arguments are quoted. See [this release note](https://github.com/SonarSource/sonarqube-scan-action/releases/tag/v6.0.0) for more information.
In v5, SonarQube Scan GitHub Action is not based on Docker `v3.1.0` and below of the GitHub Action are based on Docker: at every execution of the action, a dedicated docker container is spawned. The advantage of using container are primarily: * **isolation**, since the SonarScanner gets only access to the directory where the project is checked out * **full control of the environment** where the SonarScanner is executed, in terms of required utilities such as `wget` and `keytool` The use of Docker comes, however, with multiple disadvantages: * issues with analyzers requiring access to a system-level directories, such as cache of dependencies in Java or Dart * issues with DockerHub rate limit on peak workload scenarios * requirement by GitHub to run as root user * support for Docker-based actions limited to Linux - no Windows nor MacOS `v5` doesn't have the Docker dependency, making the action [composite](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action). The action now runs in the environment of the runner executing the GitHub workflow.
## Analysis setup overview You should follow the in-product tutorial when creating a new project. When it’s time to **Choose your Analysis Method** during setup, select **With GitHub Actions**. You can also access the tutorials for an existing project by going to *Your Project* > **Administration** > **Analysis Method**. The tutorial will walk you through the precise steps to set up the analysis but the basic steps are these: 1. Define the `SONAR_TOKEN` environment variable in your repository by setting up a GitHub Secret. The `SONAR_TOKEN` identifies and authenticates you to SonarQube Cloud. The tutorial will provide the precise value for your specific account. To generate the token, see: * From the Team plan: [Scoped Organization Tokens](/sonarqube-cloud/administering-sonarcloud/managing-organization/scoped-organization-tokens.md). * With the Free plan: [Managing personal access tokens](/sonarqube-cloud/managing-your-account/managing-tokens.md). 2. Set the parameters used to connect to the instance and identify the project. See: * [Parameters not settable in the UI](/sonarqube-cloud/analyzing-source-code/analysis-parameters/parameters-not-settable-in-ui.md#server-connection) * [Parameters not settable in the UI](/sonarqube-cloud/analyzing-source-code/analysis-parameters/parameters-not-settable-in-ui.md#project-identification) The tutorial will be populated with the correct values for your specific account. The parameters are set differently depending on your project type: * In the `pom.xml` for Java Maven projects. * In the `build.gradle` file for Java Gradle projects. * In the SonarScanner command line for .NET projects. * In the `sonar-project.properties` file for other types of projects. You can also add additional analysis parameters to further specify your analysis details. For more information about analysis parameters setup, see [Configuration overview](/sonarqube-cloud/analyzing-source-code/analysis-parameters/configuration-overview.md). 3. Set up your workflow file that defines the steps of your build. In addition to the usual steps that build your project, you need to invoke the SonarScanner to perform the analysis of your code. For more information, see below. ## Setting up your workflow file This section shows you how to configure your `.github/workflows/build.yml` file. GitHub Actions can build specific branches and pull requests if you use `on.push.branches` and `on.pull-requests` configurations as shown in the examples below. In the tabs below, click the scanner you’re using to expand the example configuration: * For Maven projects: SonarScanner for Maven * For Gradle projects: SonarScanner for Gradle * For .NET projects: SonarScanner for .NET * For other projects: SonarScanner CLI {% hint style="info" %} In the example configurations, the EU region is used. If you want to use the US region, See [Choosing your server region](/sonarqube-cloud/getting-started/choosing-your-region.md). {% endhint %} {% tabs %} {% tab title="Maven" %} Write the following in your workflow YAML file. {% hint style="info" %} A project key might have to be provided through the command line parameter. For more information, see [SonarScanner for Maven](/sonarqube-cloud/analyzing-source-code/scanners/sonarscanner-for-maven.md). {% endhint %} ```yml name: Build on: push: branches: - main # the name of your main branch pull_request: types: [opened, synchronize, reopened] jobs: build: name: Build runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 with: fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis - name: Set up JDK 21 uses: actions/setup-java@v4 with: distribution: temurin java-version: 21 - name: Cache SonarQube packages uses: actions/cache@v4 with: path: ~/.sonar/cache key: ${{ runner.os }}-sonar restore-keys: ${{ runner.os }}-sonar - name: Cache Maven packages uses: actions/cache@v4 with: path: ~/.m2 key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} restore-keys: ${{ runner.os }}-m2 - name: Build and analyze env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} run: mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar ``` {% endtab %} {% tab title="Gradle" %} 1. Activate the SonarScanner for Gradle in your build. See [SonarScanner for Gradle](/sonarqube-cloud/analyzing-source-code/scanners/sonarscanner-for-gradle.md#analyzing). 2. Write the following in your workflow YAML file. ```yml name: Build on: push: branches: - main # the name of your main branch pull_request: types: [opened, synchronize, reopened] jobs: build: name: Build runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 with: fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis - name: Set up JDK 21 uses: actions/setup-java@v4 with: distribution: temurin java-version: 21 - name: Cache SonarQube packages uses: actions/cache@v4 with: path: ~/.sonar/cache key: ${{ runner.os }}-sonar restore-keys: ${{ runner.os }}-sonar - name: Cache Gradle packages uses: actions/cache@v4 with: path: ~/.gradle/caches key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }} restore-keys: ${{ runner.os }}-gradle - name: Build and analyze env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} run: ./gradlew build sonar --info ``` {% endtab %} {% tab title=".NET" %} Write the following in your workflow YAML file. ```yml name: Build on: push: branches: - main # the name of your main branch pull_request: types: [opened, synchronize, reopened] jobs: build: name: Build runs-on: windows-latest steps: - name: Set up JDK 21 uses: actions/setup-java@v4 with: distribution: temurin java-version: 21 - uses: actions/checkout@v6 with: fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis - name: Cache SonarQube packages uses: actions/cache@v4 with: path: ~\.sonar\cache key: ${{ runner.os }}-sonar restore-keys: ${{ runner.os }}-sonar - name: Cache SonarQube scanner id: cache-sonar-scanner uses: actions/cache@v4 with: path: .\.sonar\scanner key: ${{ runner.os }}-sonar-scanner restore-keys: ${{ runner.os }}-sonar-scanner - name: Install SonarQube scanner if: steps.cache-sonar-scanner.outputs.cache-hit != 'true' shell: pwsh run: | New-Item -Path .\.sonar\scanner -ItemType Directory dotnet tool update dotnet-sonarscanner --tool-path .\.sonar\scanner - name: Build and analyze shell: pwsh run: | # Fail fast and propagate errors to the runner # https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.5 $ErrorActionPreference = "Stop" $PSNativeCommandUseErrorActionPreference = $true .\.sonar\scanner\dotnet-sonarscanner begin /k:"example" /o:"example" /d:sonar.token="${{ secrets.SONAR_TOKEN }}" dotnet build .\.sonar\scanner\dotnet-sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}" ``` {% endtab %} {% tab title="CLI" %} You can easily set up a basic configuration using the[ SonarQube Scan](https://github.com/marketplace/actions/official-sonarqube-scan) GitHub action, for all languages, including C, C++, Objective-C, and Dart. You’ll find the GitHub Actions and configuration instructions page on the GitHub Marketplace. For C, C++, and Objective-C projects relying on Build Wrapper to generate the compilation database (see the CFamily [Prerequisites](/sonarqube-cloud/analyzing-source-code/languages/c-family/prerequisites.md) page), use the `sonarqube-scan-action/install-build-wrapper` sub-action to install the Build Wrapper. {% endtab %} {% endtabs %} ## Preventing pull request merges when the quality gate fails See [Configuring GitHub project binding](/sonarqube-cloud/managing-your-projects/administering-your-projects/devops-platform-integration/github.md#preventing-the-pull-request-merge-if-the-quality-gate-fails). ## Failing the workflow when the quality gate fails You fail a GitHub Actions workflow on quality-gate failure by making the scanner wait for the Quality Gate result and exit non-zero if it’s failed. To do so, use the `sonar.qualitygate.wait` analysis parameter (optionally with `sonar.qualitygate.timeout`). For more information about these parameters, see [Parameters not settable in the UI](/sonarqube-cloud/analyzing-source-code/analysis-parameters/parameters-not-settable-in-ui.md#quality-gate). ## Analyzing Monorepo Projects: Build Configuration The example below shows how you could set up a yml file for multiple projects in a monorepo. If you want to analyze a monorepo that contains more than one project ensure that you specify the paths to each sub-project for analysis in your build file. To ensure that your monorepo works as expected, you need to build each project in the monorepo separately with a unique project key for each one. **GitHub Actions .yml file** ```yaml name: My Test Monorepo Project on: push: branches: - main paths: - 'lambdas/test/**' pull_request: types: [opened, synchronize, reopened] jobs: sonarqubeScan1: name: SonarQubeScan1 runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - name: SonarQube Scan uses: SonarSource/sonarqube-scan-action@v7 env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} with: projectBaseDir: repo1/ sonarqubeScan2: name: SonarQubeScan2 runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - name: SonarQube Scan uses: SonarSource/sonarqube-scan-action@v7 env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} with: projectBaseDir: repo2/ ``` ## Analyzing pull requests from forked repositories GitHub doesn't expose repository secrets to workflows triggered by a pull request from a fork. Because your `SONAR_TOKEN` is a secret, a single combined build-and-analyze workflow can't run on fork pull requests. [Automatic Analysis](/sonarqube-cloud/analyzing-source-code/automatic-analysis.md) supports fork pull requests without any extra setup, but doesn't produce coverage data. If you need CI-based analysis with coverage on fork pull requests, split the work across three workflows: one for regular (non-fork) pull requests, one that builds fork code without exposing secrets, and one that runs the Sonar analysis with secrets but never executes fork-provided code. {% hint style="warning" %} Checking out a fork's code in a workflow that has access to secrets is a sensitive pattern, even when that code is never executed. Validate every value you pull from the fork's pull request before using it, and keep the analysis job's permissions as narrow as possible. {% endhint %} ### Workflow 1: build and analyze non-fork pull requests This workflow behaves like a standard CI workflow. Restrict it to non-fork pull requests, and analyze directly since the build runs in a trusted context: ```yaml name: CI on: push: branches: - main # the name of your main branch pull_request: jobs: build: runs-on: ubuntu-latest if: github.event.pull_request.head.repo.fork == false steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - name: Set up JDK 21 uses: actions/setup-java@v4 with: distribution: temurin java-version: 21 - name: Build and analyze env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} run: mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar ``` ### Workflow 2: build fork pull requests without secrets This workflow builds and tests fork pull requests with no secret access, then uploads the build output and the PR metadata the next workflow needs as artifacts. Interpolating untrusted values (branch names, ref names) directly into a `run:` shell command is a script-injection risk. Instead, pass PR metadata through an `env:` block: ```yaml name: CI on forks - build and tests on: pull_request: jobs: build: runs-on: ubuntu-latest if: github.event.pull_request.head.repo.fork == true steps: - name: Checkout sources uses: actions/checkout@v6 with: persist-credentials: false - name: Set up JDK 21 uses: actions/setup-java@v4 with: distribution: temurin java-version: 21 - name: Build and test run: mvn -B verify - name: Save build output uses: actions/upload-artifact@v4 with: name: build-output-${{ github.event.pull_request.number }} retention-days: 1 path: | **/target/classes **/target/generated-sources - name: Save PR information env: REPO_NAME: ${{ github.event.pull_request.head.repo.full_name }} HEAD_REF: ${{ github.event.pull_request.head.ref }} HEAD_SHA: ${{ github.event.pull_request.head.sha }} PR_NUMBER: ${{ github.event.pull_request.number }} BASE_REF: ${{ github.event.pull_request.base.ref }} run: | mkdir -p pr-info echo "$REPO_NAME" > pr-info/repo-name echo "$HEAD_REF" > pr-info/head-ref echo "$HEAD_SHA" > pr-info/head-sha echo "$PR_NUMBER" > pr-info/pr-number echo "$BASE_REF" > pr-info/base-ref - name: Upload PR information uses: actions/upload-artifact@v4 with: name: pr-info-${{ github.event.pull_request.number }} path: pr-info/ retention-days: 1 ``` ### Workflow 3: run the Sonar analysis for fork pull requests This workflow triggers on `workflow_run` once workflow 2 finishes, so it runs in the base repository's trusted context with secrets available. It downloads the build output and PR metadata, checks out the fork's code *without executing it*, and runs the scan: ```yaml name: CI on forks - Sonar analysis on: workflow_run: workflows: [CI on forks - build and tests] types: - completed jobs: sonar: runs-on: ubuntu-latest if: > github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' permissions: actions: write contents: read pull-requests: write steps: - name: Download PR information uses: actions/download-artifact@v4 with: pattern: pr-info-* path: ${{ runner.temp }}/pr-info merge-multiple: true run-id: ${{ github.event.workflow_run.id }} github-token: ${{ secrets.GITHUB_TOKEN }} - name: Extract and validate PR information id: pr-info run: | HEAD_SHA=$(cat ${{ runner.temp }}/pr-info/head-sha) HEAD_REF=$(cat ${{ runner.temp }}/pr-info/head-ref) PR_NUMBER=$(cat ${{ runner.temp }}/pr-info/pr-number) BASE_REF=$(cat ${{ runner.temp }}/pr-info/base-ref) [[ "$HEAD_SHA" =~ ^[0-9a-f]{40}$ ]] || { echo "Invalid HEAD_SHA"; exit 1; } [[ "$HEAD_REF" =~ ^[a-zA-Z0-9/_.-]+$ ]] || { echo "Invalid HEAD_REF"; exit 1; } [[ "$PR_NUMBER" =~ ^[0-9]+$ ]] || { echo "Invalid PR_NUMBER"; exit 1; } [[ "$BASE_REF" =~ ^[a-zA-Z0-9/_.-]+$ ]] || { echo "Invalid BASE_REF"; exit 1; } echo "head-sha=$HEAD_SHA" >> "$GITHUB_OUTPUT" echo "head-ref=$HEAD_REF" >> "$GITHUB_OUTPUT" echo "pr-number=$PR_NUMBER" >> "$GITHUB_OUTPUT" echo "base-ref=$BASE_REF" >> "$GITHUB_OUTPUT" - name: Checkout sources uses: actions/checkout@v6 with: ref: ${{ steps.pr-info.outputs.head-sha }} fetch-depth: 0 persist-credentials: false - name: Download build output uses: actions/download-artifact@v4 with: pattern: build-output-* merge-multiple: true run-id: ${{ github.event.workflow_run.id }} github-token: ${{ secrets.GITHUB_TOKEN }} # This step should NOT be replaced by a direct mvn verify call — that would run # fork-provided code in a workflow_run workflow, which has access to secrets. - name: Run Sonar analysis uses: SonarSource/sonarqube-scan-action@v7 env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} with: args: > -Dsonar.pullrequest.key=${{ steps.pr-info.outputs.pr-number }} -Dsonar.pullrequest.branch=${{ steps.pr-info.outputs.head-ref }} -Dsonar.pullrequest.base=${{ steps.pr-info.outputs.base-ref }} -Dsonar.pullrequest.provider=github -Dsonar.pullrequest.github.repository=${{ github.repository }} -Dsonar.scm.revision=${{ steps.pr-info.outputs.head-sha }} - name: Delete artifacts used in analysis if: always() uses: actions/github-script@v7 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | const artifacts = await github.rest.actions.listWorkflowRunArtifacts({ owner: context.repo.owner, repo: context.repo.repo, run_id: context.payload.workflow_run.id, }); for (const artifact of artifacts.data.artifacts) { if (artifact.name.startsWith("build-output-") || artifact.name.startsWith("pr-info-")) { await github.rest.actions.deleteArtifact({ owner: context.repo.owner, repo: context.repo.repo, artifact_id: artifact.id, }); } } ``` `sonar.scm.revision` is what makes the pull request check and decoration appear — without it, the analysis runs but SonarQube Cloud can't match it to the pull request. ### Security considerations * Pass any value that comes from the fork's pull request (branch names, ref names, the head SHA) through an `env:` block, never by interpolating it directly into a `run:` shell command. * Validate extracted values (the head SHA, head branch, PR number, base ref) with a regex before using them in the checkout or scan steps. * Don't quote the scan action's `args:` values that reference `${{ }}` expressions. Quoting can change how the action parses individual arguments. * Keep the analysis workflow's permissions as narrow as the steps above require, and never run fork-provided build commands (like `mvn verify`) directly in this workflow. For a full working example, see this [community thread](https://community.sonarsource.com/t/configuring-a-secured-github-workflow-to-launch-a-sonar-analysis-for-pr-from-forks/141898) and the referenced [example repository workflow files](https://github.com/powsybl/powsybl-afs/tree/main/.github/workflows). ## Managing certificates for the SonarQube Cloud scan GitHub Action If you use the [sonarqube-scan-action](https://github.com/SonarSource/sonarqube-scan-action) for your GitHub Action and SonarQube Cloud is behind a secured proxy with certificates that need to be recognized by the GitHub runner, you’ll need to set the `SONAR_ROOT_CERT` environment variable in GitHub. ## Troubleshooting ### Scanner cannot resolve file paths in test coverage report When using GitHub Action, the SonarScanner fails to resolve the paths within the test coverage report and raises the warning "Could not resolve \ file paths in \". You may resolve this problem by switching off `relative_paths=True` in the coverage settings. ### "Container action is only supported on Linux" error You may encounter this error if you use the SonarQube Scan GitHub Action before version 4, i.e. `sonarcloud-github-action`. This action is based on Docker and is only supported on Linux runners. In that case, move to `sonarqube-scan-action` (see [#prerequisites](#prerequisites "mention")). ### "Container action is only supported on Linux" error You may encounter this error if you use the SonarQube Scan GitHub Action before version 4, i.e. `sonarcloud-github-action`. This action is based on Docker and is only supported on Linux runners. In that case, move to `sonarqube-scan-action` (see *Preqrequisites* above). ### "The job was not started because recent account payments have failed" error You may encounter this GitHub error if your GitHub options are set to use a GitHub-hosted runner instead of your self-hosted runner. In this case, we recommend checking your GitHub options to ensure your self-hosted runner is selected. ### "Failed to import SonarSource public key from all keyservers." You may encounter this error if `dirmngr` is not installed in the runner. It is confirmed by those logs: ``` gpg: error running '/usr/bin/dirmngr': probably not installed gpg: failed to start dirmngr '/usr/bin/dirmngr': Configuration error gpg: can't connect to the dirmngr: Configuration error gpg: keyserver receive failed: No dirmngr ``` Ensure that `dirmngr` is installed on the runner, or disable signature verification by setting `skipSignatureVerification: true` on your pipeline (not recommended). ## Related pages * [Choosing your server region](/sonarqube-cloud/getting-started/choosing-your-region.md) {% hint style="info" %} To analyze CI failures and get automated fix suggestions directly in pull requests, see [Gitar CI failure analysis](https://docs.gitar.ai/features/ci-failure-analysis), a separate Sonar product. {% endhint %} ## Related online courses * :desktop: [Configuring code analysis for SonarQube Cloud with GitHub Actions](https://www.sonarsource.com/learn/course/sonarqube-cloud/d77cd975-f3c7-4ee9-bda5-9e25447d1c9b/configuring-code-analysis-for-sonarqube-cloud-with-azure-pipelines) * :desktop: [Configuring pull request decoration for SonarQube Cloud with GitHub Actions](https://www.sonarsource.com/learn/course/sonarqube-cloud/2b1101c1-91b5-4a30-a0be-cbcccd8c2a61/configuring-pull-request-decoration-for-sonarqube-cloud-with-github-actions)
--- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sonarsource.com/sonarqube-cloud/analyzing-source-code/ci-based-analysis/github-actions-for-sonarcloud.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.