How Coverity on Polaris Manages Data

Organizing information in Polaris: Application, Project, Branch, and Revision

Just like source control management (SCM) systems, Polaris uses projects, branches, and revisions to limit the scope of its actions to the part of the code you worked on, including the version used, and its state at a specific time. This allows a team working on a feature to see whether they have discovered or eliminated issues in the code since the last time testing was done, without having to think about issues that belong to other teams working elsewhere on the code base.

Application

An application is a group of projects created by a Polaris organization administrator or application manager in order to combine the data from projects in different repositories.

This allows members of the application to see an aggregated view of results for the application and also the results for each of the constituent projects.

Each application is limited to 200 projects.

Project

The project is the fundamental unit of organization in Polaris.

A project is defined as a single repository (or directory), and all the code in it, whether source code or binaries. It might represent an entire software product, but more frequently a project contains one component of a larger system. When you review or triage issues in Polaris, the issues are grouped according to projects.

A Polaris project and its parts usually correspond to a project of the same name in an SCM system such as Git or Subversion.

To set up a new project or retrieve issues from the API, you also need to know something about how branches and revisions work in Polaris projects.

• The term branch has the same meaning in Polaris that it has in SCM systems, and branches can be created in SCM or in the configuration file (polaris.yml).
• A revision in Polaris is a snapshot of the branch at a particular moment in time. This could correspond to a specific commit in the SCM system, or it could correspond to a specific build of the software. (This isn't exactly the same meaning that the term has in Subversion SCM.)

When does It Help to Know This

Here are some common situations where you'll benefit from an understanding of projects, branches and revisions:

• When you set up your project and scan for the first time, Polaris creates the configuration file (polaris.yml). If you need to change the configuration in your polaris.yml file, you'll see that a project, branch, and revision are specified in the project section. A typical configuration uses variables to point to the main branch in your repo and to run tests on the latest revision. You can change those settings in the configuration file or you can change them by overriding them from the command line.
• When you retrieve issues from the Polaris API, you obtain a project id and branch id associated with the revision that would contain your code, then you can use the project id and branch id to retrieve any open issues for the branch.

Testing Within the Project: Runs and Jobs

Before issues can be discovered in a revision, you have to execute some tests.

• A run is one successful execution of one testing tool. It's important to know that Polaris doesn't return a run id unless a scan is successful. A revision can have multiple runs (you might decide to use more than one tool), but each run can be associated with no more than one revision and no more than one project.
• A job is your request to run the tool. When a scan fails, you get information about the job instead of the run. If you've set up a webhook, it will return a job id instead of a run id; the status will be FAILED; and the response type will be JobFailed.