You can review new features, bug fixes, known issues, and configuration changes for each Project Quay release. Use these notes to plan upgrades and understand changes that affect standalone and OpenShift Container Platform deployments.

About Project Quay

Project Quay is a container registry platform for secure storage, distribution, and governance of containers and cloud-native artifacts. You can deploy it as a standalone component or as an Operator on OpenShift Container Platform.

Project Quay includes the following features and benefits:

  • Granular security management

  • Fast and robust at any scale

  • High velocity CI/CD

  • Automated installation and updates

  • Enterprise authentication and team-based access control

  • OpenShift Container Platform integration

Project Quay is regularly released, containing new features, bug fixes, and software updates. You can upgrade Project Quay for both standalone and OpenShift Container Platform deployments.

Important

Project Quay only supports rolling back, or downgrading, to previous z-stream versions, for example, {producty-n1}.2 → {producty-n1}.1. Rolling back to previous y-stream versions ({producty} → {producty-n1}) is not supported. This is because Project Quay updates might contain database schema upgrades that are applied when upgrading to a new version of Project Quay. Database schema upgrades are not considered backwards compatible.

Downgrading to previous z-streams is neither recommended nor supported by either Operator based deployments or virtual machine based deployments. Downgrading should only be done in extreme circumstances. The decision to rollback your Project Quay deployment must be made in conjunction with the Project Quay support and development teams. For more information, contact Project Quay support.

Additional resources

Project Quay release notes

You can review y-stream and z-stream release information for Project Quay, including new features, bug fixes, and known issues for each version.

RHBA-TBD - Project Quay 5.0.0 release

Project Quay {producty} is available with Clair {clairproductminv}. You can review the advisory, compatibility matrix, and life cycle policy for this release.

Issued TBD

Project Quay release {producty} is now available with Clair {clairproductminv}. The bug fixes that are included in the update are listed in the RHBA-TBD advisory. For the most recent compatibility matrix, see Quay Enterprise 3.x Tested Integrations. For information on the release cadence of Project Quay, see the Project Quay Life Cycle Policy.

Project Quay new features and enhancements

You can review new features and enhancements in Project Quay {producty}.

OIDC superuser group synchronization
  • Project Quay {producty} introduces superuser group synchronization for OIDC-backed deployments, providing feature parity with LDAP_SUPERUSER_FILTER. Two new optional fields, SUPERUSER_GROUP and GLOBAL_READONLY_SUPERUSER_GROUP, are now supported inside any OIDC login service config block. Users in the configured OIDC groups are automatically granted or revoked superuser or global read-only superuser privileges at each login, based on their current OIDC group membership. This feature operates independently of FEATURE_TEAM_SYNCING and does not affect users who are statically listed in the SUPER_USERS configuration field.

Configurable gunicorn worker timeout
  • Project Quay {producty} introduces configurable gunicorn worker timeout settings. Two new config.yaml parameters, GUNICORN_REGISTRY_TIMEOUT and GUNICORN_WEB_TIMEOUT, allow administrators to increase the gunicorn worker timeout beyond the previous hardcoded 30-second default.

    Increasing these values prevents worker termination during long-running operations, including large image pushes, proxy cache blob downloads, and API queries on large organizations with quota enabled. The default values are 300 seconds for the registry process and 60 seconds for the web process. The minimum accepted value for both parameters is 30 seconds and the maximum is 300 seconds.

Robot API tokens (Technology Preview)
  • Project Quay {producty} introduces robot API tokens, which are expiring, scoped credentials that a robot account uses on the management API. Unlike the robot account’s static push and pull token, a robot API token expires after at most 90 days and carries a set of OAuth scopes that limit which management API operations it can perform. You can set the expiry to 7, 30, or 90 days on the console. A robot account can hold several tokens at once, and each one can be revoked separately.

    Create and revoke tokens on the API Tokens tab of a robot account in the v2 UI, or by using the /api/v1/organization/{orgname}/robots/{robot_shortname}/tokens endpoints. Enable the feature with the FEATURE_ROBOT_API_TOKENS configuration field, and cap the number of active tokens per robot with API_TOKEN_MAXIMUM_TOKEN_COUNT.

    Important

    Robot API tokens are a Technology Preview feature in Project Quay {producty}. Technology Preview features are not supported with Red Hat production service-level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using Technology Preview features in production environments. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

