JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
General

CodeSonar-Gerrit Pipeline Integration: Installation and Examples

The CodeSonar-Gerrit integration package includes scripts and examples to help deploy a Jenkins continuous integration (CI) pipeline which will service Gerrit code reviews. The integration allows the code in a Gerrit code review to be analyzed by CodeSonar. The results of the CodeSonar analysis can then be posted back to the code review as comments and label votes.

The integration makes use of the codesonar_gerrit_citool.py wrapper, which is documented separately.

Overview

The CodeSonar-Gerrit integration package includes scripts and examples to help deploy a Jenkins continuous integration (CI) pipeline which will service Gerrit code reviews. The integration allows the code in a Gerrit code review to be analyzed by CodeSonar. The results of the CodeSonar analysis can then be posted back to the code review as comments and label votes.

The instructions in this document assume that you will use Jenkins with the Gerrit Trigger plugin in order to implement your pipeline for Gerrit. However, the pipeline support provided by the CodeSonar-Gerrit integration is not tightly coupled to Jenkins or the Gerrit Trigger plugin for Jenkins. It should be possible to adapt these instructions to other pipeline implementations, including the Gerrit Code Review plugin for Jenkins and Zuul.

These instructions were developed with CodeSonar 8.2, Gerrit Code Review 3.7, Jenkins 2.346, and Gerrit Trigger plugin for Jenkins 2.39.

The remainder of this page describes the prerequisites for installing and using the CodeSonar-Gerrit integration, then provides detailed instructions for the stages involved:

An Appendix provides some additional detail.

The integration makes use of the codesonar_gerrit_citool.py wrapper, which is documented separately.

In this section (and throughout this manual), $CSONAR indicates the CodeSonar installation directory.

Prerequisites

Familiarity with the following documents is highly recommended:

Note for GitHub and GitLab users

A conventional Gerrit code review workflow is distinctly different from a GitHub pull request or GitLab merge request workflow. For example, Gerrit relies on Git branch rebasing and pushing amended Git commits, which is not typical for a GitHub or GitLab workflow.

A. Install CodeSonar and integration tools on your Jenkins agent

  1. Sign in to your Jenkins agent.
  2. Install CodeSonar.
    1. Extract the CodeSonar installer package (typically in the /opt directory).
    2. Activate CodeSonar. (The path to your codesonar executable may differ from the example below.)
      /opt/codesonar-9.2p0/codesonar/bin/codesonar activate
  3. Does your CodeSonar hub use a self-signed HTTPS certificate?
  4. In the Jenkins Web UI, do the following.
    1. Go to the Configure page for your Jenkins agent.
    2. In the Labels field, add a label to indicate that the agent has CodeSonar installed. We recommend using a label that includes the CodeSonar version, such as codesonar-9.2. If you update CodeSonar on your agent, you should also update this label.
    3. In the Node Properties section, select Environment variables and then add the following.
      Name Value
      CSONAR The path to the CodeSonar installation on your Jenkins agent.
      CSONAR_GERRIT The path to the csonar-ci/cso-gerrit/py subdirectory of the CodeSonar installation on your Jenkins agent
      When you set up a Jenkins pipeline, it will be able to use these variables.

B. Set up the example Gerrit repository project

