# Setting up a pause in Jenkins pipeline

To configure an [automatic failing of your Jenkins pipeline in case the quality gate fails](/sonarqube-server/2026.2/analyzing-source-code/ci-integration/jenkins-integration/key-features.md), you must set up a pipeline pause by using the `waitForQualityGate` step.

Proceed as follows:

1. Make sure the `withSonarQubeEnv` step is included in your pipeline so that SonarQube Server taskId is correctly attached to the pipeline context: see **Adding the SonarQube stage to a pipeline** in [Adding analysis to a Jenkins job](/sonarqube-server/2026.2/analyzing-source-code/ci-integration/jenkins-integration/add-analysis-to-job.md).
2. Configure a webhook for your project in your SonarQube Server pointing to `<yourJenkinsInstance>/sonarqube-webhook/` (This is the URL exposed by the Jenkins extension). You may use a webhook configured at global level if applicable to your project. See [Configuring webhooks for your project](/sonarqube-server/2026.2/project-administration/integrations/webhooks.md). This step is mandatory!
3. You may want to enable the verification of the quality gate payload sent to Jenkins by setting a webhook secret: see below.
4. Add a quality gate stage with `waitForQualityGate` to your Jenkins file as described below through examples.

## Adding a quality gate stage <a href="#add-quality-gate-stage" id="add-quality-gate-stage"></a>

This section gives examples of the adding of a quality gate stage to your Jenkins file with `waitForQualityGate`.

### Scripted pipeline <a href="#scripted-pipeline" id="scripted-pipeline"></a>

Thanks to the webhook, the step is implemented in a very lightweight way: no need to occupy a node doing polling, and it doesn’t prevent Jenkins from restarting (the step will be restored after restart). Note that to prevent race conditions, when the step starts (or is restarted) a direct call is made to the server to check if the task is already completed.

<details>

<summary>Example</summary>

```css-79elbk
 node {
  stage('SonarQube analysis') {
    withSonarQubeEnv('<sonarqubeInstallation>') {
      sh 'mvn clean verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar'
    } // submitted SonarQube taskId is automatically attached to the pipeline context
  }
}

// No need to occupy a node

stage("Quality Gate"){
  timeout(time: 1, unit: 'HOURS') { // Just in case something goes wrong, pipeline will be stopped after a timeout
    def qg = waitForQualityGate() // Reuse taskId previously collected by withSonarQubeEnv
    if (qg.status != 'OK') {
      error "Pipeline aborted due to quality gate failure: ${qg.status}"
    }
  }
}
```

</details>

### Declarative pipeline <a href="#declarative-pipeline" id="declarative-pipeline"></a>

<details>

<summary>Example</summary>

```css-79elbk
pipeline {
    agent any
    stages {
        stage('build && SonarQube analysis') {
            steps {
                withSonarQubeEnv('<sonarqubeInstallation>') {
                    // Optionally use a Maven environment you've configured already
                    withMaven(maven:'Maven 3.5') {
                        sh 'mvn clean package org.sonarsource.scanner.maven:sonar-maven-plugin:sonar'
                    }
                }
            }
        }
        stage("Quality Gate") {
            steps {
                timeout(time: 1, unit: 'HOURS') {
                    // Parameter indicates whether to set pipeline to UNSTABLE if Quality Gate fails
                    // true = set pipeline to UNSTABLE, false = don't
                    waitForQualityGate abortPipeline: true
                }
            }
        }
    }
}
```

</details>

<details>

<summary>Multiple analyses in the same pipeline</summary>

If you want to run multiple analyses in the same pipeline and use waitForQualityGate you have to do everything in order as shown in the example below.

```css-79elbk
pipeline {
    agent any
    stages {
        stage('SonarQube analysis 1') {
            steps {
                sh 'mvn clean verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar'
            }
        }
        stage("Quality Gate 1") {
            steps {
                waitForQualityGate abortPipeline: true
            }
        }
        stage('SonarQube analysis 2') {
            steps {
                sh 'gradle sonar'
            }
        }
        stage("Quality Gate 2") {
            steps {
                waitForQualityGate abortPipeline: true
            }
        }
    }
}
```

</details>

## Configuring a Webhook secret <a href="#webhook-secret" id="webhook-secret"></a>

If you want to verify the webhook payload that is sent to Jenkins, you can add a secret to your webhook on SonarQube Server.

To set the secret:

1. In Jenkins, navigate to **Manage Jenkins** > **Configure System** > **SonarQube Server** > **Advanced** > **Webhook Secret** and click the **Add** button.
2. Select **Secret text** and give the secret an ID.
3. Select the secret from the dropdown menu.

If you want to override the webhook secret on a project level, you can add the secret to Jenkins and then reference the secret ID when calling `waitForQualityGate` as follows:

<details>

<summary>Scripted pipeline</summary>

```css-79elbk
waitForQualityGate webhookSecretId: 'yourSecretID'
```

</details>

<details>

<summary>Declarative pipeline</summary>

```css-79elbk
waitForQualityGate(webhookSecretId: 'yourSecretID') 
```

</details>

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Key features of Jenkins integration](/sonarqube-server/2026.2/analyzing-source-code/ci-integration/jenkins-integration/key-features.md)
* [Setting up Jenkins](/sonarqube-server/2026.2/analyzing-source-code/ci-integration/jenkins-integration/global-setup.md)
* [Adding analysis to a Jenkins job](/sonarqube-server/2026.2/analyzing-source-code/ci-integration/jenkins-integration/add-analysis-to-job.md)


---

# 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/sonarqube-server/2026.2/analyzing-source-code/ci-integration/jenkins-integration/pipeline-pause.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.