Robot federation for the management API (Technology Preview)
  • In Project Quay {producty}, robot federation entries can grant access to the management API as well as to the registry. Each entry accepts an api_scopes field that sets the scopes a federated workload is allowed to request, and a new POST /sts/token endpoint exchanges an external OIDC token for a Project Quay access token carrying those scopes. The exchanged token expires after one hour and cannot be renewed.

    This lets in-cluster automation, such as an operator, a Tekton pipeline, or a GitOps controller, call the Project Quay management API by using its Kubernetes service account token, without a Secret object that holds Project Quay credentials. Matching on issuer and subject is exact string equality; wildcard patterns are not supported. Enable the feature with the FEATURE_ROBOT_API_TOKEN_EXCHANGE configuration field, which requires FEATURE_ROBOT_API_TOKENS.

    Important

    Robot federation for the management API is a Technology Preview feature in Project Quay {producty}. Technology Preview features are not supported with Red Hat production service-level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using Technology Preview features in production environments. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

Red Hat Quay on OpenShift Container Platform new features and enhancements

You can review new features and enhancements for Red Hat Quay on OpenShift Container Platform in {producty}.

Default NetworkPolicy support for Operator-managed components
  • Project Quay {producty} introduces automatic NetworkPolicy management for all Operator-managed components. The Project Quay Operator now creates and reconciles NetworkPolicy objects for each component marked as managed: true in the QuayRegistry CR, providing network isolation without manual policy configuration. Unmanaged components receive no NetworkPolicy restrictions. Default policies are not user-configurable. Quay and Clair retain intentionally broad egress rules to support cloud storage access, registry proxying, and CVE database updates.

Cloud Credential Operator-based AWS STS authentication for Red Hat Quay on OpenShift Container Platform
  • Project Quay {producty} introduces support for AWS STS authentication by using the OpenShift Container Platform Cloud Credential Operator (CCO) and the CredentialsRequest API. On AWS clusters running OpenShift Container Platform 4.14 or later with CCO in Manual mode, administrators can set ROLEARN in the Project Quay Operator Subscription and configure unmanaged S3Storage without static access keys. The Operator creates a CredentialsRequest, validates the CCO-generated AWS profile, and mounts the profile and a projected service account token into the quay-app and quay-mirror pods. The AWS SDK in Project Quay exchanges the projected token for temporary AWS credentials and refreshes them before expiration. If an applicable S3Storage entry contains static AWS credentials while ROLEARN is set, the Operator blocks rollout with the ConflictingCredentials reason.

Operator-managed read-only mode

With Project Quay {producty}, the Project Quay Operator supports an Operator-managed read-only lifecycle for application-consistent backups. Previously, enabling read-only mode required manually creating service keys, modifying the configuration secret, and scaling the Operator deployment. Now, administrators can set spec.readOnly: true on the QuayRegistry custom resource to transition the registry into read-only mode. The Operator handles service key creation and rotation, configuration rendering, deployment restarts, and HPA management automatically.

Project Quay configuration fields updates and changes

You can review configuration fields that are new or changed in Project Quay {producty}.

OIDC superuser group synchronization configuration fields

The following configuration fields are added to the OIDC login service config block to support superuser group synchronization for OIDC-backed deployments.

Field Type Description

SUPERUSER_GROUP

String

Specifies the unique identifier of the OIDC group whose members are granted superuser privileges at login. Users are dynamically added to or removed from the superuser role on each login based on their current OIDC group membership. The identifier format depends on your OIDC provider; for example, Microsoft Entra ID uses a group object ID (UUID), while Keycloak uses a group name. Users listed in SUPER_USERS are never deregistered. This field is optional.

GLOBAL_READONLY_SUPERUSER_GROUP

String

Specifies the unique identifier of the OIDC group whose members are granted global read-only superuser privileges at login. Members of this group can view all repositories regardless of visibility. The identifier format depends on your OIDC provider. This field is optional.

Gunicorn worker timeout configuration fields

