Sync and Health

A "sync" in HarborGuard is catalog enumeration only — it reads the list of repositories and tags from your registry and reconciles that list against the images recorded in your inventory. Sync does not pull image layers and does not run vulnerability scanners; both happen later, in the scan pipeline. The two pipelines fail independently: a successful sync followed by failed scans means catalog reads work but pulls don't.

What runs during a sync

For each registry, on every sync:

GET /v2/ to validate that the registry is reachable and credentials are still good.
Enumerate repositories — GET /v2/_catalog for OCI-compliant registries, the provider's REST API for Docker Hub / ECR / Artifact Registry / GHCR.
For each repository, GET /v2/<repo>/tags/list.
Apply the registry's tag filters.
Resolve each surviving (repo, tag) to its current digest and write/update the corresponding rows in HarborGuard's image inventory.
Persist the registry's lastSyncAt and health fields.

The slowest step is almost always (3) when a registry has thousands of repositories.

Status values

A registry's status reflects the most recent sync attempt:

Status	Meaning
`CONNECTED`	Last sync succeeded; registry is healthy
`SYNCING`	A sync is in progress
`DISCONNECTED`	No sync has run yet (e.g., a sensor-mode registry waiting for its first heartbeat)
`ERROR`	The most recent sync failed; details are surfaced in the registry detail view

health is a 0–100 score that reflects recent sync success rate; the dashboard shows it as a colored bar next to each registry.

Sync frequency

Schedule	Trigger
`manual`	Only when you click Sync Now or POST to the sync endpoint
`daily`	Once per 24 hours from the last successful sync
`weekly`	Once per 7 days from the last successful sync
`on_push`	Immediately when a registry webhook arrives (provider-dependent — see each provider's page)

The schedule is a property of the registry connection, not a global setting; you can mix daily for stable production registries with on_push for an active dev registry.

Triggering a sync manually

From the UI

Registries → [your registry] → Sync Now. The button is enabled whenever the registry isn't already in SYNCING state. The status flips to SYNCING immediately and the registry detail view polls for completion.

From the API

curl -X POST \
  -H "Authorization: Bearer $HG_API_KEY" \
  https://<your-harborguard-host>/api/registries/<registryId>/sync

A 202 Accepted is returned as soon as the sync has been queued. The response body confirms {"success": true, "message": "Sync started"}. To observe progress, poll GET /api/registries/<registryId> and watch the status and lastSyncAt fields.

The endpoint requires a token with at least the developer role.

Recovering from errors

The most common failure modes and what to check:

Error pattern	First thing to check
`Authentication failed`	Credentials rotated or expired (PATs, service-principal secrets, Azure SP, AWS keys)
`Connection timed out`	Egress firewall rules; DNS resolution from the sensor / cloud scanner
`Network error`	Registry is down or behind a private CA your scanner doesn't trust
`Unexpected status 403` on `/v2/_catalog`	Registry restricts catalog enumeration to admins; switch to per-image triggers
Repos enumerate, scans fail	This is not a sync issue — scan-pipeline pulls are blocked even though the catalog is readable. Check pull-only IAM (e.g., ECR `BatchGetImage`)
Sync hangs in `SYNCING` for hours	The catalog is enormous and pagination is slow; tighten tag filters and let it finish, or open an issue with the registry vendor

After any credentials change, click Test Connection in the registry settings before clicking Sync Now — the test surfaces auth issues directly without queuing a long enumeration.

A registry stuck in SYNCING for more than 24 hours is almost certainly a worker that crashed mid-job. Manually triggering another sync resets the state and queues a fresh attempt.