ONAP Release Mapping Tool

ONAP release component mapping tool — generates definitive manifests of Gerrit projects and Docker images comprising an ONAP release.

Results / GitHub Pages

https://modeseven-lfit.github.io/onap-release-mapping-tool/

Overview

onap-release-map follows an OOM-first strategy: it starts from the OOM Helm umbrella chart, recursively resolves every sub-chart and Docker image reference, then maps those images back to their source Gerrit repositories. Further collectors enrich the manifest with data from the ONAP release management repository, JJB CI definitions, and the Gerrit REST API.

The tool produces a versioned, self-describing JSON artifact that captures the complete state of the analysis, including:

• Every Gerrit repository participating in the release
• Every Docker image and tag referenced by OOM Helm charts
• Image-to-repository mappings with provenance metadata
• Release management status for each project
• CI/CD pipeline correlation from JJB definitions
• Data source provenance and execution statistics

Features

• OOM Helm chart parsing — recursively walks the OOM umbrella chart to extract all Docker image references and sub-chart dependencies
• Gerrit project discovery — maps Docker images back to their source Gerrit repositories via configurable mapping rules and API queries
• JJB CI correlation — scans Jenkins Job Builder definitions to link repositories with their CI pipeline configurations
• Release management status — ingests the relman repos.yaml to track per-project release participation and lifecycle state
• Nexus Docker registry validation — verifies that every image:tag pair in the manifest actually exists in the ONAP Nexus3 registry
• Manifest diffing — compares two manifests to identify added, removed, and changed repositories or images across releases
• Repository filtering — excludes infrastructure repos (e.g. All-Projects, All-Users, .github) and read-only/archived projects from reports by default, with full CLI override support
• Multi-format export — converts manifests to YAML, CSV, Markdown, or a flat Gerrit repository list
• JSON Schema validation — every manifest conforms to a versioned JSON Schema, enabling downstream tooling to verify artifacts
• GitHub Action — composite action for CI/CD integration that clones OOM, runs discovery, and uploads the manifest as a build artifact

Installation

Install from PyPI:

pip install onap-release-map

Install from source using uv:

git clone https://github.com/modeseven-lfit/onap-release-mapping-tool.git
cd onap-release-mapping-tool
uv sync

Development setup with all extras:

uv sync --group dev

Quick Start

# Clone the OOM repository
git clone --depth 1 https://gerrit.onap.org/r/oom

# Generate the release manifest
onap-release-map discover --oom-path ./oom

The tool writes the manifest to ./output/manifest.json by default.

Commands

discover

The primary command. Parses OOM Helm charts and runs selected collectors to build the release manifest.

# Basic discovery with OOM charts
onap-release-map discover --oom-path ./oom

# Full discovery with all collectors
onap-release-map discover \
  --oom-path ./oom \
  --collectors oom,gerrit,relman,jjb \
  --repos-yaml ./releases/repos.yaml \
  --jjb-path ./ci-management/jjb

# Custom output location and format
onap-release-map discover \
  --oom-path ./oom \
  --output-dir ./results \
  --output-format all

diff

Compare two manifests and report differences. Useful for tracking changes between releases or between successive builds.

# Text diff to stdout
onap-release-map diff manifest-old.json manifest-new.json

# Markdown diff written to file
onap-release-map diff \
  manifest-old.json manifest-new.json \
  --output-format md \
  --output changes.md

export

Convert a JSON manifest to other formats for consumption by downstream tools and reports.

# Export to YAML
onap-release-map export manifest.json --format yaml --output manifest.yaml

# Export a flat list of Gerrit repository names
onap-release-map export manifest.json --format gerrit-list

# Export Docker images as CSV (use --images flag)
onap-release-map export manifest.json --format csv --output images.csv

verify

Check that every Docker image:tag pair in a manifest exists in the ONAP Nexus3 Docker registry. Returns a non-zero exit code if any images are missing.

# Verify all images against the default Nexus registry
onap-release-map verify manifest.json

# Use a custom registry with more workers
onap-release-map verify manifest.json \
  --nexus-url https://nexus3.example.org \
  --workers 8

schema