In this stage you will create an example Gerrit repository project named "IncrExample"", and set up this project with example code and pipeline definitions.

  1. Create a new Gerrit repository project from the Gerrit Web UI, with the following settings.
    Create Repository field Value
    Repository name IncrExample
    Default Branch master
    Owner an appropriate Gerrit user: perhaps your own Gerrit user account
    Create initial empty commit True
    Only serve as parent for other repositories False
  2. Add a review label to your Gerrit project to represent the results of the CodeSonar analysis performed by your pipeline. Conventionally, this review label associated with code quality verification is named 'Verified', but any label name acceptable to Gerrit will work. Some tips for configuring a Gerrit review label on your repository project are provided in the Appendix.
  3. Save a copy of the Gerrit server HTTPS certificate in Base64 PEM format (for example, by using the certificate export functionality in your web browser). You will use this in stage D.

    Note: if the certificate is signed by a well-known, publicly trusted certificate root authority, you can skip this step.

  4. On your development workstation, extract the CodeSonar-Gerrit integration package. You will use some of the example code provided in the integration package.
  5. If you intend to use HTTPS with Git (rather than SSH) and if your Gerrit server has a self-signed certificate, you will need to configure Git to trust your Gerrit server's HTTPS certificate. See the Appendix for some tips on how to configure Git to trust a self-signed certificate. If you intend to use SSH with Git, then you do not need to configure Git to trust the Gerrit server's HTTPS certificate.
  6. Clone your new repository to your development workstation and install the Gerrit commit-msg hook.

    Use the commands provided by the Gerrit Web UI Clone with commit-msg hook. This will implicitly record the Gerrit server address as the repository's "remote origin".

  7. Verify that the Gerrit commit hook script was successfully installed.
    1. Check that your repository contains a file named .git/hooks/commit-msg.
    2. Check that this commit-msg file contains Gerrit content. For example, one of the first lines of the file should say: "Part of Gerrit Code Review".
    This commit hook script will automatically add a Change-Id field to your Git commit messages. The Change ID is used by Gerrit to track commits that are related to a code review.
  8. Verify that you have the master branch checked out.
    git branch
    You should see output that includes the following text:
    * master
  9. Make a new branch named example_init.
    git checkout -b example_init
  10. Copy the CodeSonar-Gerrit IncrExample files to your Gerrit repository. These files may be found in the $CSONAR/csonar-ci/cso-gerrit/examples/IncrExample directory. You will need the following files:
  11. Review the contents of IncrExample.c.

    It should contain a trivial main() function. Later you will update this file to include some more code.

  12. Review the contents of Jenkinsfile. This file contains your pipeline definition.

    You will notice that both "Analyze" and "Accept Analysis" stages invoke codesonar_gerrit_citool.py. For full documentation of this tool, see codesonar_gerrit_citool.py.

    The pipeline relies heavily on variables and parameters that will be defined by Jenkins when you run the pipeline. You will configure many of these parameters on your Jenkins pipeline project later.
    1. If you have determined that your Gerrit server has a trusted HTTPS certificate, you can remove all uses of GERRIT_CACERT_ID.
      1. From the withCredentials() invocation, delete file(credentialsId: params.GERRIT_CACERT_ID, variable: 'GERRIT_CACERT').
      2. Delete -gerrit-cacert "$GERRIT_CACERT".
    2. Make any other changes you wish to make. In particular, if your Jenkins agent runs on a non-Linux platform you may need to adjust line continuations and other aspects of shell syntax.
  13. Add and commit the new files to your example_init branch:
    git add IncrExample.c Jenkinsfile Makefile

    git commit -m "Add example files"
  14. Check the log to verify that the commit hook added a Change-Id line to your commit message.
    git log -n 1
  15. Push your commit to Gerrit and open a code review.

    To open a code review that targets the master branch, you must push your local branch to a magic reference target named refs/for/master. It is conventional to push from HEAD, but you could also name your local branch explicitly. Note that in this case, HEAD is the same commit as your local branch example_init.

    git push origin HEAD:refs/for/master
    This will not trigger a pipeline, because we have not yet configured one.
  16. Accept and merge the code review.
    1. Navigate to your Gerrit code review web page. The URL for the web page should have been provided by the git push command output.
    2. Is there a Submit button available on the top right of the page?
      • YES: go on to the next step.
      • NO: this probably indicates that you need to vote on one or more labels.
        1. Click the Reply button. The Reply dialog will open.
        2. Vote for each one of the listed labels with the highest available positive vote.
        3. Click the Send button.
        Once all labels have the required votes, the Submit button will be available.
    3. Click the Submit button and complete the merge of your code review. This will merge your change into the master branch on the Gerrit server.
  17. Check out the master branch and pull your recent changes from the Gerrit server to your local repository.
    git checkout master

    git pull origin