The following configuration fields allow you to tune the gunicorn worker timeout for the registry and web processes. Previously, the timeout was hardcoded at 30 seconds, which caused worker termination during legitimate long-running operations such as large image pushes, proxy cache blob downloads, and API queries on large organizations with quota enabled.

Field Type Description

GUNICORN_REGISTRY_TIMEOUT

Integer

Specifies the worker timeout, in seconds, for the gunicorn-registry process. The minimum value is 30. The maximum value is 300. Defaults to 300.

GUNICORN_WEB_TIMEOUT

Integer

Specifies the worker timeout, in seconds, for the gunicorn-web process. The minimum value is 30. The maximum value is 300. Defaults to 60.

Operator-managed read-only mode configuration fields

The following internal configuration field is added to support the Operator-managed read-only lifecycle. This field is set automatically by the Project Quay Operator and should not be modified manually.

INSTANCE_SERVICE_KEY_IMPORT_FROM_FILES

Boolean

When set to true, the instance service key is imported from the Operator-mounted .kid and .pem files (INSTANCE_SERVICE_KEY_KID_LOCATION and INSTANCE_SERVICE_KEY_LOCATION) instead of being generated at boot. The Operator sets this field to true only when the read-only Secret is mounted. Defaults to False. This field is for internal use and is managed by the Operator.

Robot API token configuration fields

The following configuration fields control robot API tokens and federated token exchange for the management API. Both features are Technology Preview in Project Quay {producty} and are disabled by default.

Field Type Description

FEATURE_ROBOT_API_TOKENS

Boolean

When set to true, robot accounts can hold expiring, scoped qro_ tokens for the management API, and the token lifecycle endpoints are available. Defaults to false.

FEATURE_ROBOT_API_TOKEN_EXCHANGE

Boolean

When set to true, the POST /sts/token endpoint is available, which exchanges an external OIDC token for a management API access token. Requires FEATURE_ROBOT_API_TOKENS. Defaults to false.

API_TOKEN_MAXIMUM_TOKEN_COUNT

Integer

Specifies the maximum number of active robot API tokens that a single user or robot account can hold. Set to null to remove the limit. Defaults to 20. Creating a token beyond the token limit can result in a 400 error that states Token limit reached.

API endpoint enhancements

The following API endpoints were added in Project Quay {producty}

Service key status endpoint

Project Quay {producty} adds the following keyserver endpoint to support the Operator-managed read-only lifecycle:

Method Endpoint Description

GET

/keys/services/<service>/keys/<kid>/status

Returns key identity, operator-management state, and expiration metadata for a given service key.

Unlike the existing GET /keys/services/<service>/keys/<kid> endpoint, this endpoint returns 200 for expired and unapproved keys, so the Project Quay Operator can inspect key metadata regardless of key state. The operator_managed field is true when the key was created by the Operator. The expiration_date field is formatted as RFC 3339 UTC.

This endpoint is used internally by the Operator during the PreparingKey and ExitingReadOnly lifecycle phases and is not intended for direct use by registry administrators. You can review API enhancements in Project Quay {producty}.

Robot API token endpoints

The following endpoints manage the lifecycle of robot API tokens. They require the FEATURE_ROBOT_API_TOKENS configuration field. Equivalent endpoints exist under /api/v1/user/robots/{robot_shortname} for robot accounts that belong to a user.

Table 1. Robot API token endpoints
Endpoint Description

GET /api/v1/organization/{orgname}/robots/{robot_shortname}/mintable-scopes

Lists the scopes that the calling user can grant to a token for this robot account.

POST /api/v1/organization/{orgname}/robots/{robot_shortname}/tokens

Creates a robot API token. The token value is returned only in this response.

GET /api/v1/organization/{orgname}/robots/{robot_shortname}/tokens

Lists the robot account’s tokens without their values.

DELETE /api/v1/organization/{orgname}/robots/{robot_shortname}/tokens/{token_uuid}

Revokes a robot API token. Revocation takes effect immediately.

Token exchange endpoint

The following endpoint requires the FEATURE_ROBOT_API_TOKEN_EXCHANGE configuration field.

Table 2. Token exchange endpoint
Endpoint Description

