Quay
Quay (Red Hat's registry, available as quay.io SaaS or self-hosted) is structured around organizations that own repositories. Robot accounts are the primary auth primitive and are scoped per-organization — never per-repository in the way Harbor robots are.
Auth options
| Method | When to use | HarborGuard fields |
|---|---|---|
| Robot account | Recommended; per-organization | Username = <org>+<robotname>, Password = robot token |
| OAuth application token | App-issued, broader scope | Username = $oauthtoken, Password = the OAuth token |
| Username + password | Limited; not for org-scoped access | Standard fields |
| Encrypted CLI password | When account uses external auth (LDAP/OIDC) | From Quay → Account → Generate Encrypted Password |
The wizard auto-detects quay.io as Quay. Self-hosted Quay (quay.example.com) needs the provider set manually.
Add the registry
- Registries → Connect Registry.
- Registry URL —
quay.io(SaaS) or your self-hosted host. - Cloud mode: enter the robot's full prefixed username and the robot token.
- Save.
The robot's + separator is part of the username (acme+harborguard-reader, not acme/harborguard-reader). HarborGuard does not transform it — paste exactly what Quay shows.
Required permissions
In the org's Robot Accounts tab, give the robot Read on each repository it should scan, or Read at the org/team level for blanket access. Repositories with no permission grants are invisible — Quay's /v2/_catalog reflects only what the robot can see.
For OAuth applications:
- Scope: View all visible repositories (
repo:read).
Push-event sync
Quay supports per-repository notifications.
- Repository → Settings → Notifications → Create Notification.
- Event: Push to Repository.
- Method: Webhook POST.
- Webhook URL:
https://<your-harborguard-host>/api/webhooks/quay. - Set HarborGuard's registry schedule to
on_push.
There is no org-wide push notification on Quay; configure one per repo (or use a CI step to call HarborGuard's webhook directly).
Common pitfalls
+in the username is significant. The robot username is literallyorg+name; some shells / form fillers strip the plus sign. The username must contain it.- Org vs user repositories. A robot lives on an org. To scan a user-owned repo (
quay.io/<user>/<image>), use a regular user account or migrate the repo to an org. - Token revocation cascades. Regenerating a robot token in Quay invalidates the old one immediately — HarborGuard will start failing on the next sync. Update the registry's credentials before regenerating.
- Encrypted CLI password vs account password. If your Quay account is backed by SSO/LDAP, the UI password won't authenticate to the registry — use the account's encrypted CLI password instead.
- Self-hosted Quay v3 URL paths. Self-hosted Quay sometimes runs behind a reverse proxy at a sub-path. HarborGuard expects
/v2/at the host root. Configure the proxy accordingly.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| 401 with valid robot token | Username missing the <org>+ prefix |
| Catalog empty for an org you can see in Quay UI | Robot has no repository permissions — grant Read at the org or per-repo level |
| Test passes but no images for a specific repo | Repo permissions are user-only; add the robot |
| Notification fires but no scan | Webhook is on a sibling repo, not the one whose image was pushed |
Self-hosted: /v2/ returns Quay UI HTML | Reverse proxy isn't forwarding /v2/* to the registry component |