# Setting up a pipeline pause

To configure an [key-features](https://docs.sonarsource.com/sonarqube-server/10.7/analyzing-source-code/ci-integration/jenkins-integration/key-features "mention"), 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 taskId is correctly attached to the pipeline context: see **Adding the SonarQube stage to a pipeline** in [add-analysis-to-job](https://docs.sonarsource.com/sonarqube-server/10.7/analyzing-source-code/ci-integration/jenkins-integration/add-analysis-to-job "mention").
2. Configure a webhook for your project in your SonarQube server pointing to `<yourJenkinsInstance>/sonarqube-webhook/`(This is the URL exposed by the SonarQube extension for Jenkins). You may use a webhook configured at global level if applicable to your project. See [webhooks](https://docs.sonarsource.com/sonarqube-server/10.7/project-administration/webhooks "mention"). 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:3.11.0.3922: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 killed 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 sonar: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 sonar: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.

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](https://docs.sonarsource.com/sonarqube-server/10.7/analyzing-source-code/ci-integration/jenkins-integration/key-features "mention")
* [global-setup](https://docs.sonarsource.com/sonarqube-server/10.7/analyzing-source-code/ci-integration/jenkins-integration/global-setup "mention")
* [add-analysis-to-job](https://docs.sonarsource.com/sonarqube-server/10.7/analyzing-source-code/ci-integration/jenkins-integration/add-analysis-to-job "mention")