Setting up a pipeline pause until the quality gate is computed
On this page
Starting in Team plan, you can configure an automatic failing of your pipeline in case the quality gate fails. To do so, you must set up a pipeline pause by using the waitForQualityGate step.
Proceed as follows:
- Make sure the
withSonarQubeEnvstep is included in your pipeline so that the taskId is correctly attached to the pipeline context: see Adding the SonarQube Cloud stage to a pipeline in Adding the SonarQube Cloud analysis to a Jenkins job. - Configure a webhook for your project in SonarQube Cloud pointing to
<yourJenkinsInstance>/sonarqube-webhook/(This is the URL exposed by the Jenkins extension). You may use a webhook configured at the global level if applicable to your project. See Webhooks. This step is mandatory (and cannot be performed in a Free plan organization)! - You may want to enable the verification of the quality gate payload sent to Jenkins by setting a webhook secret: see below.
- Add a quality gate stage with
waitForQualityGateto your Jenkins file as described below through examples.
Adding a quality gate stage
This section gives examples of the adding of a quality gate stage to your Jenkins file with waitForQualityGate.
Scripted pipeline
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.
Example
node {
stage('SonarCloud analysis') {
withSonarQubeEnv('SonarCloud') {
sh 'mvn clean verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar'
} // submitted 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}"
}
}
}Declarative pipeline
Example
pipeline {
agent any
stages {
stage('build && SonarCloud analysis') {
steps {
withSonarQubeEnv('SonarCloud') {
// 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
}
}
}
}
}Multiple analyses in the same pipeline
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.
pipeline {
agent any
stages {
stage('SonarCloud analysis 1') {
steps {
sh 'mvn clean verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar'
}
}
stage("Quality Gate 1") {
steps {
waitForQualityGate abortPipeline: true
}
}
stage('SonarCloud analysis 2') {
steps {
sh 'gradle sonar'
}
}
stage("Quality Gate 2") {
steps {
waitForQualityGate abortPipeline: true
}
}
}
}Configuring a Webhook secret
If you want to verify the webhook payload that is sent to Jenkins, you can add a secret to your webhook on SonarQube Cloud.
To set the secret:
- In Jenkins, navigate to Manage Jenkins > Configure System > SonarQube Server > Advanced > Webhook Secret and click the Add button.
- Select Secret text and give the secret an ID.
- 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:
Scripted pipeline
waitForQualityGate webhookSecretId: 'yourSecretID'Declarative pipeline
waitForQualityGate(webhookSecretId: 'yourSecretID') Was this page helpful?
© 2008-2025 SonarSource SA. All rights reserved.
