Run a Custom Image
Boot a sandbox from your own OCI image, including private images that need registry credentials.
A Tektona sandbox runs whatever OCI image you point it at. Public images work with no setup. Private images need a registry credential stored on your organization so Tektona can pull them.
This guide assumes your image is already built and pushed to a registry. Building and pushing the image is out of scope.
Prerequisites
- The
tektonaCLI installed and configured (tektona login), with an org/project context set (tektona ctx show). - An image already published to a container registry.
Run a public image
For an image in a public repository, reference it directly:
tektona sandbox create --image ghcr.io/acme/my-app:1.4.0Image references must be deterministic: use a non-latest tag, a
@sha256:… digest, or both. Tektona rejects a bare image or a bare
:latest. See
Manage Sandboxes → Choosing an image
for the full rules and more examples.
Run a private image
Private images need a registry credential. You configure one per
organization, and Tektona applies it automatically whenever a sandbox
in that org references a matching image. You never pass it to
sandbox create.
Work out your endpoint and namespace
Tektona builds the full image path as endpoint/namespace/image:tag. Pick
the endpoint and namespace that match how you reference the image:
| Registry | endpoint | namespace | Full image path |
|---|---|---|---|
| GitLab CR | registry.gitlab.com | mygroup/myrepo | registry.gitlab.com/mygroup/myrepo/image:tag |
| Docker Hub | docker.io | myuser | docker.io/myuser/image:tag |
| GitHub CR | ghcr.io | my-org | ghcr.io/my-org/image:tag |
| Google AR | us-docker.pkg.dev | project/repo | us-docker.pkg.dev/project/repo/... |
| AWS ECR | 123456.dkr.ecr.us-east-1.amazonaws.com | (empty) | 123456.dkr.ecr.../image:tag |
Choose an auth type
All private registries require authentication. Pick the one your registry uses:
- Personal access token (default) for GitHub and GitLab. Provide a username and the token.
- Basic for username and password registries.
- Bearer token for token-only registries.
Create the registry credential
Registries are managed in your project settings. Add a registry with the endpoint, namespace, and auth details from the previous steps.
Credentials are write-only. Tektona stores them encrypted and never shows them again. To rotate them, edit the registry and enter the new secret.
To automate this, use the registry endpoints in the API reference.
Create the sandbox
Reference the private image exactly as the registry's
endpoint/namespace describes it:
tektona sandbox create --image ghcr.io/my-org/my-app:1.4.0 --sshIf the image won't pull
A sandbox that errors right after creation usually has a registry credential that does not match the image reference:
- The
endpointandnamespaceon the registry must match the image you passed to--image.ghcr.io/my-org/appneeds endpointghcr.ioand namespacemy-org. - The auth type must match what the registry expects (token vs. username/password).
- The token or password must still be valid and have read/pull scope for that repository.
Re-check the registry on the Registries page, fix the mismatch, and create a new sandbox.