1. Feature Overview (Goal summary)

This feature adds support for arbitrary key-value metadata ("Labels") at both the Organization and Repository levels.

2. Goals (Expected user outcomes)

• Identify Ownership & Communication: Users can tag Organizations or Repositories with contact info (e.g., owner=team-platform, slack=#dev-alerts, contact=jane.doe).  This allows other users to quickly identify and reach the appropriate team lead, reducing communication delays.  

• Granular Organization: Group resources horizontally across the registry (e.g., filtering all Organizations tagged business-unit=finance).

• Enhanced Automation: DevOps teams can target resources programmatically (e.g., "enforce retention policies on all repos where env=dev").

• Ecosystem Consistency: Aligns Quay with standard Kubernetes resource management.

3. Background

Currently, Quay relies on hierarchical structures to group content.  Users lack a standardized way to attach "out-of-band" information, e.g., ownership details, cost centers, or environment classification, directly to the resource. 

This feature will implement a labeling system standard in the ecosystem (similar to Kubernetes labels), allowing users to attach metadata via the UI and API to both Organizations and Repositories.

Rationale for prioritization:

• Customer Value: Addresses critical friction in large enterprises where identifying the "owner" of a stale repository or organization is difficult.  This enables self-service lookup of contact information directly within the UI.

• Feature Parity: AWS ECR, Azure ACR, Google Artifact Registry, and Docker Hub support tagging at the resource level.  Lack of this feature allows competitors to offer better governance and cost-allocation reporting tools.

• Strategic Alignment: Aligns with "Ops Excellence" by reducing the manual overhead of tracking resource ownership.

• Technical Feasibility: This is a standard metadata management feature common in modern platforms (e.g., Kubernetes labels) and aligns well with the current "Image/Tag Level Labeling" in the PatternFly UI, where such metadata can be surfaced effectively.

4. Requirements (Acceptance criteria)

1) Scope & Permissions

• Repositories: Managed by Repository Admins.
• Organizations: Managed by Organization Admins.
  • Note: To address security concerns, SuperUsers can view all labels, but standard RBAC applies for creation/editing.

2) Validation rules (Alignment: Kubernetes / RFC 1123)

To ensure future compatibility with the QuayRepository CRD and Kubernetes operators, validation should mirror Kubernetes label syntax:

• ‘Key’/‘Value’ constraints:
  • Max length: 63 characters (per segment).
  • Allowed characters: Alphanumeric ([a-z0-9A-Z]), dashes (-), underscores (_), and dots (.).
  • Prefix support: Keys may optionally be prefixed by a DNS subdomain (max 253 chars) followed by a slash / (e.g., quay.io/managed-by).
  • Formatting: Must begin and end with an alphanumeric character.

• Quantity limit:
  • Max labels per repository: 64. (Matches Google Artifact Registry standard).

3) Backend / API

• Schema: Both Organization and Repository must support a labels field.

• Uniqueness: Keys must be unique per repository. Adding a label with an existing key overwrites the previous value.

• CRUD Endpoints (Organizations):
  • GET/POST/DELETE /api/v1/organization/{org}/labels

• CRUD Endpoints (Repositories):
  • GET/POST/DELETE /api/v1/repository/{repo}/labels

• Search/Filter:
  • Repository Discovery API (GET /api/v1/repository) accepts label_selector.
  • Organization List API accepts label_selector.

4) Frontend / UI (PatternFly)

• Organization View: Display labels in the Organization Settings and the Organization Dashboard header.

• Repository View: Display labels in the Repository Header and Settings tab.

• Component: Use the standard PatternFly Label Group component to display metadata.
• Interaction/UX:
  • "Add Label" modal should validate input in real-time against the regex rules defined above.
  • "Add Label" modal reuses the same PatternFly component for both Repos and Orgs.
  • Clicking a label on a repository should trigger a filter of the repository list for that label key/value pair.

5. Documentation considerations

• API Docs: Update OpenAPI definition to include the new Label endpoints and the new query parameters for repository searching.

• User guide:
  • Document the use of labels for ownership (e.g., "We recommend adding contact or owner labels to all Organizations to facilitate internal communication").

• • Update the "Repository Management" section to explain best practices for using labels (e.g., differentiating between architectural labels vs. ownership labels).