C. Configure your CodeSonar hub for pipeline analysis evaluation

In this step we will create a "saved search" that will help the pipeline determine which code warnings are acceptable and which should cause a pipeline to fail. Operations for this stage are performed in the CodeSonar hub's web UI.

  1. Sign in to your CodeSonar hub web UI as Administrator, or as another user with administrative privileges.
  2. Navigate to the hub's home page (which shows the set of root projects).
  3. Create a saved search that will identify all "unacceptable" warnings.
    1. In the simple search tool at the top of the home page, select warnings in all projects from the pull-down menu.
    2. In the (search) for field, enter the following warning search expression. 
      (state=None OR state=New OR state=Assigned) AND (finding=None OR finding=Unconfirmed OR finding="True Positive") AND (-priority=Suppressed)
      Note that this search expression is a suggestion based on a default hub configuration. You may have different criteria for deeming a warning unacceptable, in which case you must modify this search expression.
    3. Click the Search button.
      A Warning Search Results page will be displayed.
    4. Click the Save this search hyperlink (located under the page heading).
      A save dialog will be displayed.
    5. Enter master_unaccepted in the Save as field of the save dialog.
    6. Click the Save button.
      The page will update to confirm that your search was saved.
    7. Click View saved searches.
      The Saved Searches page will be displayed.
  4. Make sure the new master_unaccepted search is available to all users.
    1. On the Saved Searches page, change to the Warnings tab if it is not already displayed.
    2. Find the table entry for your master_unaccepted search and click the permissions (key icon) link.
      The Named Search master_unaccepted: Permissions page will open.
    3. Check that role Anyone has at least the following permissions for master_unaccepted. If they are missing, add them now.
      • Named Search Exists
      • Named Search Read
    4. Save the updated permissions by clicking the SAVE CHANGES button.
  5. Do you have a suitable CodeSonar CI user account: a (non-Administrator) hub user account for automated CI tasks?
  6. Sign out of the Administrator account.
  7. Create a session bearer token for your CodeSonar CI user account. You will use this to authenticate your CI automated tasks.

    If you already have a suitable bearer token, you can skip this step.

    Note: while we recommend using bearer token authentication, it is not required. If you prefer to use another authentication method, make the corresponding adjustments in stage D.
    1. Sign in to your CodeSonar CI user account.
    2. Navigate to the User Sessions page.
    3. Use the functionality on this page to create a new session. Set an appropriate session expiration: you can create a new session and update your pipeline configuration if this one expires, but it is more convenient to avoid this.

      On successful creation, the session's token will be displayed.

    4. Save the (secret) bearer token now. You will need it in the steps that follow.

D. Set up a Jenkins pipeline

