IBM ZCodeScan Baseline management guide

IBM® ZCodeScan's baseline feature helps you manage code quality by tracking known issues and identifying new problems introduced during development. This guide explains how to use baseline commands to maintain code quality standards across your development lifecycle.

Baseline fundamentals

A baseline is a reference point that captures all detected issues at a specific point in time. Once you create a baseline, you can track known issues, identify new problems, and monitor improvements. All issues in the baseline remain visible but are marked as "known".

Baselines enable quality gates in CI/CD pipelines, support release management by tracking code quality across versions, facilitate technical debt management, and establish shared quality standards for team collaboration.

Commands

Create Baseline
This command creates a baseline file that captures the current state of your code quality. The command performs a complete scan of your codebase and saves all detected issues to a baseline file. All issues captured in the baseline are marked as "known issues" and will be suppressed in subsequent scans when you apply the baseline.
Create a baseline after you complete a code review, before you release a new version, at the start of a new sprint, after you merge approved changes, or when you establish initial quality standards.
zcodescan --createBaseline <baseline-file> [scan-options]
Parameter:
  • <baseline-file>: Path where the baseline JSON file will be saved
  • [scan-options]: Standard IBM ZCodeScan options (source folders, rules, configuration)
Example:
zcodescan --createBaseline ./baselines/release-1.0.json \
  -sf ./src \
  -cf config.yml
Output:
* Scan Summary:
*   Total Files   : 31
*   Scanned Files : 26
*   Issues Count  : 5259
✓ Baseline created: ./baselines/release-1.0.json
  Total 5259 issues were marked as known and will be suppressed in future scans.
Note: The command will not overwrite existing baseline files. Delete or rename the existing file if you need to create a new baseline at the same location.
Apply Baseline (Incremental Scans)
This command compares your current code against an existing baseline to identify new issues. The command performs an incremental scan by comparing your current code quality state against a previously created baseline. The scan identifies three categories: new issues that require attention, known issues from the baseline, and resolved issues that have been fixed.
Apply a baseline during pull request validation, in CI/CD pipelines as a quality gate, during daily development to monitor code quality changes, or before you merge feature branches.
Command:
zcodescan --applyBaseline <baseline-file> [scan-options]
Parameters:
  • <baseline-file>: Path to an existing baseline JSON file
  • [scan-options]: Standard IBM ZCodeScan options (must match baseline creation settings)
Process:
  1. Scans your current code with the same configuration used to create the baseline
  2. Compares current scan results against the baseline
  3. Categorizes issues into three groups:
    • New findings: Issues not present in the baseline (require action)
    • Suppressed known findings: Issues in both baseline and current scan (tracked but don't block builds)
    • Resolved findings: Issues from baseline no longer detected (code improvements)
Output: 
zcodescan --applyBaseline ./baselines/release-1.0.json \
  -sf ./src \
  -cf config.yml \
  -rf rules.yml \
  -of new-issues.yml
Output:
* Applying baseline: ./baselines/release-1.0.json
✓ Baseline comparison complete:
* New findings: 15
* Suppressed known findings: 145
* Resolved findings: 5

*! WARNING: 15 new findings detected!

Baseline comparison results

When you apply a baseline, the system categorizes issues into three groups:
  • New Findings are issues detected in the current scan but not in the baseline. These issues require review and action. The system reports them in scan output and they cause a non-zero exit code.
  • Suppressed Known Findings are issues present in both the baseline and current scan. The system tracks them for awareness but they don't block builds. They do not affect the exit code.
  • Resolved Findings are issues from the baseline that are no longer detected. They indicate code improvements and do not affect the exit code.
Example output interpretation: 
✓ Baseline comparison complete:
* New findings: 15                         ← Action required
* Suppressed known findings: 145           ← Tracked, suppressed
* Resolved findings: 5                     ← Improvements

This output indicates 15 new findings that need attention, 145 known findings still present but suppressed, and 5 findings successfully resolved.

Baseline file format

The system stores baselines in JSON format. Each baseline file contains metadata and a list of findings. The metadata includes a timestamp in ISO 8601 format (UTC) that indicates when the baseline was created.

Metadata
-created_at: Timestamp indicating when the baseline was created, stored in ISO 8601 format (UTC). This helps track the baseline version and age.
Findings:
- findings: An array containing all code quality issues detected at the time of baseline creation. Each finding includes:
  - fingerprint: A unique identifier that precisely identifies each issue. This fingerprint is used to match issues across scans, ensuring accurate tracking of new, known, and resolved issues.
  - rule_id: The identifier of the quality rule that detected the issue (for example., "COBOL.QualityGate.LineLength"). This links the issue to specific coding standards.
  - severity: The severity level of the issue, which can be:
    - BLOCKER: Critical issues that must be addressed immediately
    - HIGH: Serious issues requiring prompt attention
    - MEDIUM: Moderate issues that should be addressed
    - LOW: Minor issues for consideration
    - INFO: Informational findings for awareness
  - file: The relative path to the source file where the issue was detected, making it easy to locate the problem in your codebase.
  - message: Description of the issue, explaining what was detected and why it matters.

Known Limitations

IBM ZCodeScan currently supports only one baseline per scan. You cannot combine or merge multiple baselines in a single scan operation. For more information about troubleshooting, see IBM ZCodeScan Known issues and limitations.