Tektona Docs

Attach repositories to a project, then unlock the private ones with a stored git credential.

You attach repositories to a project. Sandboxes and agents in that project can use every repository you attach. Mark some of them as the project's default repo set, the repositories present by default. A private repository also needs a stored git credential so a sandbox can authenticate when it clones over HTTPS. You attach that credential to the repositories it unlocks, picking them from the project's repository list.

Manage both from the project pages in the Tektona console: Repositories for the repos themselves, Git Credentials for the tokens. A git credential is the user-facing construct you work with: a token plus the repos it unlocks. Under the hood it is persisted as an internal secret of type git that never appears in the Secrets list. Manage credentials from the Git Credentials page in the console, or use the git-credentials endpoints in the API reference for automation.

Use HTTPS clone URLs, not SSH

Always attach repositories by their https:// clone URL, not an ssh:// or git@…:… URL. Credential injection, what lets a sandbox authenticate to a private repository, only works over HTTPS, so a credential cannot be attached to a repository whose URL is SSH-form.

How git credentials work

Git credentials keep their own dedicated, repo-centric flow: pick the forge, paste a token, tick the repos it unlocks, done. No catalog, no rules to build: you choose the forge (GitHub or GitLab) and Tektona scopes the token to those repos only. Under the hood it runs on the same engine as Egress Proxy Profiles. The token is injected at the network edge and never enters the sandbox (see how egress injection works).

Add a repository

You need writer or admin access to the project.

Open the Repositories page

In the console, go to your organization → the project → Repositories. The page lists every attached repository with its URL, default branch, and default-set membership.

Add the repository

Click Add repository and fill in:

Name. A short name for the repository within the project.
URL. The https:// clone URL (see the warning above).
Default branch. For example main. Optional — defaults to main when left blank.
Include in the default repo set. Check this to make the repository part of the project's default set.

Save. The repository now appears in the list.

From the CLI

Prefer the terminal? Register a repository with tektona repository (alias repo):

tektona repository create --url https://gitlab.com/group/online-shop
tektona repository ls

--name defaults to the last path segment of the URL; add --default-branch and --default to set the branch and include it in the default set. A registered repository is what a git credential attaches its token to — so register the repo first, then run tektona git-credential create --repo <name-or-url> ….

Edit and remove

Edit replaces all the repository's settings. One restriction: the default-set flag is append-only, so editing can add a repository to the default set but cannot remove it.
Delete removes the repository from the project, and is also the only way to take a repository out of the default set: delete it, then re-add it without the default flag if you still want it attached. Deletes are soft, so Tektona detaches the repository without destroying it upstream.

Editing and deleting also require writer or admin access.

Authenticate to private repositories

A git credential is a token Tektona stores so a sandbox can authenticate when it clones a private repository over HTTPS. The flow is deliberately minimal: pick the forge, paste the token, tick the repositories it unlocks, pick a scope, with no domains, no headers, no catalog. Tektona keeps the token encrypted and injects it at the network edge, only for traffic to those specific repositories, never for other repos on the same host, never for the forge's API or download hosts, and the token never enters the sandbox at all.

GitHub and GitLab

A git credential works across GitHub and GitLab (cloud or self-managed). You pick the forge when you create the credential, and Tektona handles its token form for you.

Allow the forge host in your network policy

A git credential only adds authentication. It does not open the network. The project's egress network policy must allow the forge host (for example github.com or gitlab.com), or the sandbox cannot reach the repository at all. Reachability and authentication are separate controls: the policy decides where a sandbox can connect, and the credential decides how it authenticates once there.

One token, many repositories

A forge token usually unlocks many repositories at once. One GitHub or GitLab PAT for an organization can read every service in a microservices project where each service is its own repository. You do not store the token once per repo. You store it once as a single credential and attach all of those repositories to it.

So the common setup for a multi-repo project is one credential holding the team's PAT, with every service repository ticked. Each repo is unlocked by that one credential, and the token is still injected only for the repositories you attached, never for anything else on the host. To rotate, you replace the single token in one place.

