Quay Integration Guide

What the Integration Does

The integration uses a dedicated Quay OAuth2 access token to read data from your registry. All access is read-only. No data is written, updated, or deleted in your Quay registry. No image layers or container content are pulled — only metadata returned by the Quay API.

It syncs organizations, members, robot accounts, teams, repositories, tags, image manifests, the per-image software bill of materials (SBOM), and Clair vulnerability findings.

Step 1: Create a Quay OAuth Application

Quay access tokens are issued by an OAuth Application that lives inside an organization. You only need to do this once.

1. Sign in to Quay (https://quay.io or your self-hosted host).
2. Navigate to an organization you administer (create a dedicated org such as devgrid-integration if you prefer to keep this isolated).
3. Go to Applications (left sidebar) → Create New Application.
4. Name it DevGrid Integration and save.
5. Open the application → Generate Token tab.

A Quay OAuth application can only be created inside an organization, not under a personal account. The organization that owns the application does not have to be the one being synced.

Step 2: Generate the Access Token

On the application's Generate Token tab, select the scopes below, then click Generate Access Token. Quay shows the token once — copy it immediately and store it securely.

Minimum: repo:read + org:admin. Without org:admin, the organization, members, robots, and teams tables resolve empty. Without user:read, you must supply the organization names explicitly — the integration cannot auto-discover them.

The generated token is a long opaque string (no fixed prefix). It is what you hand to DevGrid.

Step 3: Decide Which Organizations to Sync

The integration can either auto-discover organizations from the token's user, or sync an explicit list you provide.

• Auto-discover (default): requires user:read. The integration reads the organizations the token's user belongs to.
• Explicit list (recommended for tightly-scoped tokens): you tell us exactly which organizations to sync (e.g. acme-prod, acme-staging). This works even without user:read.

If you want to limit the blast radius, create a dedicated user (or robot owner) that is a member of only the organizations you want synced, and provide the explicit list.

Step 4: Data We Collect

The integration reads the following 11 resources. All access is read-only.

Identity & Access

Repositories & Images

Security & Compliance

Vulnerability scans rely on Quay's built-in security scanner (Clair). If your Quay instance does not have security scanning enabled, the two security tables resolve empty — no errors occur. Scanning can also be disabled on the DevGrid side if you prefer not to collect it.

Robot tokens / secrets are never collected. Only the robot account names are read.

Step 5: Provide Credentials to DevGrid

Share the following with your DevGrid contact through a secure channel (password-manager share or encrypted message — never email the token):

Step 6: Verify Access

Before handing off the token, confirm it works. Replace YOUR_TOKEN and the base URL.

# 1. Token + user discovery (needs user:read)
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://quay.io/api/v1/user/" | jq '{username, organizations: [.organizations[].name]}'

# 2. Read an organization (needs org:admin)
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://quay.io/api/v1/organization/YOUR_ORG" | jq '{name, email}'

# 3. List repositories (needs repo:read)
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://quay.io/api/v1/repository?namespace=YOUR_ORG" | jq '.repositories[].name'

A successful response is HTTP 200 with JSON. HTTP 401 means the token is invalid or expired; HTTP 403 means the token is missing a scope (e.g. org:admin for call 2).

Network & Firewall Considerations

The integration connects outbound from DevGrid infrastructure to your Quay registry over HTTPS (port 443).

• Quay.io: No firewall changes needed.
• Self-hosted Red Hat Quay: If your registry restricts inbound connections by IP, contact your DevGrid representative for the list of source IP addresses to allowlist. Provide your registry host as the base URL (e.g. https://quay.yourcompany.com).

API Usage & Rate Limiting

The integration is designed to be respectful of your registry:

• Read-only: no writes, updates, or deletes.
• Paginated: repositories use Quay's next_page cursor; tags page in batches (up to 100 per request, Quay's maximum).
• Rate-limit aware: honors the Retry-After header and backs off automatically on HTTP 429, with exponential backoff + jitter on transient 5xx errors.
• Concurrent but controlled: a small, configurable number of tables sync in parallel (default 5).
• Graceful degradation: resources a token cannot access (e.g. a team without a members endpoint) resolve empty rather than failing the whole sync.

Incremental Sync

Quay's API has no server-side "modified since" filter for repositories, tags, or scans, so every run is a full sync. For very large registries this means each sync re-reads all metadata; the integration's pagination and rate-limit handling keep this within Quay's limits.

Token Rotation

When you need to rotate the access token:

1. Generate a new token from the same OAuth application (Step 2).
2. Send the new token to your DevGrid contact via a secure channel.
3. DevGrid updates the configuration (zero downtime).
4. Revoke the old token in Quay (application → token → delete).

Quay OAuth tokens do not expire on a fixed schedule by default, but you should rotate on your organization's standard cadence. Set a calendar reminder.

Frequently Asked Questions

Q: Does the integration write anything to our registry?
A: No. All access is strictly read-only.

Q: Do you pull our images or layers?
A: No. Only API metadata is read — repository/tag/manifest records and the Clair scan results. No image content is downloaded.

Q: Do you read our robot account tokens or secrets?
A: No. Only robot account names are collected.

Q: Can we limit which organizations are synced?
A: Yes. Provide an explicit organization list, or scope the token's user to only the organizations you want synced.

Q: Does this work with self-hosted Red Hat Quay?
A: Yes. Provide your registry host (e.g. https://quay.yourcompany.com) as the base URL.

Q: What if we don't run security scanning?
A: The two vulnerability/SBOM tables will be empty. Everything else still syncs. We can also disable vulnerability collection entirely.

Support

If you have questions about the integration or need help configuring access, contact your DevGrid representative or reach out to [email protected].