Red Hat Quay
Connect quay.io or self-hosted Red Hat Quay to Safeguard. The token scopes and robot permissions Safeguard needs, which credentials work, and step-by-step setup.
Availability
This integration is switched on per workspace. If you do not see the card under Integrations, ask your Safeguard contact.
What it does
The Red Hat Quay card connects Safeguard to the repositories on quay.io or a self-hosted Red Hat Quay. Safeguard lists the repositories of your namespaces (organizations and users) and every tag, and each image you select becomes a project that Safeguard scans for an SBOM and vulnerability findings. Each scan is pinned to the digest the tag points at when the scan starts, and pulls the image with the credential you connect. Find the card under Integrations on the Project/Product tab.
Public vs private
| Public | Private | |
|---|---|---|
| What you enter | The Quay URL and the Namespaces to read | The Quay URL and an OAuth token or robot account |
| Credential needed | None. Only public repositories are read | An OAuth application token or a robot account |
| What you can scan | Public repositories of the namespaces you name | Every repository the credential can read |
Supported auth methods
| Method (dialog label) | Use it when | Notes |
|---|---|---|
| OAuth token | Recommended | An OAuth application token, sent as a bearer token to the Quay API; pulls use it as $oauthtoken |
| Robot account | You want registry-only access | <namespace>+<robot> and its token. Robots cannot call the Quay API, so Safeguard lists through the registry and tags come without digests until a scan resolves them |
| Password | No token or robot is allowed | A Quay user and its password or encrypted password, registry-only like a robot |
Permissions required
Safeguard only reads. It never pushes, deletes or retags images, and never changes repository settings, except the notification you add yourself (below).
OAuth token
| Scope (UI label) | Required? | What Safeguard uses it for |
|---|---|---|
repo:read (View all visible repositories) | Required | Listing repositories (/api/v1/repository) and tags (/api/v1/repository/{repository}/tag/), and pulling images |
user:read (Read User Information) | Optional | Listing your user and organizations (/api/v1/user/) when you leave Namespaces empty |
repo:write, repo:admin, repo:create, org:admin, user:admin, super:user | Not used | Safeguard never writes |
Scopes do not override repository roles: the token's user must be able to read each repository.
Least privilege: an application token with repo:read (and user:read if you want namespaces discovered), created by a user that can only read the repositories to scan.
Robot account
| Permission | Required? | What Safeguard uses it for |
|---|---|---|
| Read on each repository | Required | Listing through the registry catalog, tags, digests and pulls |
| Write, Admin | Not used | Safeguard never writes |
Token types
| Credential type | Works? | Notes |
|---|---|---|
| OAuth application token | Yes (recommended) | Created under the organization's Applications |
| Robot account token | Yes | Registry reads only |
| User password or encrypted password | Yes | Registry reads only; prefer a robot |
| Token with write or admin scopes | Works, not recommended | Safeguard never writes |
Expiry: Quay OAuth tokens and robot tokens do not expire by default. Regenerate them on your rotation schedule (90 days or less is a good default).
What we never need: write, admin or super-user scopes, organization administration, or repository creation.
Step-by-step setup
Create the credential in Quay
OAuth token:
- Open the organization, then Applications > Create New Application and name it (for example
safeguard). - Open the application, choose Generate Token, tick View all visible repositories (and Read User Information if you want namespaces discovered), and authorize it.
- Copy the access token; Quay shows it once.
Robot account:
- Open the organization, then Robot Accounts > Create Robot Account.
- Give it Read on each repository to scan.
- Open the robot and copy its name and token.
Or with the Quay API
# Give an existing robot Read on one repository (as an organization administrator).
curl -X PUT -H "Authorization: Bearer <admin token>" -H "Content-Type: application/json" \
https://quay.io/api/v1/repository/<namespace>/<repository>/permissions/user/<namespace>+<robot> \
-d '{"role": "read"}'Connect it in Safeguard
- Open Integrations and choose the Project/Product tab.
- Click Connect on the Red Hat Quay card.
- Choose Private (or Public), enter a Name; the Quay URL is
https://quay.io(change it for a self-hosted Quay). - Private: pick OAuth token and paste the token, or Robot account with the Robot account name and its token.
- Namespaces: the organizations or users to list. Required for Public; with an OAuth token, leave it empty to list your user and organizations.
- Click Verify Credentials (or Check anonymous access).
- Click Next, select repositories and tags, and choose a connect option (fast, progressive or deep scan).
Webhooks and triggers
Scan on push is optional. Open the connection's edit dialog and expand Scan on push (optional) for the Webhook URL (https://api.safeguard.sh/scm/api/v1/registry-webhooks/quay/<connection id>) and the Secret. In Quay, open the repository, then Settings > Events and Notifications > Create Notification: event Push to Repository, notification Webhook POST, and the Webhook URL followed by ?token=<secret>. Quay sends no custom headers and does not sign notifications, so the secret travels in the URL; keep the URL private. Add one notification per repository.
Each delivery rescans the pushed tags (updated_tags), pinned to their digests at scan time. Without a notification, rescan on a schedule under Integrations > Scheduled.
What we read and store
- Read: namespace and repository names, tags with their manifest digests and times, and the images you select for scanning.
- Stored: the connection's settings, the SBOM and findings of each scanned image with its digest, and the credential, which is encrypted at rest and never shown again after you save it.
- Not stored: image layers. The image is read for the scan and not kept.
- No customer data from this integration is sent to third-party LLMs.
Troubleshooting
| Message you see | Cause | Fix |
|---|---|---|
Red Hat Quay rejected the OAuth access token ... with "View all visible repositories" (repo:read) and "Read User Information" (user:read). | A revoked token or missing scopes | Generate a new token with those scopes |
Red Hat Quay rejected the robot account. Its username is <namespace>+<robot name> ... | Wrong robot name or token | Copy both from the robot's page |
The Quay credential cannot read <repository> ... | The robot or the token's user has no Read on it | Grant Read on the repository |
Name the Quay namespaces (organizations or users) to list. Public mode cannot discover them. | Public tab with no namespaces | Enter at least one namespace |
The Quay namespace <namespace> has no public repositories. ... | Public tab on a namespace with only private repositories | Make a repository public, or use the Private tab |
The TLS certificate of <host> is not trusted ... | A self-signed or private certificate on a self-hosted Quay | Serve Quay with a certificate from a public certificate authority |
Rotation and disconnect
- Rotate: generate a new OAuth token (or regenerate the robot token), find the connection under Project Configurations on the Project/Product tab, choose Update, paste it, verify and save, then revoke the old token.
- Disconnect: choose Delete from the connection's menu under Project Configurations and confirm. Then revoke the token or delete the robot, and delete the repository notifications that point at Safeguard.
Vendor references
- Project Quay API guide, checked 2026-10-16.
- Red Hat Quay API reference, checked 2026-10-16.
- Repository notifications, checked 2026-10-16.