Using alignment results to drive action

By default, tidelift alignment returns an exit code of 1 when something is not 100% aligned with your catalog standards.

However, in many organizations you may want to make more nuanced decisions based on what issues are detected.  Here are some ways you can use the Tidelift CLI and its output to integrate into other systems, make decisions, or get data for other tools.

Alignment JSON interface

The majority of these examples use the JSON alignment status output. This can be retrieved in one of two ways:

• Using the --json flag to tidelift alignment save --wait or tidelift status. The output of this is documented in our CLI JSON reference
• Using the alignment status API. This is documented in our API documentation

Checking for an alignment score less than 100%

As noted, by default the CLI returns whether there are any detected issues - whether the alignment score is 100%.

Users may want to have a different criteria for action. In the JSON output, the alignment_pct field shows the alignment percentage, and can be used to drive decision making

Operating on only runtime/production issues

The CLI and API output contains two summary objects:

•  "statistics" (CLI), "alignment_counts" (API).
  • These contain summary data for all releases in the alignment
•  "production_statistics" (CLI) "production_counts" (API).
  • These contain summary data for only releases that are included in a production scope, as opposed to development and test dependencies.

Each statistics object includes counts of approved, denied, and newly introduced releases. The CLI-provided objects also calculate a percentage for each.

By looking at production_statistics, users can check to see what issues are in their production dependencies, and potentially ignore acting on issues in development or test dependencies.

Examples using alignment output

These examples use the  jq tool to filter the alignment output.

The following samples will allow you to continue where the denied count for all packages is not 0, or the denied percent of production-scoped packages is less than 10%.

tidelift alignment --json | jq ".statistics.denied_count == 0"
tidelift alignment --json | jq ".production_statistics.denied_percent < 0.1"

Finding newly introduced issues

One of the important things organizations want to ensure is that their applications aren't getting worse. While there is technical debt they may want to address at some point, they want to ensure that no new issues are being introduced.

This can be done by looking at the newly_introduced field on releases and in the summary output. For each release that is new in this alignment, the newly_introduced flag is set to true. newly_introduced counts are also included in the summary outputs.

An organization that wants to take alignment results and file issues for engineering teams can look for just denied releases that have newly_introduced set to true, to catch any new issues that are introduced in the codebase.

How "newly introduced" is calculated

Whether an alignment introduces new dependencies is calculated based on what is called a "baseline alignment".

Baseline alignments are set by the following method:

• If no baseline alignment is set, and an alignment happens on the default branch, that alignment is set as the baseline alignment for future alignments
• If a new alignment happens on the default branch, and there have been no "regressions" (denials in newly introduced releases), the baseline alignment for future alignments is updated to that new scan

An explicit baseline alignment can be set when running tidelift alignment by passing the --baseline-alignment argument. For example, to compare to alignment number 33, pass --baseline-alignment 33.