Two scopes

Every credential has a scope, shown as a badge on the Credentials page:

Scope	Who can see it	Who can manage it	Which sandboxes use it
Project	everyone on the project	project admins	every sandbox in the project
Personal	only you	only you	only sandboxes you own

A personal credential lives in one project: if you work across several projects, add your token in each one where you want it.

How a sandbox picks a credential

Credentials are matched per repository. When a sandbox clones a repository, Tektona resolves the credential based on the person who owns the sandbox:

the owner's personal credential attached to that repository, if any, otherwise
the project credential attached to it.

So a sandbox you own prefers your personal token and falls back to the shared project one. A sandbox owned by someone else uses their personal token (or the project one), never yours. If no credential is attached to the repository, the clone fails to authenticate. Two repositories can therefore use different tokens, each matched individually.

One credential per repository, per scope

Within a scope, a repository may be attached to only one credential, so saving a second credential for a repository already covered in that scope is rejected. To give two repositories different tokens, attach each to its own credential. To cover many repositories with one token, attach them all to a single credential.

The token never enters the sandbox

Git tokens are injected at the network edge, scoped to the exact repositories they unlock: the proxy adds the credential only to requests whose path resolves to a bound repository (so a token for acme/repo is never sent for acme/repo-private). The token is never written into the sandbox, and access to one repository never leaks a credential for another.

Because the token is attached at the edge, the proxy terminates TLS to the forge host, so git in the sandbox must trust Tektona's egress CA. Tektona stages this automatically (git reads it via GIT_SSL_CAINFO). See CA trust in the sandbox.

Add a credential

Open the Credentials page

In the console, go to your organization → the project → Git Credentials. The list shows each credential's scope, forge, name, and repositories. Use the All / Project / Personal filter to narrow the view.

Add it

Click Add credential and fill in:

Scope. Personal (only you) or Project (shared, admins only).
Name. A label to recognize it by.
Forge. GitHub or GitLab.
Repositories. Tick the project repositories this token unlocks. Don't see a repository? Add it on the Repositories page first.
Token. The secret itself, write-only.

Save. The credential appears with its scope and forge badges and the repositories it covers.

Tokens are write-only

Tektona encrypts the token at rest and never returns it. No page or API call shows the secret again. To change a token, delete the credential and add a new one.

Deleting erases the stored token immediately. Personal credentials are also removed automatically when you leave (or are removed from) the project, and across all of an organization's projects when you leave the organization, so your token never outlives your access.

Walkthrough: a private GitLab repository

Create a token in GitLab

In GitLab, create a token that can read the repositories:

For repos your whole team should reach, a Project or Group Access Token (Project/Group → Settings → Access tokens).
For your own access, a Personal Access Token (Preferences → Access tokens).

Give it the read_repository scope (add write_repository only if your sandboxes need to push). Copy the token, since GitLab shows it once. A group token is handy when one credential should cover several repositories under that group.

Attach the repository to the project

On the Repositories page, Add repository using the Clone with HTTPS URL from GitLab's Code button (https://gitlab.com/group/repo), not the SSH URL.

Store the credential

On the Git Credentials page, Add credential: choose the scope and forge, paste the token, and tick the repository you just attached.

Allow the forge host

Make sure the project's egress network policy allows gitlab.com (or your self-managed host). The credential authenticates the request, but the network policy is what lets the sandbox reach the host in the first place.

Clone from a sandbox

Create a sandbox in the project and clone over HTTPS, with no extra setup and no token in your commands:

git clone https://gitlab.com/your-group/your-repo.git

Tektona injects the credential attached to that repository (your personal one if you have it, otherwise the project one) and the clone authenticates automatically.

Copy the HTTPS URL, not SSH

Use Clone with HTTPS. The SSH URL (git@gitlab.com:…) won't authenticate, because Tektona injects credentials into HTTPS clones only. If a remote is already set to SSH, switch it with git remote set-url origin https://gitlab.com/your-group/your-repo.git.

Git Repositories