Nexus IQ for GitLab CI

Download

Download the docker image here:  GitLab Nexus IQ docker image

Overview

CI/CD pipeline jobs in GitLab leverage custom docker images to perform desired actions in the context of the GitLab project's build workspace.  As such, the GitLab Nexus IQ docker image provides the ability to run Nexus policy evaluation against build artifacts in GitLab and produces a summary report with policy violation counts and a link to a detailed report on the IQ server.

Any project that wants to leverage GitLab's CI/CD pipeline must include a .gitlab-ci.yml pipeline definition file in the root of the project.  Documentation on the various options for pipeline and job definitions is available here.  A GitLab pipeline job that performs Nexus IQ policy evaluation consists of the following elements and would look something like this:

iq_policy_eval:
  stage: test
  image: sonatype/gitlab-nexus-iq-pipeline:1.1
  script:
    - /sonatype/evaluate -i WebAppX target/web-app-x.war
  artifacts:
    name: "policy-eval-$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - WebAppX-policy-eval-report.html

Let's explore some of these elements in more detail:

  • iq_policy_eval - the name of the job and can be anything you like
  • stage: test  - the pipeline stage in which to run the policy evaluation;  can be any one of the built in stages or any custom stage defined earlier in the pipeline definition file
  • image: sonatype/gitlab-nexus-iq-pipeline:1.1 - the docker image that will be used during the execution of this pipeline job
  • script - the script statements that will be run in the context of the given docker image;  in this case, the following minimal elements are required:
    • /sonatype/evaluate is the shell script inside the docker container that executes the policy evaluation
    • -i WebAppX is the unique ID of the application being evaluated, as defined in IQ server
    • target/web-app-x.war is a list of one or more artifacts from the build environment to perform the evaluation against
    • See the documentation provided with the image on Docker Hub for details about other options available during policy evaluation
  • artifacts - list of directories or files that will be zipped and archived with the executed pipeline;  see the GitLab documentation for more information on how long these artifacts live and how to access them
    • name - the name to give the artifact zip file (note: pipeline variables can be used to create the name, as shown in the above example)
    • paths - references to one or more files or directories in the build environment to include in the archive
      • WebAppX-policy-eval-report.html - this is the name of the report generated by the policy evaluation and is comprised of '<app id>-policy-eval-report.html'

In order to make GitLab CI/CD pipeline job artifacts available across jobs you should add them to the pipeline cache, which could be defined a little further up in the file, as so:

cache:
  paths:
    - target/
    - <submodule1>/target/
    - <submodule2>/target/

IQ Server connection information

The required connection information for the IQ server can be specified at either the group or project level using the CI/CD settings, as so:

The following three environment variables must be defined if not set explicitly in the job definition via script parameters:

Problems with the IQ server connection will show up in, and can be diagnosed from, the pipeline job output, as so:

Release Notes

Version 1.1

  • released 2019-04-29
  • expanded coverage option (-xc) fixed
  • application ID added to the report filename
  • policy violation counts added to the html report

Version 1.0

  • released 2019-04-25
  • Known issues:
    • Using the expanded coverage option (-xc) will incorrectly cause the pipeline job to fail
    • Multiple evaluations in the same job will incorrectly append report information to the same policy-eval-report.html file