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:

RegistryendpointnamespaceFull image path
GitLab CRregistry.gitlab.commygroup/myreporegistry.gitlab.com/mygroup/myrepo/image:tag
Docker Hubdocker.iomyuserdocker.io/myuser/image:tag
GitHub CRghcr.iomy-orgghcr.io/my-org/image:tag
Google ARus-docker.pkg.devproject/repous-docker.pkg.dev/project/repo/...
AWS ECR123456.dkr.ecr.us-east-1.amazonaws.com(empty)123456.dkr.ecr.../image:tag

Tektona checks both values when you save the registry:

  • The endpoint is a host name, an IPv4 address or an IPv6 address in brackets. A port is optional, for example registry.example.com:5000 or [2606:50c0:8000::153]:5000. A https:// prefix is allowed.
  • The endpoint has no path, user name, password, query or space. Tektona refuses any other scheme.
  • A host name cannot end in a number, such as example.123 or 0x7f000001. A resolver reads such a name as an IPv4 address.
  • The namespace is optional. It has one or more parts that a / joins, for example my-org/team-a.
  • Each part has lowercase letters and digits. A dot, an underscore or a hyphen can separate them.
  • A namespace cannot start or end with /, and it cannot hold ...
  • An endpoint that is an IP address must be public. Tektona refuses a loopback address, localhost and every name that ends in .localhost.
  • Tektona also refuses a private, link-local or reserved address, such as 10.0.0.5 or 169.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 --ssh

The 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 endpoint and namespace on the registry must match the image you passed to --image. ghcr.io/my-org/app needs endpoint ghcr.io and namespace my-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.

On this page