Secrets

Store a credential once as a project secret, shared with everyone on the project. Scope it to just yourself when you need to, and Tektona keeps it encrypted and out of your sandboxes.

A Secret is a stored value: a key (e.g. anthropic), the secret itself, and where it lives. That's all it is. Secrets don't know where they're used. An Egress Proxy Profile is what injects a secret into your sandboxes' traffic, and git credentials have their own flow. This page is just the vault. For how the whole model fits together, and why the value never enters the sandbox, see how egress injection works.

The value lives only in the Secret. Everything that uses it references it by key, so you rotate a value in one place. A teammate can drop in their own personal value that quietly overrides the shared one for their own sandboxes, everywhere it's used.

Store a secret

A secret is a project secret by default. It lives in a project and is shared with everyone on the project. You add and manage it on the project's Secrets page. A secret has a key (e.g. anthropic) and a value. Values are write-only: once saved, no page or API call shows the secret again. To change one, save a new value over it.

A secret also has a type, which is the TYPE column in tektona secret ls:

TypeWhat it holdsCreated with
genericone opaque value — an API key, a token, a passwordtektona secret set (the default)
awsan AWS access key id and its secret access keytektona secret set --type aws
basica username and a password for HTTP Basic authtektona secret set --type basic
gita forge token, bound to the repositories it unlockstektona git-credential create — see Git repositories

Most secrets are generic. The other types exist because their consumer needs more than one value to work with.

AWS credentials

A normal secret is one opaque value that a rule drops into a header. AWS accepts no such header. It wants a signature computed over the whole request — method, host, path, query and body — so the value that authenticates a request is different for every request, and no stored string can stand in for it.

An AWS credential is therefore its own type. It has two halves: the access key id, which is not secret and travels in plain text in every signed request, and the secret access key, which is. Tektona checks the key id before it saves, so a mistyped credential fails here instead of as a 403 from AWS later.

Store both at once, on the Secrets page or from the CLI:

printf '%s' "$AWS_SECRET_ACCESS_KEY" | \
  tektona secret set aws-opensearch --type aws --aws-access-key-id AKIA...

The secret on its own does nothing. A rule has to name it, along with the AWS region and service it signs for:

tektona egress-proxy rule add aws-logs \
  --host '*.es.amazonaws.com' \
  --aws-region eu-central-1 --aws-service es \
  --aws-secret aws-opensearch

One rule per service: the service name is part of what gets signed, so S3 and OpenSearch need a rule each even when they share this credential. See Sign AWS requests for the whole flow, including what your code needs on its side.

The two halves belong together, so a rotation replaces both. Run the same command with the new key id and the new secret access key; a rotation that names only one is refused.

Basic credentials

A basic secret holds the username and the password of an HTTP Basic login as one secret. The username is not secret. The API and the console show it. The password is write-only, like every other value. The username cannot contain a colon.

Store both at once, on the Secrets page or from the CLI. The CLI reads the password on stdin:

printf '%s' "$REGISTRY_PASSWORD" | \
  tektona secret set registry-login --type basic --username deploy

A rotation replaces both halves. Run the same command with the new username and the new password. A rotation that names only the password is refused.

An egress rule uses the secret when its basic op names it in secret_ref. The op has no username and no template. The proxy then sends Authorization: Basic with the username and the password of the secret, on a matching host only.

Add the rule from the CLI with --basic-secret:

tektona egress-proxy rule add registry \
  --host registry.example.com \
  --basic-secret registry-login

--basic-secret names the secret by its key. Scope-qualify it as org:KEY, project:KEY or personal:KEY when the same key exists in more than one scope.

The console cannot create this op. Through the API, write it in the recipe of the request body that adds a rule to a proxy profile:

{
  "domain_pattern": "registry.example.com",
  "recipe": [
    { "target": "basic", "basic": { "secret_ref": "registry-login" } }
  ]
}

A rule that names a secret of another type in secret_ref is refused.

Use a long-lived access key, one that starts with AKIA. A temporary credential (ASIA) also needs a session token, which Tektona does not carry, so it is refused when you save it.

Scope a secret to just you

On the project's Secrets page you can optionally set a secret to Personal instead of leaving it shared. A personal secret is visible only to you and used only by sandboxes you own, and it overrides the shared project value for those sandboxes. Use it for your own key or quota when you don't want to put it in front of the whole project. The page lists the shared values and the ones scoped to you together, and each row shows its scope.