POST /sts/token

Exchanges an external OIDC token for a Project Quay management API access token, according to the robot federation entry that matches the token’s iss and sub claims. The issued token expires after one hour and cannot be renewed.

Robot federation endpoint changes

The /api/v1/organization/{orgname}/robots/{robot_shortname}/federation endpoints now accept an api_scopes field on each federation entry, which sets the management API scopes that a federated workload is allowed to request. The audiences array on each entry is now persisted and is validated against the aud claim of the presented token.

Project Quay bug fixes

You can review bug fixes included in Project Quay {producty}.

The following issues were fixed with Project Quay {producty}:

  • PROJQUAY-6016. Previously, no error notification was displayed in the UI when an invalid robot account description was entered. With this update, proper validation and error feedback are now shown when the robot account description input is invalid.

  • PROJQUAY-6125. Previously, the Project Quay UI did not validate tag names when a new tag was created, allowing invalid tag names to be submitted without warning. With this update, tag name input is validated in the UI and users receive feedback when an invalid tag name is entered.

  • PROJQUAY-7098. Previously, using an email address when creating a repository notification for the first time caused an unexpected error alert in the UI. With this update, the UI correctly handles email-based notification creation without displaying spurious error messages.

  • PROJQUAY-8202. Previously, authorizing OAuth applications through the CLI no longer functioned correctly. With this update, CLI-based OAuth application authorization works as expected.

  • PROJQUAY-8272. Previously, nested indexes in the Project Quay database could cause query performance issues. With this update, nested indexes are corrected to improve database query performance.

  • PROJQUAY-9038. Previously, the notification bell badge in the Project Quay UI displayed a maximum count of 5, even when more unread notifications were present. With this update, the badge count correctly reflects the actual number of unread notifications.

  • PROJQUAY-9330. Previously, when a tag name was the same as the repository name, the repository name was missing from the breadcrumb navigation in the UI. With this update, the breadcrumb correctly displays the repository name in all cases.

  • PROJQUAY-9692. Previously, deleting an organization from the superuser admin panel did not generate an audit event. With this update, organization deletions are properly recorded in the audit log.

  • PROJQUAY-11177. Previously, changing an organization quota limit using the v2 UI returned a quota update error, Unauthorized error even when the user had the necessary permissions. With this update, quota limit changes via the v2 UI succeed for users with appropriate permissions.

  • PROJQUAY-11202. Previously, a routing bug in the v2 UI caused malformed API requests when an organization name contained the word organization. With this update, organization names containing organization are handled correctly in the UI routing layer.

  • PROJQUAY-11278. Previously, when RadosGWStorage was configured with a region_name, the value was not validated at startup, which could result in silent misconfiguration. With this update, RadosGWStorage validates region_name at startup and reports configuration errors immediately.

  • PROJQUAY-12113. Previously, the Project Quay UI did not display the cosign shield icon for images that had been signed with cosign. With this update, the shield icon is correctly displayed for cosign-signed images.

  • PROJQUAY-12190. Previously, repository mirroring did not work when both the source and destination registries were the same Project Quay instance. With this update, repository mirroring functions correctly when the source and destination registries are the same.

  • PROJQUAY-12223. Previously, the referrers cache was not invalidated when a manifest was pushed, causing stale referrers to be returned. With this update, the referrers cache is properly invalidated on manifest push, ensuring accurate referrers lists.

  • PROJQUAY-12269. Previously, using the /search function in the new UI caused the interface to break. With this update, the search function works correctly in the v2 UI.

  • PROJQUAY-12311. Previously, the proxy cache failed for large blobs due to an asynchronous download issue. With this update, the proxy cache correctly handles large blobs by resolving the asynchronous download race condition.

  • PROJQUAY-12443. Previously, the /v1/bootstrap/renew endpoint for the programmatic OAuth token provisioning feature did not properly sanitize input. With this update, the endpoint correctly sanitizes input to prevent unexpected behavior.

  • PROJQUAY-12447. Previously, Project Quay returned stale caching results on Operator-based deployments. With this update, caching is correctly invalidated on Operator-based deployments, ensuring fresh results are returned.

  • PROJQUAY-12456. Previously, the Project Quay new UI help dropdown did not display build version information. With this update, the help dropdown shows current build and version information.

  • PROJQUAY-12538. Previously, the tags/list cache was not invalidated when a manifest was deleted, causing stale tag listings to be returned. With this update, the tags/list cache is properly invalidated on manifest deletion.

  • PROJQUAY-12557. Previously, orphaned multipart uploads were not cleaned up during blob cleanup, leading to storage accumulation over time. With this update, orphaned multipart uploads are removed as part of the blob cleanup process.

  • PROJQUAY-12773. Previously, Project Quay generated excessive DNS query bursts that could saturate local DNS resolvers. With this update, DNS query behavior is optimized to prevent resolver saturation.

  • PROJQUAY-12833. Previously, the repository mirroring Server-Side Request Forgery (SSRF) mitigation required pod-local DNS resolution, which broke mirroring in disconnected environments that route traffic through an HTTPS_PROXY. With this update, repository mirroring works correctly in disconnected environments that use an HTTPS_PROXY.

  • PROJQUAY-13363. Previously, Project Quay ran expensive quota checks even when quota was not configured or required, adding unnecessary overhead to registry operations. With this update, quota checks are skipped when not needed, improving overall registry performance.

  • PROJQUAY-13364. Previously, the expiry time for blob and temporary tags was too short, causing premature cleanup of objects still in use. With this update, the blob and temporary tag expiry time is increased to prevent premature deletion.

  • PROJQUAY-13371. Previously, registry blob commits blocked for 25–60 seconds due to a double blocking lock acquisition in with_blob_lock_or_fallback, causing significant latency during concurrent push operations. With this update, the locking behavior is corrected to eliminate the contention and reduce blob commit latency.

  • PROJQUAY-13405. Previously, retrieving archived build logs stored in Google Cloud Storage (GCS) returned a 500 error due to a zlib incorrect header check error when GCS served an already-decoded object. With this update, archived build logs are retrieved correctly from GCS storage.

  • PROJQUAY-13429. Previously, authentication timeouts occurred with the OIDC backend in large environments due to inefficient token validation. With this update, OIDC authentication is optimized to prevent timeouts in large-scale deployments.

  • PROJQUAY-13519. Previously, blob GET requests through the storage proxy (FEATURE_PROXY_STORAGE) were gzip-encoded by nginx, which removed the Content-Length header and caused client compatibility issues. With this update, blob responses through the storage proxy are returned with the correct encoding and Content-Length header.

  • PROJQUAY-13543. Previously, Project Quay application and mirror pods did not roll out when the AWS STS ROLEARN was changed in the configuration. With this update, changing ROLEARN in the AWS STS configuration triggers the expected pod rollout.

  • PROJQUAY-13715. Previously, the Project Quay 5.0 Operator displayed the upstream community project logo instead of the Red Hat downstream logo. With this update, the Operator correctly displays the Red Hat Project Quay branding.

  • PROJQUAY-13716. Previously, the header search box in the Project Quay 5.0 UI overlapped the Project Quay logo. With this update, the header layout is corrected so the search box and logo do not overlap.

  • PROJQUAY-13780. Previously, the Project Quay 5.0 Change Log page displayed v3.11.0 release notes instead of v5.0.0 release notes. With this update, the Change Log page correctly displays the v5.0.0 release notes.

  • PROJQUAY-13783. Previously, the Project Quay 5.0 robot API token name field lacked input validation for length and character restrictions. With this update, robot API token names are validated to enforce length and character restrictions.

  • PROJQUAY-13784. Previously, Project Quay 5.0 robot API tokens did not generate per-token audit trail entries for security-relevant operations. With this update, security-relevant operations performed with robot API tokens are recorded in the audit log.

  • PROJQUAY-13785. Previously, the last_accessed field for robot accounts showed Never even when the robot account was actively used via API tokens. With this update, last_accessed is correctly updated when a robot account is accessed via API tokens.

  • PROJQUAY-13786. Previously, robot API token GET endpoints did not grant read access to global readonly superusers, preventing them from inspecting token metadata. With this update, global readonly superusers can access robot API token GET endpoints as expected.

  • PROJQUAY-13787. Previously, the Robot API Tokens tab in the Project Quay 5.0 UI displayed tokens as a flat text list instead of a structured table layout. With this update, the Robot API Tokens tab uses a structured table layout for improved readability.

  • PROJQUAY-13788. Previously, a security regression in Project Quay 5.0 caused robot API tokens to bypass the ROBOTS_DISALLOW configuration policy. With this update, the ROBOTS_DISALLOW policy is correctly enforced for robot API tokens.

  • PROJQUAY-13930. Previously, the Superuser Usage Logs table in the Project Quay 5.0 UI had a truncated date column and was missing additional columns. With this update, the Superuser Usage Logs table displays all columns correctly.

  • PROJQUAY-13942. Previously, the Project Quay 5.0 UI Create Team wizard Review step incorrectly marked optional fields as required. With this update, the Create Team wizard correctly distinguishes between required and optional fields.

  • PROJQUAY-13943. Previously, users with GLOBAL_READONLY_SUPER_USERS permissions could not create repositories or generate OAuth tokens in their own namespace or organization. With this update, GLOBAL_READONLY_SUPER_USERS can create repositories and generate OAuth tokens in their own namespaces and organizations as expected.

  • PROJQUAY-13991. Previously, the Robot API Tokens tab in the Project Quay 5.0 UI showed mutation controls (such as create, delete, and revoke) to global readonly superusers, who should only have read access. With this update, mutation controls are hidden from global readonly superusers on the Robot API Tokens tab.

  • PROJQUAY-14041. Previously, the Project Quay 5.0 Quay Bridge Operator displayed an incorrect logo and icon in OperatorHub. With this update, the Quay Bridge Operator displays the correct branding in OperatorHub.

