Overview

GitHub Container Registry (GHCR) is now supported as a dedicated registry integration type within the Aqua platform. This provides behavior consistent with Docker Hub and other native registry integrations, with improved authentication boundary handling for automated workflows.

This feature is available as part of the U14 release.

What is changing

Today, customers can connect GHCR using the generic Docker v1/v2 registry integration. While image scanning and registry access function correctly, automated workflows such as Auto-pull do not consistently respect authentication boundaries — specifically, public images may be pulled even when credentials are configured.

With this enhancement, GHCR is supported as a first-class registry integration providing:

  • Repository discovery
  • Tag listing
  • Manual image pull
  • Auto-pull workflows
  • API-based scan initiation
  • Scheduled rescans
  • Policy evaluation and deployment workflows
  • CLI-based scanning workflows
  • Connectivity validation (Test Connection)

The integration supports configurable authentication modes, including authenticated access using GHCR-supported credentials. Registry operations and automated workflows honor the permissions associated with the configured credentials.

Why this change is being made

Product teams are increasingly transitioning to GitHub CI/CD. The generic Docker registry workaround creates operational friction:

  • Limited visibility of scan results — developers must log into the Aqua portal to review findings instead of using streamlined local outputs
  • Remote scan integration issues — when integrating via generic Docker registry, Aqua may pull all public images from GitHub, including repositories that do not belong to the customer, creating noise and confusion

A native GHCR integration streamlines workflows and ensures automated operations respect credential boundaries.

Customer impact

This enhancement introduces a new registry integration type and does not impact customers who do not use GitHub Container Registry.

Known limitations

  • Public repositories: Not discovered via auto-pull catalog; auto-pull targets private images visible to the credentials. Full repository path required (for example, owner/repository or owner/repository:tag) for manual search. Partial search is not supported.
  • GitHub Enterprise Server (GHES): Not supported.
  • Max 100 orgs per PAT: If the user belongs to more than 100 organizations, Aqua scans container packages from 100 organizations only.

Scanner compatibility

Scenario

Expected result

New Console + new Scanner (GHCR build)

GHCR registry scan / CI/CD scan succeeds

New Console + old Scanner (no GHCR)

GHCR scan fails with invalid registry type: 18

Old Console + old Scanner

GHCR integration N/A

Scanner upgrade to U14 is required. Old scanners will fail with: failed to get global options: failed to get image qualified name: invalid registry type: 18. This is expected and does not support backward compatibility.

Required customer action

No action is required for customers who do not use GitHub Container Registry.

Customers planning to use GHCR should:

  • Configure GHCR using the new dedicated registry integration type when it becomes available
  • Upgrade all scanners to U14
  • Review existing GHCR integrations currently configured via Docker v1/v2 and evaluate migration to the native GHCR integration
  • Validate that configured GHCR credentials have the necessary permissions for repository discovery, image access, and automated workflows
  • Review Auto-pull configurations to ensure expected repositories are accessible through the configured credentials
  • Update internal operational documentation and onboarding procedures, if applicable

Because scan requests are distributed across available scanners, mixed scanner versions may experience inconsistent scanning behavior. Begin using this feature only after all scanners have been upgraded.

Frequently Asked Questions

Q: Do I need to change my existing GHCR setup?

A: No immediate change is required, but customers using the generic Docker v1/v2 integration should evaluate migrating to the native GHCR integration for improved Auto-pull behavior and credential boundary handling.

Q: Why does scanning fail with invalid registry type: 18?

A: This indicates scanners have not been upgraded to a U14 version that supports the GHCR integration type.

Q: Are public GHCR repositories auto-discovered?

A: No. Auto-pull targets private images visible to the configured credentials. Public repositories are not discovered via the auto-pull catalog.

Q: Is GitHub Enterprise Server supported?

A: No. GHES is not supported in this release.