Organization secrets

Organization secrets are a separate, org-wide concept. You manage them on the organization's Secrets page (org settings), and they are shared across every project in the org. An org secret acts as the cross-project fallback. A project or personal value for the same key takes precedence where one exists.

A project admin can use org secrets in the rules of a project egress proxy profile, and a rule can send the value to any host it names. The creator of a project becomes its admin. If your org does not trust every member with its org secrets, turn off Allow members to create projects in organization settings. See Roles & Permissions.

Where it livesManaged onWho can see/use itTypical use
Project (shared)project → Secretseveryone on the projecta project-specific key
Project, scoped to youproject → Secrets (Personal)only sandboxes you own, in that projectyour own key / quota
Organizationorg → Secretsevery project in the orga shared team key

A personal value overrides the shared one

When something resolves the anthropic secret for a sandbox, Tektona picks the most specific value for the sandbox's owner: a personal value first, then the shared project value, then the organization fallback. So an org can publish a shared key, and any user who scopes their own anthropic value to themselves has it used automatically for their sandboxes, wherever anthropic is referenced, with no extra configuration.

Ownership transfer rebinds personally scoped values

Because a personal value resolves against the sandbox owner, transferring a sandbox re-binds any ${secret:...} reference (including those in an attached egress proxy profile) to the new owner. If the new owner has no personal value for a referenced key, and no shared project or org value covers it, resolution fails closed rather than reusing the previous owner's value. Transfer should therefore warn or block when a required personal value isn't present for the new owner. (Design item to confirm.) Deleting a secret that a profile references is the same fail-closed case. The reference stops resolving and the call fails rather than going out without the credential.

Organize secrets in folders

A key can contain slashes. Each part before the last slash names a folder, so the key payments/live/api-key lies in the folder payments/live:

tektona secret set payments/live/api-key   # value read from stdin

Each part of a key uses lowercase letters, digits, - and _, and starts with a letter or a digit. A full key has at most 256 characters.

A reference always names the full key. A scope qualifier comes before it, as usual:

--header 'x-api-key=${secret:payments/live/api-key}'
--header 'x-api-key=${secret:project:payments/live/api-key}'

You do not create a folder. A folder exists while a secret lies in it, and it goes away with its last secret. There is no folder rename or delete: to move a secret, set it under the new key, change every rule that names the old key, and then delete the old one. A reference to a deleted key stops resolving.

On the Secrets page, the list shows one folder level at a time. Click a folder to open it, and use the breadcrumb to go back up. The search finds keys in every folder. In the CLI, tektona secret ls payments/live lists one folder, and tektona secret ls --query live searches every key. See the CLI reference.

Sealing keys

Tektona keeps a sealing key pair for each org and for each project. The org key seals org secrets. The project key seals project secrets and personal secrets. The private keys never leave Tektona.

A key has one of three statuses:

StatusSeals new valuesOpens sealed values
activeYesYes
decrypt_onlyNoYes
retiredNoNo

Tektona makes the first key when it creates the org or the project. To replace the active key, rotate it. The old key becomes decrypt_only. When no sealed value needs the old key any more, retire it. A retired key cannot come back.

tektona project sealing-key ls
tektona project sealing-key rotate
tektona project sealing-key retire <keyId>

Every member can list the keys. Only an admin of the project, or of the org for org keys, can rotate or retire a key. See the CLI reference.

Security

  • Values never enter the sandbox when injected at the network edge (the default). They're fetched just-in-time, held briefly, and never stored on the sandbox's disk.
  • Write-only. Never shown again after you save them.
  • Encrypted in transit and at rest. The value travels to Tektona over HTTPS. Tektona encrypts it with a key unique to that secret before it is stored.
  • Rotate or revoke instantly. Change or delete a secret and in-flight caches drop it within seconds. Deletes are cryptographically shredded.
  • Removed with your access. Personally scoped values are deleted when you leave the project (or the org), so a value never outlives your access.

Injection terminates TLS at the egress boundary, so the sandbox trusts a Tektona CA for the injected hosts. Most tools pick this up automatically from the system trust store and the standard CA-bundle environment variables. Tools with their own trust store (e.g. Java's keytool) can import it with tektonactl ca cert, which prints the current CA as PEM.

A request to an injected host with the method TRACE or CONNECT gets status 405 and does not reach the host.

Next

On this page