Create a namespace and push your first image

This guide walks through creating a namespace and an image repository, obtaining short-lived registry credentials, and pushing your first artifact. It uses the control-plane API for resource setup and the registry data plane for the push 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 namespaces and repositories (registry.namespace.create, registry.repository.create) plus a push (or admin) grant on the repository for the push. See the authorization model.
• Prerequisites. A workspace UUID and a region UUID. 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 REGION_ID="<your-region-uuid>"

Your deployment’s API domain

api.qibdo.example.com is an example host. qibdo runs on your own infrastructure, so the API lives at your deployment’s own domain. Replace it with yours before running these examples.

Console

Coming soon

A step-by-step walkthrough in the qibdo console is on the way. For now, use the REST tab.

CLI

Coming soon

A qibdo CLI walkthrough is on the way. For now, use the REST tab.

REST

Step 1: Create a namespace

Create a namespace by POSTing to the namespaces endpoint. Its name must match ^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$, and a region is required:

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/namespaces" \
  -d '{
    "name": "team-payments",
    "description": "Payments service images",
    "region_id": "'"$REGION_ID"'"
  }'

The call completes synchronously: the response is an operation already marked done, with the new namespace’s id in resource_id. Read the namespace back with a GET for its output-only registry_url:

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

curl -s \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  "$QIBDO_API_HOST/registry/v1/workspaces/$WORKSPACE_ID/engines/qibdo/namespaces/$NAMESPACE_ID"

Step 2: Create a repository

Create an image repository under the namespace by POSTing to the repositories endpoint. 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/namespaces/$NAMESPACE_ID/repositories" \
  -d '{
    "name": "checkout-api",
    "description": "Checkout API service image",
    "visibility": "VISIBILITY_PRIVATE",
    "immutable_tags": true
  }'

The returned operation comes back already done, with the repository id in its resource_id.

Step 3: Get short-lived registry credentials

Push and pull traffic uses a short-lived registry credential, not your API token. Request one with a GET:

curl -s \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  "$QIBDO_API_HOST/registry/v1/workspaces/$WORKSPACE_ID/namespaces/$NAMESPACE_ID/credentials"

The response carries registry_url, username, password, and expires_at. Log your Docker client in against registry_url:

docker login "<registry_url>" -u "<username>" --password-stdin

Pipe the password from the credential response into --password-stdin rather than passing it on the command line, and re-issue the credential once expires_at passes.

Step 4: Push the image

Tag your local image for the repository and push. The push flows through the registry data plane:

docker tag checkout-api:1.0.0 "<registry_url>/team-payments/checkout-api:1.0.0"
docker push "<registry_url>/team-payments/checkout-api:1.0.0"

Because the repository has immutable_tags enabled, the registry refuses to overwrite the 1.0.0 tag on a later push. Bump the tag instead.

Step 5: Confirm the artifact landed

List artifacts through the control plane with a GET; tags are returned inline:

export REPOSITORY_ID="<repository-id>"

curl -s \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  "$QIBDO_API_HOST/registry/v1/workspaces/$WORKSPACE_ID/engines/qibdo/namespaces/$NAMESPACE_ID/repositories/$REPOSITORY_ID/artifacts"

Each artifact in the response carries its digest, size_bytes, media_type, the inline tags (here, 1.0.0), and a scan_status that starts out not scanned.

Next steps

• Read Namespaces, repositories, and artifacts to understand digests, tags, and the two delete operations.
• Learn how the scan_status advances and what it gates in Scanning and supply-chain governance.
• Apply the platform security baseline to your access policies.