Skip to content

Run Understand in a CI pipeline (end-to-end)

This is the umbrella how-to: it orchestrates the individual headless commands into a single pipeline that runs on every commit, gates the build on CodeCheck violations, and archives SARIF + metrics. Each stage links to its own detailed page — this page shows how they fit together.

This page orchestrates; the details live elsewhere

Prerequisites

  • Understand or the CLI-only kit installed on the build agent — see Install Understand (Headless / CI / Docker tab).
  • A license the agent can reach headlessly — see Licensing from the command line.
  • A saved CodeCheck configuration committed with the project (create it once in the GUI).
  • A .und that is portable if the agent's paths differ from where it was created — see Portable projects & Named Roots.

The pipeline

Keep one .und under version control (or rebuild it on the agent). On each commit, reanalyze only the changed files, run the saved config scoped to the commit, and export metrics.

#!/bin/bash -x
UND=/path/to/scitools/bin/linux64/und
DB=$WORKSPACE/project.und
OUT=$WORKSPACE/understand_out
GITREV=$(git rev-parse HEAD)
mkdir -p "$OUT"

# 1. Build the project once (or check in the .und). See headless-workflow.
#    und -db "$DB" create -languages c++
#    und -db "$DB" add -cmake "$WORKSPACE/build/compile_commands.json"

# 2. Incrementally reanalyze the changed files (fast per-commit).
"$UND" -db "$DB" analyze -changed

# 3. Run the saved CodeCheck config on this commit's files; gate the build.
"$UND" -db "$DB" codecheck -exitstatus -gitfiles "$GITREV" \
       -sarif "$OUT/results.sarif" "MyConfig" "$OUT" || CODECHECK_RC=$?

# 4. Export metrics for trend tracking (archive the CSV as a build artifact).
"$UND" -db "$DB" metrics "$OUT/metrics.csv"

exit ${CODECHECK_RC:-0}

What gates the build

Understand does not have a single "pass/fail" command; you compose the gate from the exit codes of the individual stages.

Stage Command How it gates
Analyze und analyze -changed Reparses only changed files. Parse errors are surfaced but do not by themselves fail the step — inspect the log.
CodeCheck und codecheck -exitstatus … Exit code = violation count; non-zero fails the step. Scope with -gitfiles/-changedfiles so you fail only on the commit's code.
Metrics und metrics … For trend data, not gating. Threshold it yourself in the pipeline if you want to fail on a metric.

Fail only on new violations

Scope CodeCheck with -gitfiles/-changedfiles, or compare against a baseline with -previous <old.sarif>. See Baseline violations.

Publish results

  • SARIF (-sarif) — archive it, or feed it to a viewer/plugin. Results from other tools can be brought back into Understand too — see Import SARIF.
  • Metrics CSV — archive per build/tag and chart the columns you track (the Entity_Uniquename column follows an entity across runs). See Export & track metrics.

Where to run it

  • Jenkins — either the dedicated Understand Jenkins plugin (form-driven, feeds Warnings Next Generation), or an Execute-Shell step running the script above (Run CodeCheck in CI).
  • Any other CI — the same script runs anywhere und is on the agent.
  • C/C++ with no compile_commands.json — capture the build first with Buildspy in CI.