Create a repository and pull your first image

This guide walks through creating an image repository, logging a container client in, and pulling an image. It uses the control-plane API for resource setup and the registry data plane for the pull itself.

Before you begin

Authentication. Export an API token as QIBDO_API_TOKEN and the API host as QIBDO_API_HOST. See Authenticate a user and manage the session.
Permissions. An IAM identity that can create repositories (registry.repository.create), and whose role or access policy conveys pull on the repository you are going to read. See the authorization model.
Prerequisites. A workspace UUID and your deployment’s registry hostname. Export your context:

export QIBDO_API_HOST="https://api.qibdo.example.com"
export QIBDO_API_TOKEN="<your-token>"
export WORKSPACE_ID="<your-workspace-uuid>"
export REGISTRY_HOST="registry.qibdo.example.com"

Step 1: Create a repository

Create an image repository by POSTing to the repositories endpoint. The repository lives directly inside the workspace. Choose a visibility; the format is fixed at creation and defaults to Docker:

curl -s -X POST \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$QIBDO_API_HOST/registry/v1/workspaces/$WORKSPACE_ID/engines/qibdo/repositories" \
  -d '{
    "name": "checkout-api",
    "description": "Checkout API service image",
    "visibility": "VISIBILITY_PRIVATE",
    "immutable_tags": true
  }'

The call completes synchronously: the response is an operation already marked done, with the new repository’s id in resource_id.

export REPOSITORY_ID="<resource_id-from-the-operation>"

Step 2: Log in to the registry host

Your username is your account email, and your password is an access token, not your console password. There is no registry credential to request first.

docker login "$REGISTRY_HOST" -u "you@example.com" --password-stdin <<< "$QIBDO_API_TOKEN"

Authenticating to the registry covers the exchange, which credentials work, and what each token is scoped to.

Step 3: Pull the image

The reference is the registry host, then the organisation, the workspace, and the repository. Both the organisation and the workspace accept either its name or its UUID:

docker pull "$REGISTRY_HOST/acme/production/checkout-api:v1.4.0"

To pull an exact artifact regardless of where tags currently point, use a digest:

docker pull "$REGISTRY_HOST/acme/production/checkout-api@sha256:0b1f…"

Step 4: Confirm what you pulled

docker image inspect "$REGISTRY_HOST/acme/production/checkout-api:v1.4.0" \
  --format '{{.Id}} {{.RepoDigests}}'

The digest is derived from the content, so it is what identifies the artifact across every registry that holds it.