Overview

Integrations that export Aqua container image data and source code repository data often attempt to join the two datasets on a shared field such as container_image_repo, product_name, or labels. Many images legitimately have no matching Supply Chain Security repository record, and labels from the two APIs are not interchangeable.


This article explains what each API surface represents, why one-to-one mapping is not always possible, and practical approaches for reporting and ownership metadata.


Symptoms

  • Container Images API (/api/v2/images or related endpoints) returns container_image_repo values that do not match any product_name in the Source Code Repositories API
  • Examples of unmatched paths: internal Artifactory namespaces, ML pipeline image paths, or third-party images (dpage/pgadmin4, and similar)
  • Attempts to join on labels fail because label keys and semantics differ between resources
  • Expectation that every scanned image has a linked SCM repository entity in Aqua

Understanding the Two Data Domains

Container images (runtime / registry artifacts)

  • Represent built container artifacts discovered via registry integration, CI/CD, or host/runtime scanning
  • Image labels come from the image itself (for example LABEL instructions in a Dockerfile or OCI config)
  • container_image_repo reflects registry/repository path naming at scan time; it is not guaranteed to equal an SCM repository name

Source code repositories (Supply Chain Security)

  • Represent SCM integrations (GitHub, GitLab, Azure DevOps, and similar) onboarded under Supply Chain Security
  • Repository labels are resource metadata at the SCM or Aqua repository entity level (organization, custom properties, integration tags)
  • Managed as distinct entities from container images


There is no universal API field that always links a container image row to a source code repository row. Images built outside onboarded SCM repos, pulled from public registries, or promoted through rename pipelines will not have a repository counterpart in Aqua.


Why Labels Cannot Be Used as a Join Key


SourceLabel meaningExample
Code Repositories APISCM / repository resource metadataGitHub org tag, repo-level custom property
Container / Image APIImage build-time OCI labelsversion, maintainer, build IDs


These label namespaces are independent. Matching keys by coincidence does not establish provenance. Using labels as a join key produces false matches and misses legitimate images.


1. Treat unmatched images as expected

Maintain a classification for images with no SCM entity:

  • Third-party / vendor images
  • Images built outside Supply Chain Security coverage
  • Legacy images predating SCM onboarding
  • Renamed or forked registry paths

2. Establish ownership outside automatic correlation

For governance reporting, use one or more of:

  • Registry and namespace rules mapped to teams in your CMDB
  • OCI labels applied at build time (owner, service, git.repo) — consumed from the image API, not from Code Repositories API
  • CI/CD metadata pushed via Aqua labels or assurance policies at build
  • Manual repository onboarding in Supply Chain Security when source repos exist but are not yet integrated

3. Align naming where you control both sides

When your pipeline owns registry path and SCM repo, standardize naming conventions (for example registry.example.com/<org>/<repo> mirrors Git repo path) in build automation—not via post-hoc API joins on Aqua fields alone.

4. Use Supply Chain Security features for code-to-build linkage

Where Aqua Supply Chain Security is deployed, link build pipelines and repositories at integration time rather than inferring relationships from container scan exports alone.


Important Considerations

  • Unmatched rows in a CSV export do not necessarily indicate missing Aqua data; they often indicate no SCM entity exists for that image lifecycle.
  • Renamed repositories in Git or registry path changes break naive string equality joins—maintain a mapping table in your analytics layer if historical correlation is required.


Verification and Monitoring

  • Document count of images by category: SCM-linked (via your conventions), third-party, unmatched
  • Validate sample joins manually before automating dashboards
  • After onboarding new SCM integrations, re-export repository inventory and refresh mappings


Platform Coverage

ItemDetail
ComponentServer API, Supply Chain Security
APIsContainer images, source code repositories
PlatformSaaS and self-hosted