Operations for this stage are performed in the Jenkins UI.

  1. Create a new Jenkins Pipeline project. This project will use a Jenkinsfile to define its pipeline.
  2. In the General tab, select This project is parameterized and add the following parameters.
    Parameter Name Type Description Example
    CODESONAR_AGENT_LABEL String The Jenkins agent label that you are using for agents with CodeSonar installed. This is the label you associated with your agent in stage A. codesonar-9.2
    CODESONAR_HUB String Host and port of your CodeSonar hub. myhubmachine:7340
    CODESONAR_HUBBEARERVAL Password Bearer token for your CodeSonar CI user account. (Created in stage C.) (a short, cryptic string)
    CODESONAR_PROJECT_NAME String The name for the CodeSonar project that you will use to analyze your code. It is often convenient to use the same name as the Gerrit project, but this is not required. IncrExample
    CODESONAR_PROJECT_PATH String The full project path for the CodeSonar project. Any project trees in your specified path must already exist on the hub. The root path is called /. /gerrit/IncrExample
    CODESONAR_REMOTE_ARCHIVE String Your CodeSonar remote launch daemon specification. This will be used with the -remote-archive option: for information on available argument types, see the -remote-archive documentation. /saas/* for CodeSonar SaaS; /myldgroup/* otherwise |
    CODESONAR_WARNING_VISIBILITY String The name of the saved search you created in stage C. master_unaccepted
    GERRIT_URL String Your Gerrit server base URL. https://gerrit.example.com
    GERRIT_CACERT_ID Credentials: Secret file A secret file containing your Gerrit server HTTPS certificate in Base64 PEM format.

    You can omit this parameter if you deleted all uses in the Jenkinsfile (because the Gerrit server certificate is trusted).

    Otherwise, if you don't already have a Jenkins Secret file credential containing this certificate, click Add and follow the steps to create one, then select it as the default value for GERRIT_CACERT_ID.

    		 -----BEGIN CERTIFICATE-----\nMIIEabcdefghi ...
    GERRIT_PWFILE_ID Credentials: Secret file A secret file containing the password associated with GERRIT_USERNAME: that is, the password for your Gerrit CI user account. This pipeline will use this along with GERRIT_USERNAME to authenticate updates to the Gerrit code review.

    If you don't already have a Jenkins Secret file credential containing the password, click Add and follow the steps to create one, then select it as the default value for GERRIT_PWFILE_ID.
    GERRIT_REVIEW_LABEL String The Gerrit review label that you added to represent CodeSonar analysis results. Verified
  3. In the Build Triggers section, do the following.
    1. Select Gerrit event. Additional configuration fields will be displayed.
    2. From the Choose a Server menu, select your Gerrit server. (The menu is populated by previous Gerrit Trigger plugin configuration.)
    3. Click the Advanced button. Another set of additional configuration fields will be displayed.
    4. Under Skip Vote, select all options (Successful, Failed, Unstable, Bit Built and Aborted).
    5. Under Trigger on, click the Add button and select Patchset Created.
    6. Click the Add button again and select Change Merged.
    7. Scroll down to the Gerrit Project section.
    8. Under Project:
      1. Select Plain from the pulldown menu.
      2. Enter IncrExample (your Gerrit repository name) in the adjacent (pattern) field.
    9. Under Branches:
      1. Click Add Branch if there is not already a Branch field for you to configure.
      2. Select Plain from the pulldown menu.
      3. Enter master (your Gerrit repository branch) in the adjacent (pattern) field.
  4. In the Pipeline tab, do the following.
    1. Set the Definition type to Pipeline script from SCM. This tells Jenkins that your pipeline will load your Jenkinsfile from your Gerrit repository.
    2. Set the SCM type to Git.
    3. In the Repositories list, configure a repository item for your Gerrit repository project.
      1. In the Repository URL field, enter the Gerrit repository URL This is the URL displayed in the Gerrit UI for download with ANONYMOUS HTTP (the URL itself may be HTTPS). If you want to use this Jenkins project to serve multiple Gerrit projects, you can substitute the Gerrit Trigger variable $GERRIT_PROJECT for the project name in the URL.
      2. In the Credentials field, provide Username with password credentials for your Gerrit CI user account. If you don't already have a suitable Jenkins credential set up, click Add and create it now.
        • Kind : Username with password
        • Username : the username of your Gerrit CI user account.
        • Password : a generated Gerrit HTTP user password.
      3. Click on Advanced..., then set Refspec: +refs/changes/*:refs/changes/*.
      4. If your Gerrit server uses an untrusted HTTPS certificate, you may need to configure your Jenkins server and your Jenkins agents to trust the Gerrit server's certificate. This was assumed in the Prerequisites. (If you have determined that your Gerrit server has a trusted HTTPS certificate, you can skip this step.)
    4. Under Branches to build:
      1. Click Add Branch if there is not already a branch field for you to configure.
      2. Set Branch Specifier: *$GERRIT_REFSPEC.
        Notice the * prefix. The GERRIT_REFSPEC variable is found in the Gerrit Trigger plugin documentation.
    5. Under Additional Behaviors:
      1. Click Add and select Strategy for choosing what to build from the menu that pops up.
      2. Under Choosing Strategy, select Gerrit Trigger from the menu.
    6. In the Script Path field, specify the exact location of your Jenkinsfile relative to your Gerrit repository root. Since you have set up your repository with the Jenkinsfile stored directly in the root of the repository, you just need to enter Jenkinsfile.
    7. Deselect Lightweight checkout.
  5. Click Save.

E. Do a code review to try out your pipeline

Now that everything is set up, we can try changing some code in the example project and submitting it to a Gerrit code review. If everything is working as expected, then this will trigger a sequence of events.

The $CSONAR/csonar-ci/cso-gerrit/examples/IncrExample/revisions/ directory contains several versions of the IncrExample.c file. We will make code changes by copying various of these revisions over the existing IncrExample.c file in the local example repository. The initial contents of IncrExample.c should exactly match the contents of revisions/0/IncrExample.c.

  1. Your repository should have the master branch checked out already. Create a new branch named example_rev in your example repository, based on the master branch:
    git checkout -b example_rev
  2. In your local repository, overwrite IncrExample.c with revisions/1/IncrExample.c.
    cp $CSONAR/csonar-ci/cso-gerrit/examples/IncrExample/revisions/1/IncrExample.c IncrExample.c
  3. Use git diff to verify that this changes IncrExample.c.
    git diff IncrExample.c
    The output should show the difference between the initial and current contents of IncrExample.c.

    Some of this new code contains bugs. When you push the changes to Gerrit and your pipeline runs, CodeSonar will detect these bugs and the pipeline will produce a "down" vote.

  4. Add and commit the updated file, and push it to the refs/for/master target.
    git add IncrExample.c

    git commit -m "Update from revisions/1/"

    git push origin HEAD:refs/for/master

    Pushing these changes should automatically create a new code review in Gerrit. A Jenkins pipeline for your code review should then be automatically triggered by the Gerrit Trigger plugin in Jenkins.

    The git push output includes the URL for the code review web page.
  5. Navigate to the code review web page URL.
  6. After a brief wait, the results of the pipeline analysis should appear posted to the change log on your Gerrit code review. It may be necessary to refresh the Gerrit change web page to see the pipeline updates.

    The pipeline is expected to fail due to the presence of bugs in the code which the CodeSonar analysis will discover. However, if the pipeline does not start at all, or if it does not perform a CodeSonar analysis, then you will need to troubleshoot and correct the error.

    To check on the status of the pipeline, go to the Jenkins web page and navigate to your pipeline project status.
  7. The pipeline will produce CodeSonar warnings triggered by the bugs in the modified IncrExample.c code. As a result, the pipeline will fail and issue a "down" vote for your code review. (If you prefer the pipeline to pass even when it issues a down vote, see the notes in the Appendix below.)

    In the next stage, we will address the analysis warnings so that we can submit our change.

F. Address analysis warnings and merge your change

In order for the pipeline to pass and issue an "up" vote, there must be no CodeSonar warnings meeting the conditions of the master_unaccepted search that you created in stage C. There are several ways you can handle these unacceptable warnings.

We will demonstrate a combination of Options A and B here.

Note that option B is only possible if you are permitted to disregard the down vote issued by the pipeline and to submit your change anyway. If your review label is configured with a submit requirement that forbids submission when a down vote is present, you will need to choose a different option for addressing the warnings. The Verified label described in the Appendix below does not have any submit requirements.

  1. Review the warnings found by the analysis.
    1. Navigate to the CodeSonar Analysis web page created by the pipeline. The URL for this CodeSonar analysis should have been posted to the change log of your Gerrit code review.
    2. Sign in to the hub as a regular (non-Administrator) user.
    3. Select master_unaccepted from the Visible Warnings selector (upper right).

      Only the warnings that meet the conditions of the master_unaccepted search are now displayed.

    4. Observe the values of the Priority, State, and Finding columns in the warnings table for the analysis. In a default hub configuration, these values will all be set to None.
    5. The hub should show several different warnings found in IncrExample.c. Typically, you would want to review each warning individually to determine if it is acceptable as-is or if it must be fixed. We will fix one warning and we will accept the rest.
  2. Fix some warnings by updating the code.

    The analysis should have found a "Useless Assignment" warning on line 23 of IncrExample.c. We will update the code so that this warning goes away.

    1. Open your copy of IncrExample.c in a text editor.
    2. Go to line 21, which should show a simple variable assigment.
    3. Comment out the line by prefixing it with //. After changing the line to a comment, the line should look like the following. 
      //i = n;
    4. Save the file.
  3. Amend your commit and push the change to Gerrit.
    1. Using your terminal, add your file to the Git index:
      git add IncrExample.c
    2. Use git commit --amend to "patch" your last commit with the new version of the code.
      git commit --amend
    3. This should open a text editor with your Git commit message. You do not need to change anything in the text editor. In particular, you should not alter the Change-Id line at the bottom of the message text. Save the text (if needed) and close the editor. This will replace your old commit with a new commit containing your amended code. Since the Change-Id has not been altered, Gerrit will recognize that the commit is a "patch" to your existing change.
    4. Push your patched change to Gerrit in exactly the same way as you did previously.
      git push origin HEAD:refs/for/master
      Pushing these changes to Gerrit should automatically trigger another pipeline in Jenkins.
  4. Return to the code review web page URL. You may need to refresh the page in order to see the updated code in your new "patchset".
  5. After a brief wait, the results of the new pipeline analysis should appear posted to the change log on your Gerrit code review. It may be necessary to refresh the Gerrit change web page to see the pipeline updates. To check on the status of the pipeline, go to the Jenkins web page and navigate to your pipeline project status.
  6. The pipeline should produce fewer CodeSonar warnings for the bugs in the IncrExample.c code than the pipeline for your previous patchset. However, the pipeline will again fail and issue another "down " vote for your code review.
  7. Look at the message posted by CodeSonar to your Gerrit change log.

    You should notice that the "Useless Assignment" warning was not found in your latest patchset revision. You can confirm this by following the link to the CodeSonar Analysis page (seen in the change log message).

    We will accept the remaining warnings automatically by submitting the code review.
  8. Submit the code review change so that it will be merged.
    1. Return to your Gerrit code review web page.
    2. Provide an up vote on all required review labels.
    3. Click the Submit button.
    Submitting the change will trigger a change-merged pipeline job. This job will not run a new analysis, but it will instead do the following: The warning which were "accepted" by this process did not simply go away. They will continue to be found by CodeSonar in subsequent pipelines for any future changes pushed to your master branch. However, the warnings will be hidden from future pipeline results since they have been annotated to no longer satisfy the master_unaccepted search filter criteria.
  9. Wait briefly for the pipeline job to complete.

    The Gerrit Trigger plugin for Jenkins will start the pipeline job asynchronously. The Gerrit server will not wait for the pipeline job to finish. You can check the status of your pipeline by navigating to the Jenkins project page for your pipeline project.

  10. Check the warning annotation properties for your analysis again.
    1. Return to the CodeSonar analysis page for your code review.
    2. Refresh the page to check the status of the warnings. When the master_unaccepted visibility filter is selected, the warnings table should be empty. Prior to merging your change, the warnings were visible since they met the criteria of the master_unaccepted saved search filter. Now, since the change-merged pipeline ran, the warnings have been updated so that they no longer meet the master_unaccepted filter criteria.
    3. To see the warnings, change the visibility filter to something more permissive, such as the all filter.

G. Try another code review

IncrExample contains several revisions which you can use to further experiment with your pipeline. To use the revisions, follow the steps in the previous section to create a new change for Gerrit. Be sure to substitute a different revision number (i.e. "2" or "3") when copying the IncrExample.c file from the revisions directory.

Appendix

Install Gerrit HTTPS certificate on Jenkins server

If your Gerrit server uses a self-signed HTTPS certificate, it will not be automatically trusted by Jenkins. This may lead to problems when starting pipelines. If your Gerrit server's certificate is signed by a well-known, publicly trusted certificate root authority, you should not need to perform the steps below.

To install the Gerrit server's HTTPS certificate on your Jenkins server, do the following.

  1. Sign in to your Jenkins server with an OS administrator account.
  2. Save a copy of the Gerrit server certificate in Base64 PEM format as gerrit.cacert.
  3. Execute the following command.
    $JAVA_HOME/keytool -keystore $JDK_HOME/jre/lib/security/cacerts -storepass changeit -file gerrit.cacert -alias "Gerrit Server" -noprompt

Configure Git to trust a self-signed Gerrit certificate

When cloning, fetching, pushing, and pulling changes with Git using HTTPS protocol, Git must trust the HTTPS server certificate used by the remote repository host. If the remote repository host (i.e. Gerrit) uses a self-signed certificate, then Git will not trust the remote host and will refuse to interact with it.

This situation does not apply when you configure Git to use SSH instead of HTTPS protocol to communicate with the remote repository host.

There are several ways to configure Git to trust an HTTPS certificate.

Gerrit Trigger plugin parameters

The Gerrit Trigger plugin for Jenkins has dozens of named parameters. These parameters can be used as variables in a Jenkinsfile pipeline script as well as in the Jenkins project configuration. A list of the parameters can be found in the Jenkins Trigger Javadocs hosted by Jenkins, or in the source code on GitHub:

Pipeline pass vs fail when CodeSonar warnings detected

By default, the CodeSonar-Gerrit integration is configured to exit with failure if the designated analysis checks fail. In the example above, this means that by default the Jenkins pipeline will fail if the CodeSonar analysis produces any warnings meeting the conditions of the master_unaccepted search.

In some cases you may prefer different behavior. For example, your organization may require that pipelines exit with failure only if they fail to run to completion, not if they run to completion but produce undesirable results.

There are two main options. Note that these do not affect the Gerrit code review vote produced by the pipeline.

Adding a Gerrit Review Label to a repository project

It is conventional to add a review label named Verified to your Gerrit project and to use it to summarize pipeline test results. It is possible to make an arbitrary number of review labels with arbitrary names. Each review label must have access control. The Gerrit "Service Users" group is typically used for the pipeline user account. It should have access to vote on any labels that it is intended to update.

To add a review label to a Gerrit project, you must check out the special meta/config ref and commit your changes to the project.config file. There are several ways to do this, including with Git and with the Gerrit web UI.

Often, it is also helpful to configure the label on a "parent" repository project in Gerrit. This way, the label configuration can be inherited by new repositories created on your Gerrit server.

In Gerrit 3.7, the project.config file should look something like the following. Note that the label definition parameters have been subject to change across Gerrit releases, so you may need to adjust the definition below to fit your Gerrit version.

[label "Verified"]
    function = NoBlock
    value = -1 Fails
    value = 0 No score
    value = +1 Verified
    copyCondition = changekind:NO_CHANGE OR changekind:TRIVIAL_REBASE OR is:MIN
    defaultValue = 0

[access "refs/heads/*"]
    label-Verified = -1..+1 group Service Users

For more information, see Gerrit Code Review - Review Labels

A label may be further configured with submit requirements so that a change without an affirmative vote on the label cannot be merged. The label definition above does not have any additional submit requirements, so it will not affect the ability of changes to be merged. For more information, see Gerrit Code Review - Submit Requirements.

 

To report problems with this documentation, please visit https://support.codesecure.com/.