Container Registries
Give Tektona a credential, so that a template build can pull an image from a private registry.
A template build pulls its base image from a container registry. A public image needs no setup. A private image needs a registry credential on your project.
Set up a registry credential
You configure a credential per project. Tektona applies it whenever a build in that project pulls a matching image. You never pass it to a build. An organization template cannot use a project registry. For a private image, create the template in a project that has a matching registry.
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 |
Tektona checks both values when you save the registry:
- The
endpointis a host name, an IPv4 address or an IPv6 address in brackets. A port is optional, for exampleregistry.example.com:5000or[2606:50c0:8000::153]:5000. Ahttps://prefix is allowed. - The
endpointhas no path, user name, password, query or space. Tektona refuses any other scheme. - A host name cannot end in a number, such as
example.123or0x7f000001. A resolver reads such a name as an IPv4 address. - The
namespaceis optional. It has one or more parts that a/joins, for examplemy-org/team-a. - Each part has lowercase letters and digits. A dot, an underscore or a hyphen can separate them.
- A
namespacecannot start or end with/, and it cannot hold... - An
endpointthat is an IP address must be public. Tektona refuses a loopback address,localhostand every name that ends in.localhost. - Tektona also refuses a private, link-local or reserved address, such as
10.0.0.5or169.254.169.254. - Your operator can allow a private range for a registry on a private network. A loopback address stays refused.
- Tektona does not look up a host name when you save it. A build looks up the host name and stops when it points to a private address that your operator did not allow.
Tektona sends the credential to the endpoint. A save with a bad value returns 422.
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.
A project can have at most 1000 container registries.
To automate this, use the registry endpoints in the API reference.
Build the template
Reference the private image exactly as the registry's
endpoint/namespace describes it:
tektona template create my-app --image ghcr.io/my-org/my-app:1.4.0
tektona sandbox create my-app --sshThe TypeScript SDK manages registry credentials too.
If the image won't pull
A build that fails on the pull 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 run the build again.
If the registry rate-limits the pull
A build can stop with the registry rate-limited the pull of <image>. The
image and your reference to it are both correct. The registry served too many
pulls and refused this one.
Public registries count a pull with no credential against a low limit, and they count it per address. Docker Hub is the strictest. Tektona retries the build a few times, so a short limit passes on its own. A limit that lasts hours does not, and the build then fails.
A credential raises the limit, and it counts against your account instead of an address you share. Configure a registry for the image host, the same way Set up a registry credential describes, and give it a Docker Hub account and an access token. The image stays public — the credential only raises what the registry serves you. A free account is enough to make a large difference.
For Docker Hub, use endpoint docker.io and leave namespace empty, so the
credential applies to every Docker Hub image the project pulls.
Two cases a project credential cannot cover:
- An image in the Tektona catalog, such as
tektona/sandbox-base. Those builds belong to no project. Ask your operator to configure a credential for the platform. - A base image you reference from another host. Configure a registry for that host too.