registry.image.resolve

Resolve a registry image tag, digest, or reference to catalog metadata

Resolve a registry image reference from the local aggregated catalog.

Inputs:

• organization_uuid: Organization UUID (required)
• registry_repository_uuid: RegistryRepository UUID (optional when repository_full_name is provided)
• repository_full_name: Provider repository full name, e.g. ghcr.io/org/pkg (optional when UUID is provided)
• tag: Exact tag to resolve (optional)
• digest: Exact digest to resolve (optional)
• reference: Full reference such as repo:tag or repo@sha256:... (optional)

Outputs:

• resolved: true when a matching digest or version exists
• registry_repository_uuid, registry_image_uuid, registry_image_version_uuid
• repository_full_name, tag, digest, reference
• media_type, artifact_type, architecture, operating_system, size_bytes, pushed_at, last_seen_at
• error: str | None for soft validation/read errors

Overview

Property	Value
Workflow type	Atomic
Library	App-registry
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization UUID for tenant isolation
registry_repository_uuid	uuid	No	—	Restrict resolution to one RegistryRepository
repository_full_name	string	No	—	Provider repository full name, such as ghcr.io/org/package
tag	string	No	—	Exact tag to resolve
digest	string	No	—	Exact image digest to resolve
reference	string	No	—	Full image reference, such as repository:tag or repository@digest
workflow_run_id	string	No	—	Engine-stamped workflow_run_id when invoked as a DAG step (ADR-015 E1)

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization UUID for tenant isolation
registry_repository_uuid	uuid	No	—	Restrict resolution to one RegistryRepository
repository_full_name	string	No	—	Provider repository full name, such as ghcr.io/org/package
tag	string	No	—	Exact tag to resolve
digest	string	No	—	Exact image digest to resolve
reference	string	No	—	Full image reference, such as repository:tag or repository@digest
workflow_run_id	string	No	—	Engine-stamped workflow_run_id when invoked as a DAG step (ADR-015 E1)
resolved	boolean	Yes	—	True when a matching image or version was found
registry_image_uuid	uuid	No	—	Resolved RegistryImage UUID
registry_image_version_uuid	uuid	No	—	Resolved RegistryImageVersion UUID when a version matched
is_mutable	boolean	No	—	Version mutability when a version matched
media_type	string	No	—	Resolved image media type
artifact_type	string	No	—	Resolved artifact type
architecture	string	No	—	Resolved image architecture
operating_system	string	No	—	Resolved image operating system
size_bytes	integer	No	—	Resolved image size in bytes
pushed_at	string	No	—	ISO-8601 push timestamp
last_seen_at	string	No	—	ISO-8601 last-seen timestamp
error	string	No	—	Soft read/validation error when unresolved
failure_reason	string	No	—	Engine failure reason, present only on failed terminal state
failure_type	string	No	—	Engine failure type classification (ADR-015 E2)
failed_action	string	No	—	Action name that caused the failure (ADR-015 E2)
failed_at_state	string	No	—	State name where the failure occurred
failed_step	string	No	—	Failed DAG step name when reported by the engine
failed_layer	integer	No	—	1-based failed DAG layer number emitted by the engine
error_type	string	No	—	Unexpected error class or type

States

State	Initial	Terminal	Success	Auto-advance	Description
done	Yes	Yes	Yes	—	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "registry.image.resolve",
  "initial_data": {
    "organization_uuid": "value"
  }
}