Project Quay feature tracker

You can track Project Quay feature availability across recent releases, including Technology Preview status, and review platform support for IBM Power, IBM Z, and IBM LinuxONE.

Some features available in previous releases have been deprecated or removed. Deprecated functionality is still included in Project Quay, but is planned for removal in a future release and is not recommended for new deployments. For the most recent list of deprecated and removed functionality in Project Quay, refer to Table 1.1. Additional details for more fine-grained functionality that has been deprecated and removed are listed after the table.

Table 3. Features tracker
Feature Quay 5 Quay 3.18 Quay 3.17

Cloud Credential Operator-based AWS STS authentication

General Availability

-

-

Robot API tokens

Technology Preview

-

-

Robot federation for the management API

Technology Preview

-

-

Microsoft Entra ID v2 token and multi-issuer OIDC support

General Availability

General Availability

-

Configurable gunicorn worker timeout

General Availability

-

-

Default NetworkPolicy support for Operator-managed components

General Availability

-

-

OIDC superuser group synchronization

General Availability

-

-

Programmatic OAuth token provisioning

Technology Preview

Technology Preview

-

OpenShift Container Platform cluster TLS security profile inheritance & Post-Quantum Cryptography (PQC) readiness

General Availability

General Availability

-

Sparse manifest support for multi-architecture filtering

General Availability

General Availability

General Availability

Immutable tags overview

General Availability

General Availability

General Availability

Proof Key for Code Exchange support for OIDC

General Availability

General Availability

General Availability

IBM Power, IBM Z, and IBM® LinuxONE support matrix
Table 4. list of supported and unsupported features
Feature IBM Power IBM Z and IBM® LinuxONE

Allow team synchronization via OIDC on Azure

Not Supported

Not Supported

Backing up and restoring on a standalone deployment

Supported

Supported

Clair Disconnected

Supported

Supported

Geo-Replication (Standalone)

Supported

Supported

Geo-Replication (Operator)

Supported

Supported

IPv6

Not Supported

Not Supported

Migrating a standalone to operator deployment

Supported

Supported

Mirror registry

Supported

Supported

Quay config editor - mirror, OIDC

Supported

Supported

Quay config editor - MAG, Kinesis, Keystone, GitHub Enterprise

Not Supported

Not Supported

Quay config editor - Red Hat Quay V2 User Interface

Supported

Supported

Quay Disconnected

Supported

Supported

Repo Mirroring

Supported

Supported