The project Section

The project section of the configuration file tells Coverity on Polaris the name to use for the project, branch, and revision. It also allows you to assign existing groups to a project and select their role during project creation.

For project root directories that are Git or Subversion repositories, you can use information from the repository in your configuration file. For example, when Coverity on Polaris generates a configuration file, it automatically uses source controls values if they are available.

Project section properties

Table 1. Project section properties
Name	Type	Required	Description
organization	value	no	Allows you to specify your organization.
name	value	no	If no project name is specified, Coverity on Polaris picks a reasonable default; either the source code repository project name or the current directory. Project names must be unique within the organization, and are case-insensitive: myapp is not a different name from myApp.
branch	value	yes	This is the name of the project branch to be scanned. You can tell Coverity on Polaris which branch to scan in your `polaris.yml` file or can be conveniently set to the master branch in your git repo (by means of a variable such as `${scm.git.branch}`). The first branch scanned in the CLI is your main-for-project branch and the first default branch but you can change it in the CLI for running incremental analysis but this does not change the main-for-project or preferred viewing branches. Branch names are case-insensitive in Coverity on Polaris: main, Main and MAIN are identical branch names.
properties	key/value pairs (Keys and values must be strings. They cannot be null. They cannot be environment variables.)	no	Accepts up to five key/value pairs created that you have created. The keys must be unique within a project, but keys and values can be shared between projects. This is useful when you need to associate the projects that are parts of the same application or component, or if you want to associate internal tracking numbers for the projects.
groups	value	no	Assigns existing group(s) and allows you to select their role during project creation. Role values are: `Administrator`, `Observer`, and `Contributor`. See Users, Groups, Roles, and Access.
projectDir	value	no	`projectDir` contains the files to be analyzed. The default value is the current directory; in other words,. the directory containing the configuration file.
captureDir	value	no	`captureDir` describes where intermediate results of Coverity on Polaris tools are stored before being uploaded to the server. The default value is .blackduck/polaris in the current directory.
scmUrl	value	no	Stores the address of the source control remote repository. This allows cov-capture to use buildless capture for checking out code and running analysis.
revision	RevisionInfo	yes	Attributes of revision are described below. (Revision names are case-insensitive, like the project and branch but are less likely to be problematic, because revisions usually inherit names from SCM.)

Table 2. Attributes of the revision property. For the `revision` item, the allowable structure is as follows.
Name	Type	Required	Description
name	value	yes	For Git, this corresponds to the commit hash. For Subversion, this corresponds to the revision. (Case-insensitive.)
date	value	yes	Date the revision was committed. The resulting value must evaluate to a date string in ISO8601 format. The date must contain the revision date, the time with seconds resolution, and the time zone.
modified	value	no	This item indicates the local changes made for the given revision. The default value is `false`.

The following examples are valid values for the date value of revision.

2017-05-30T13:25:30Z
2017-05-30T13:25:30+05:30
2017-05-30T13:25:30+05
2017-05-30T13:25:30.111+05:30
20170530T132530Z
20170530T132530+0530
20170530T132530+05
20170530T132530.111+0530

Project examples

General Example

project: 
  name: doc-examples-java-1 
  branch: doc-examples-java-branch
  revision:
    name: doc-examples-java
    date: "2021-08-16T05:12:39Z"
    modified: false
  captureDir: "/Users/Desktop/path/captureDir"
  projectDir: "/Users/path/projectDir"
  scmUrl: "https://github.com/test/simplejava.git"
  properties:
    key1: 162918
    key2: 16291840
    key3: 1629184067
    key4: 162918406779
    key5: 1629184067794h
  groups:
    Group1: "Observer"
    Group2: "Administrator"
    Group3: "Contributor"

For a Git repository, Coverity on Polaris generates the following.

project:
  name: ${scm.git.repo}
  branch: ${scm.git.branch}
  revision:
    name: ${scm.git.commit}
    date: ${scm.git.commit.date}
  properties:
    key1: value1
    key2: value2

In this example, the Git repository name and branch are used as the name and branch in Coverity on Polaris, and the repository's current commit hash and timestamp are used to identify the Coverity on Polaris revision.

Git Detached Mode

If the Git checkout you are using for analysis is detached from HEAD, Coverity on Polaris might require extra help to determine the branch.

If the value of ${scm.git.branch} cannot be determined from Git when in detached mode, then Coverity on Polaris uses the value of the GIT_BRANCH environment variable.

If you are running the analysis from a Jenkins build, this environment variable is already set and no changes are required.

If you are using Azure, the Coverity on Polaris CLI uses the default environment variable – BUILD_SOURCEBRANCHNAME – in the Azure pipeline to retrieve the branch name. This eliminates the requirement for setting the branch name.

If you are running the analysis within a different tool, you can leave your polaris.yml file unchanged, but explicitly set GIT_BRANCH before running analysis. For example, in a GitLab CI environment, you could use CI_COMMIT_REF_NAME as follows:

export GIT_BRANCH=${CI_COMMIT_REF_NAME}
polaris analyze -w