Print the JSON Schema that all manifests conform to. Useful for integrating with validation tools or generating documentation.

# Print schema to stdout
onap-release-map schema

# Save schema to a file
onap-release-map schema > manifest-v1.schema.json

version

Print version information for the tool and the Python runtime.

onap-release-map version

Configuration

The tool ships with a default configuration at configuration/default.yaml. You can override it with the --config flag on the discover command.

Key configuration sections:

# ONAP Gerrit server
gerrit:
  url: "https://gerrit.onap.org/r"
  timeout: 30
  max_retries: 3

# OOM repository defaults
oom:
  default_branch: "master"
  exclude_dirs:
    - "argo"
    - "archive"

# Repository filtering — repos excluded from reports
filter_repos:
  - ".github"
  - "All-Projects"
  - "All-Users"
  # JJB CI job definitions for the ONAP Jenkins instance, not runtime
  # release content
  - "ci-management"

# Exclude read-only/archived Gerrit projects from reports
exclude_readonly: true

# Nexus registry for validation
nexus:
  url: "https://nexus3.onap.org"
  timeout: 10
  max_retries: 3
  concurrent_workers: 4

The filter_repos list and exclude_readonly flag control which repositories appear in exported reports. Infrastructure repositories (.github, All-Projects, All-Users) and CI-only repositories (ci-management, which contains JJB CI job definitions for the ONAP Jenkins instance) do not appear by default, nor do read-only/archived Gerrit projects. Override either setting via CLI flags (--filter-repos, --no-exclude-readonly) or a custom config file.

GitHub Action

The tool is available as a composite GitHub Action for CI/CD pipelines. It automatically clones OOM (or uses a pre-cloned checkout), runs discovery, and uploads the manifest as an artifact.

name: Generate ONAP Release Manifest
on:
  workflow_dispatch:

jobs:
  manifest:
    runs-on: ubuntu-latest
    steps:
      - name: Generate manifest
        uses: modeseven-lfit/onap-release-mapping-tool@main
        id: release-map
        with:
          oom-branch: "master"
          release-name: "Rabat"
          collectors: "oom,gerrit"
          output-format: "all"

      - name: Show results
        run: |
          echo "Repositories: ${{ steps.release-map.outputs.total-repositories }}"
          echo "Images: ${{ steps.release-map.outputs.total-images }}"

Output Formats

HTML Report Features

The HTML export (export --format html) produces a single dark-themed HTML report hosted on GitHub Pages. CDN-hosted Simple-DataTables assets supply interactive table behaviour and styling, so the report requires network access for full functionality.

Interactive Tables

Report tables include search/filter and column sorting powered by Simple-DataTables:

• Search/filter — a search box above each table for real-time filtering
• Column sorting — click any column header to sort ascending/descending

Tables with fewer than three rows skip interactivity, as search and sort add no value to small tables.

State Indicators

The Repositories table uses emoji in the State column to convey release scope at a glance:

Totals Summary

The Markdown and HTML reports include a Totals subsection directly below the Repositories table. This table provides a numerical count of repositories in each state category alongside the emoji key:

The table omits rows with a zero count automatically. When repository filtering is active (e.g. --exclude-readonly), the totals reflect the filtered set.

The tool resolves state by cross-referencing four data sources:

1. OOM discovery — repos found in OOM Helm charts are definitively in the release (✅)
2. Relman included_in — the release management repos.yaml tracks which releases each project participates in
3. READ_ONLY status — archived projects are definitively not in the release (📦)
4. Parent project detection — Gerrit parent projects whose children ship in the release receive the parent indicator (☑️)

Development

Install development dependencies:

uv sync --group dev

Run the test suite:

uv run pytest tests/

Run linting and formatting checks:

uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

Run type checking:

uv run mypy src/

This repository uses pre-commit hooks to enforce code quality on every commit. Install them with:

pre-commit install

The hooks run gitlint, ruff, mypy, reuse (SPDX license compliance), yamllint, actionlint, and interrogate (docstring coverage).

Documentation

Full documentation is available on Read the Docs.

License

This project uses the Apache License 2.0. See the LICENSE file for details.