Docker images and registries

Hubfly space has two separate registry workflows. You can deploy an image that lives in an external registry such as GHCR, Docker Hub, GitLab Registry or Harbor, or you can push images into the registry attached to a Hubfly space project. Choose the workflow first; the credentials and image references are different.

Choose the registry workflow

Need	Use	Where to configure it
Run an image already published elsewhere	Deploy from Docker image	Container creation → Docker image → Private Registry
Push your own image to Hubfly space	Project registry token	Project → Registry → Credentials → Registry Tokens
Keep a project registry tidy and scanned	Registry settings	Project → Registry → Settings
Notify another service after an image event	Registry webhook	Project → Registry → Webhooks
Redeploy a container after code or image changes	Deployment webhook	Project → Deployments → Pipeline Console

External private registries

When a container pulls from a private external registry, save its pull credential in the project. Hubfly space stores the password or token encrypted and returns only the credential metadata afterwards. A saved credential can be selected again for future redeployments.

Credential fields

Field	Required	What to enter
`label`	Yes	A recognizable name, such as `GHCR production read`.
`registryUrl`	Yes	The registry host, such as `ghcr.io` or `registry.gitlab.com`.
`username`	No	The registry username, deploy-token username, or service account name.
`password`	Yes	The registry password, deploy token, or package-read token.

Typical image references are:

text

docker.io/library/nginx:1.27
ghcr.io/acme/backend:v2.4.0
registry.gitlab.com/acme/platform/api:sha-7f3b1a9
registry.example.com/production/api@sha256:<digest>

Use a read-only credential

Hubfly space only needs to pull the image. For GHCR, GitLab, Docker Hub and Harbor, create a service credential with package-read or pull-only permission when the registry supports it. Do not paste a personal administrator token into a project credential.

Project registry

Each project can have its own managed image registry. The Registry tab shows the registry host, image references, storage usage, and Docker commands for the current project. Always copy the exact reference shown there; the project name and registry host are deployment-specific.

Push an image

Generate a registry token first. Then authenticate, tag a local image with the project reference, and push it. The token is the password; the username is accepted as a placeholder.

bash

# Use the host and project image reference shown in the Dashboard
REGISTRY_HOST="hubcell.local"
IMAGE_REF="hubcell.local/<project>/backend:v2.4.0"
REGISTRY_TOKEN="<token-from-the-creation-dialog>"

printf '%s' "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" \
  --username any --password-stdin
docker tag backend:local "$IMAGE_REF"
docker push "$IMAGE_REF"

Pull or deploy the image

bash

docker pull "$IMAGE_REF"

# In the Dashboard: Project → Containers → New Container → Docker image
# Then paste the same image reference and configure ports, env, and volumes.

Tags are not immutable

Pushing a new image with the same tag does not automatically change a running container. Use a deployment webhook or redeploy the container explicitly after publishing a replacement.

Registry tokens

Project registry tokens are separate from Hubfly space personal access tokens. They authenticate Docker-compatible registry operations and can expire independently. Generate them from the project Registry → Credentials tab.

Type	Allows	Recommended use
`pull`	Pull images	Runtime hosts, staging testers and deployment-only consumers.
`push`	Push images	CI jobs that publish images but never deploy them.
`push_pull`	Push and pull	A pipeline that builds, publishes and verifies its own image.

For each token, choose a label, access type, and expiration in days. The raw value is shown exactly once:

Copy it directly into your CI secret store.
Use it with docker login; never commit it to the repository.
Revoke it from the Registry tab when the job, person, or machine no longer needs access.

A revoked token cannot be restored

Create a replacement token, update the consumers, verify the new token works, and then revoke the old one. The token list keeps metadata such as prefix, expiry and last use, but never shows the secret again.

Images, cleanup and scans

The project Registry → Images view supports search by image name, tag or reference and shows digest, size, layers, architecture, whether a container is using the image, and registry storage cost. An image that is still referenced by a container cannot be deleted until that reference is removed.

Vulnerability scans

Enable Scan on Push in Registry → Settings for automatic scans, or trigger a scan from an image's actions. Scans run asynchronously and move through these states:

Status	Meaning
`queued`	The scan request was accepted and is waiting to run.
`scanning`	The scanner is inspecting the image.
`complete`	Results include severity counts and package/version details.
`failed`	The scan could not complete; retry it after checking the image reference.

Registry settings

Setting	Default	Effect
Automatic cleanup	30 days	Removes unused images older than the configured period.
Public registry access	Off	Allows unauthenticated pulls when enabled; keep it off for private images.
Maximum tags	Unlimited	Keeps only the latest N tags for an image name; `0` means unlimited.
Scan on push	Off	Queues a vulnerability scan after each successful image push.

API examples

The REST API exposes the same registry operations for automation. Use a Hubfly space personal access token with the required project permissions; use a project registry token only for Docker registry authentication.

bash

# List images
curl -sS "https://api.hubfly.space/api/v1/projects/PROJECT_ID/registry/images?page=1&pageSize=20" \
  -H "Authorization: Bearer $HUBFLY_TOKEN"

# Trigger a scan, then poll the result
curl -sS "https://api.hubfly.space/api/v1/projects/PROJECT_ID/registry/images/IMAGE_ID/scan/trigger" \
  -H "Authorization: Bearer $HUBFLY_TOKEN"
curl -sS "https://api.hubfly.space/api/v1/projects/PROJECT_ID/registry/images/IMAGE_ID/scan" \
  -H "Authorization: Bearer $HUBFLY_TOKEN"

For request and response schemas, use the API reference. For a container that should redeploy when the image changes, configure adeployment webhook rather than relying on a push alone.