codesonar_gerrit_citool.py

• Overview
• build
• analyze
• check
• update
• Command Options
• Environment Variables
• Specifying analysis_ref

Overview

codesonar_gerrit_citool.py is a wrapper used by the CodeSonar-Gerrit integration.

It provides functionality for running the CodeSonar build/analysis in Gerrit pipelines and performing specified checks on the analysis results.

For some commented usage examples, see the example Jenkinsfiles:

• $CSONAR/csonar-ci/cso-gerrit/examples/IncrExample/Jenkinsfile
• $CSONAR/csonar-ci/cso-gerrit/examples/IncrExample/use-environment.Jenkinsfile

There are four general forms.

Example command lines in the remainder of this page are written like the following.

where:

• $CSONAR is the CodeSonar installation directory.
• $CSONAR_GERRIT is the csonar-ci/cso-gerrit/py subdirectory of the CodeSonar installation directory.

If you want to use these environment variables you will need to set them to appropriate values: they are not set automatically.

build : Accumulate Project Components Without Analyzing

Use the build form of the command to accumulate components toward a CodeSonar project, but not finalize or analyze the project.

This form has similar functionality to the regular codesonar build command, with some key differences:

• It can take advantage of the global options available to codesonar_gerrit_citool.py.
• Interactive functionality, such as prompting for a password, is not available.

The general form of the command is:

Where:

For more information about the project_file, hub_address, CS_BUILD_OPTS, and command elements, see Building and Analyzing a CodeSonar Project.

analyze : Build and Analyze Project, Evaluate Analysis Results

Use the analyze form of the command to build and analyze a CodeSonar project, then run a specified set of checks with respect to a specified subset of the analysis results.

In most respects this form extends the functionality of the regular codesonar analyze command. However, interactive functionality, such as prompting for a password, is not available.

The general form of the command is:

Where:

For more information about the project_file, hub_address, CS_ANALYZE_OPTS, and command elements, see Building and Analyzing a CodeSonar Project.

check : Check Results of an Existing Analysis

Use the check form of the command to perform checks on an existing analysis. This can be an analysis performed with $CSONAR/codesonar/bin/cspython $CSONAR_GERRIT/codesonar_gerrit_citool.py analyze, or one performed with the standard codesonar analyze.

The general form of the command is:

Where:

update : Update an Existing Analysis

Use the update form of the command to update information about an existing analysis and its warnings.

The general form of the command is:

Where:

Command Options

The various forms of the codesonar_gerrit_citool.py command have a large number of options.

• Global Options (GLOBAL_OPTS)
• codesonar build Options (CS_BUILD_OPTS)
• codesonar analyze Options (CS_ANALYZE_OPTS)
• Search Options (SEARCH_OPTS)
• Check Options (CHECK_OPTS)
• Gerrit-Specific Options (GERRIT_OPTS)
• Update Options (UPDATE_OPTS)

Global Options (GLOBAL_OPTS)

The global options can be used with all forms of the codesonar_gerrit_citool.py command.

• -tmpdir temp
• standard authentication options
• -hubbearervar variable
• -hubcertvar variable
• -hubkeyvar variable
• -hubpwvar variable
• -cs-environment-format vartemplate
• -use-environment

codesonar build Options (CS_BUILD_OPTS)

Any option that can be used with the standard codesonar build command can also be used with the build form of the codesonar_gerrit_citool.py command.

For more information, see Command Line Build/Analysis.

codesonar analyze Options (CS_ANALYZE_OPTS)

Any option that can be used with the standard codesonar analyze command can also be used with the analyze form of the codesonar_gerrit_citool.py command.

For more information, see see Command Line Build/Analysis.

Search Options (SEARCH_OPTS)

The search options can be used with the analyze, check, and update forms of the codesonar_citool.py command.

• -comparison-analysis comp_analysis
• -warning-visibility filter
• -warning-search wsearch_exp
• -search-param param value

Use these options to restrict the following to a particular subset of the warnings produced by the analysis.

• All checks specified with the -check option.
• The contents of the output files produced with -dump-sarif and -summary.
• All warning updates specified with update options.

If no search options are specified, checks/updates are applied to all warnings produced by the analysis, and output files include information about all warnings.

Check Options (CHECK_OPTS)

The check options can be used with the analyze and check forms of the codesonar_gerrit_citool.py command.

• -check check_method [+check_arg...]
• -dump-sarif sarif_file
• -fail-code exit_code
• -polling-timeout inactivity_seconds
• -summary report_file

Gerrit-Specific Options (GERRIT_OPTS)

