Container registries

Loha builds your images and pushes them to your registry. Loha does not host an image registry on your behalf. You bring your own (Docker Hub, GitHub Container Registry, GitLab, Harbor, or any OCI-compliant registry) and give Loha a credential scoped to pushing.

Manage them at Settings → Registries.

Who can manage registries

Registries are workspace infrastructure, so both viewing and editing them are limited to Owners and Admins. See Members & roles. A personal access token used against the API needs the registry:read or registry:write scope.

A service account bound to a project cannot manage registries at all, whatever its scopes. A registry is workspace-wide: deleting one breaks image pushes for every project, so there is nothing for a project binding to match. Use a workspace-wide service account.

How it works

A registry credential is workspace-scoped and keyed by its host. Add as many as you push to: one credential per registry. At build time, Loha renders all of your workspace's credentials into the build and hands them to the image-build step (buildah-build or docker-build). The step authenticates against whatever registry the image targets by matching the host in your IMAGE reference, so there is nothing to wire up in .loha.yml.

• Nothing to mount. You no longer create a docker-credentials secret or bind a workspace. That is automatic now.
• Push to any host you have added. If your IMAGE targets ghcr.io/acme/web, add a credential for ghcr.io.
• No credential for that host? The push fails. Only a public registry accepts an anonymous push. A workspace with no registries at all still builds fine; only the push step needs a credential.

Adding a registry

Open Settings → Registries → Add registry and fill in:

Field	What to enter
Registry	The registry host, e.g. ghcr.io, docker.io, harbor.example.com.
Username	The account or robot username the token belongs to.
Password or token	A push-scoped access token, not your account password.

Use a token, not a password. A registry access token limited to pushing images is safer to store and easy to revoke without disrupting anything else. For Harbor, use a robot account with push permission on the target project; for Docker Hub, GitHub, and GitLab, mint a registry/packages token in the provider's settings.

Docker Hub is stored as a canonical URL

Docker Hub is the one host that looks different from how you type it. Whatever you enter (docker.io, index.docker.io, registry.hub.docker.com), Loha normalizes and stores it as https://index.docker.io/v1/, the only address Docker, Buildah, and Kaniko actually authenticate against. The form shows a "Stored as …" hint before you save, so the value in the table is an explanation rather than a surprise. Reference Docker Hub images in .loha.yml however you normally do (e.g. docker.io/acme/web). The stored credential still matches.

The password is write-only

Loha never shows a stored password back; there is no read path for it. When you edit a registry, the password field starts blank: leave it blank to keep the current password, or type a new value to replace it. Rotating a token is the same flow: edit the registry and paste the new token.

One credential per host

Each registry host can hold exactly one credential in a workspace. Adding a second credential for a host you already have returns a conflict (409). Edit the existing one instead of creating a duplicate.

Confirming it works

There is no "test connection" action for registries. Loha cannot verify a push credential without pushing. The first build that reaches its image-push step is the test. If it fails, see Push fails with 401 Unauthorized below.

Loha does run two checks before the build starts, so a misconfiguration surfaces in seconds rather than ten minutes in at push:

• The credential can be read and applied. If not, the build is refused with a reason.
• A credential exists for the host you're pushing to. If your IMAGE targets ghcr.io and you have no ghcr.io credential, the build carries a warning naming the step and the host. It is a warning rather than a refusal because a public registry accepts an anonymous push, and because an IMAGE whose host comes from a variable is only resolved once the step runs, so Loha says nothing rather than guess. A step with SKIP_PUSH: true is never warned about.

Dashboard only, for now

Registries are managed in Settings → Registries. There is no /api/v1 endpoint for them yet, so they cannot be scripted the way webhooks or repositories can. The registry:read and registry:write scopes exist for the dashboard surface today.

Provider setup

Enter the host only: no scheme, no repository path. harbor.example.com/myproject is stored as harbor.example.com; the project or namespace stays in the IMAGE reference in your .loha.yml.

Docker Hub

Field	Value
Registry	docker.io
Username	Your Docker ID (not your email)
Password	An access token from Account Settings → Personal access tokens, with Read & Write

Docker Hub is stored under a canonical URL. See Docker Hub is stored as a canonical URL.

GitHub Container Registry

Field	Value
Registry	ghcr.io
Username	Your GitHub username (or the org's: any account the token belongs to)
Password	A classic personal access token with the write:packages scope

Fine-grained tokens do not currently cover GHCR pushes; use a classic token. If the package already exists, make sure the token's account has write access to that specific package.

GitLab Container Registry

Field	Value
Registry	registry.gitlab.com, or your self-managed registry host (often registry.<your-gitlab>)
Username	The deploy token username, or your GitLab username for a personal access token
Password	A deploy token with write_registry, or a PAT with write_registry

A project or group deploy token is the better choice here: it is scoped to the registry alone and can be revoked without touching your user account. The registry host is often not the same as your GitLab host. Check Packages and registries → Container Registry for the exact address.

Harbor

Field	Value
Registry	harbor.example.com, the host only, without the project name
Username	The full robot account name, e.g. robot$myproject+loha
Password	The secret shown once when the robot account is created

Use a robot account with push permission on the target project rather than a human login. Harbor shows the robot's secret only at creation time; if you lose it, regenerate it and edit the registry here.

Deleting a registry

Deleting a credential takes effect immediately. Loha re-renders the whole set of credentials your builds use and drops the deleted one right away (not at your next build), so even a build that has not yet reached its push step can no longer authenticate to that registry.

There is no "is anything still using this?" check. If a pipeline still pushes to that host, its next push fails with a 401. A delete cannot be undone; to restore access, add the registry again.

Managed registries

A registry may be labelled Managed by Loha. These are issued and rotated by Loha (arriving with Loha-hosted code hosting) and cannot be edited or deleted here. Today every registry you add is your own bring-your-own credential; no managed registries are issued yet.

Troubleshooting

The build was refused before it started, saying registry credentials could not be read or applied. Loha checks your credentials when the build is triggered, so a build does not run for ten minutes only to fail at push. This message means a credential exists but could not be decrypted or written. Retry; if it persists, contact support. The platform may be missing its encryption key.

Push fails with 401 Unauthorized. The build has no credential for that registry host, or the token is wrong, expired, or lacks push scope. Check that the host in your IMAGE exactly matches a registry under Settings → Registries, and that the token can push to the target repository. For Docker Hub, remember the stored host is https://index.docker.io/v1/, even though you still reference images as docker.io/… in .loha.yml.

A verbose build logged my registry config. Registry passwords are masked in build logs the same way secrets are, so a token echoed into Buildah or Kaniko output is redacted before the logs reach you.

Where to go next

• Buildah build / Docker build: the steps that push images
• Builds: what a build produces
• Releases: the record of each image a build pushed, and its digest
• Repo hosts: the other half of the setup, where your source comes from
• Variables and secrets: for the non-registry credentials your steps need
• Members & roles: who can manage registries

Using your registry's images in builds

A registry you add here also allows its images as run: step and services: images, and Loha pulls them with this credential. See Allowed images → Your own registry for exactly which images each registry allows.