The Gerrit-specific options can be used with the analyze and check forms of the codesonar_gerrit_citool.py command.

• -gerrit-cacert cafile
• -gerrit-change changeid
• -gerrit-label label
• -gerrit-patchset revision
• -gerrit-project repository
• -gerrit-pwfile file
• -gerrit-target-branch branch
• -gerrit-url url
• -gerrit-user username

Update Options (UPDATE_OPTS)

The update options can be used with the update form of the codesonar_gerrit_citool.py command.

• -set-property name value
• -set-priority priority
• -set-state state
• -set-finding finding
• -set-owner owner
• -add-note comment

For all of these updates, the authorizing hub user must have ANALYSIS_ANNOTATE permission for the specified analysis. Any additional permission requirements for individual updates are noted in the option details.

Note on eligible warnings. If one or more search options are specified, warning updates are only applied to warnings that were issued by the specified analysis and meet all the specified constraints. Otherwise, warning updates are applied to all warnings issued by the specified analysis. Search options do not affect the behavior of -set-property.

Environment Variables for -use-environment

• CodeSonar Environment Variables Set by the User
• Useful Environment Variables Set by the Gerrit Trigger Plugin for Jenkins
• Useful Environment Variables Set by Jenkins Pipeline
• User-Defined Analysis Properties

When the -use-environment option is specified, various environment variables are recognized and used as command defaults or stored as user-defined analysis properties. These environment variables can be divided into three groups: those set by the user, those set by the Gerrit Trigger Plugin for Jenkins, and those set by Jenkins Pipeline.

CodeSonar Environment Variables Set by the User

The table below shows the default CodeSonar environment variable names that will be recognized and used when -use-environment is specified. If you want to use these variables, you will need to define them to appropriate values.

If -cs-environment-format is also specified, codesonar_gerrit_citool.py will instead recognize the variable names produced by replacing the CODESONAR_ according to the specified format. Variables with other prefixes will not be affected.

For example, if you specify -cs-environment-format MYCS_? then the recognized environment variables will be MYCS_HUBUSER, MYCS_HUBPWFILE, and so on.

Useful Environment Variables Set by the Gerrit Trigger Plugin for Jenkins

These variables are set by the Gerrit Trigger Plugin for Jenkins: you should not need to modify them.

Some of these variables are recognized and automatically used when -use-environment is specified.

Useful Environment Variables Set by Jenkins Pipeline

If you are using Jenkins Pipeline, it will set a number of useful environment variables. Some of these variables are recognized and their values automatically recorded when -use-environment is specified.

For more information about these and other environment variables made available by Jenkins Pipeline, see Using a Jenkinsfile.

User-Defined Analysis Properties

As shown in the table above, many environment variables are stored as user-defined analysis properties when -use-environment is specified.

These properties can be used in analysis search language expressions to find the CodeSonar analysis that corresponds to a particular Gerrit change or Jenkins build. For example, the example Jenkinsfile at $CSONAR/csonar-ci/cso-gerrit/examples/IncrExample/Jenkinsfile includes the following fragment, in which an update command specifies the analysis of interest using an analysis search language expression. This expression will match an analysis whose gerrit_change_id and gerrit_patchset_commit properties have values matching those recorded in the specified environment variables.

    // ...
    script {
        // Find the last analysis for this change and update it with warning annotations and analysis properties:
        sh '''
            "$CSONAR/codesonar/bin/cspython" "$CSONAR_GERRIT/tools/codesonar_gerrit_citool.py" \
            update \
           "?((gerrit_change_id=$GERRIT_CHANGE_ID) & (gerrit_patchset_commit=$GERRIT_PATCHSET_REVISION))" \

If your analyze command does not specify -use-environment, these properties are not set automatically. In this case, you will need to explicitly set any properties that you will later rely on to coordinate CodeSonar analyses, Jenkins builds, and Gerrit changes. You do not need to use the same property names as those discussed here, although you may find it convenient to do so.

It is generally most convenient to do this in your analyze command, using the standard CodeSonar -property option. This ensures that the properties are available for any subsequent analysis searches or other uses. For example:

If you need to add or modify an analysis property after the analyze command has run, you can use an update command with the -set-property option. Note that if you are updating a historical analysis the environment variables may not have the values you require, so you may need to obtain the property values from some other source.

Specifying analysis_ref for check and update Commands

The codesonar_gerrit_citool.py check and codesonar_gerrit_citool.py update commands take an analysis_ref argument that specifies the analysis of interest. The analysis_ref can have any of the following forms.