Skip to main content

How secrets work

A secret is a connection to another service, such as Jira, Slack, GitHub or AWS: the address, the account and the token or key Jaah signs in there with. A task that needs to file an issue, post a message, push code or launch a machine does it with a secret it was given. You type the secret once, and Jaah never shows it again.

This page explains the ideas behind secrets. For the steps, see Add a secret, Attach a secret to a project and Replace or delete a secret. For every control on the screen, see Secrets.

Terms​

TermMeaning
SecretOne stored connection: a Name, a Type and the fields that type asks for.
TypeThe service the secret connects to, for example Jira, GitHub or AWS. It decides which fields the form asks for.
SecretA field Jaah keeps hidden, such as an API token or a Secret access key.
OwnerWho the secret belongs to: Personal, Organization or System.
NodeVaultAn optional seal on a secret's values: only your organization's nodes can open them. See How NodeVault works.
Attached projectA project the secret is attached to. Every task on it receives the secret.
Model accountNot a secret: the AI account a runner signs in as to reach the AI model. See Secrets and model accounts.

Who owns a secret​

When you add a secret, its Owner decides who may use it:

  • Personal — yours. Tasks you start can use it, and so can the projects you attach it to.
  • Organization — shared across your organization. Org Owners and Admins can use it, and so can their tasks and the tasks on the projects it's attached to.
  • System — for Jaah itself, for example cloud nodes. Tasks never see it, and it can't be attached to a project.

Use Personal for a token tied to your own account, and Organization for one the whole team shares. The form shows Owner only to Org Owners and Admins; a secret anyone else adds is personal. The list shows only the secrets you can see: the ones you added, and the ones shared with you.

How tasks use secrets​

A secret reaches a task in one of these ways:

  • Through its owner. A task you start can use your personal secrets.
  • Through a project. A secret attached to a project is given to every task that starts on that project from then on. Detach it, and tasks on that project stop receiving it.
  • As an environment variable. A project can hand its tasks one field of a secret as a variable, so the value is never shown on the project. See Add an environment variable.
  • For pushing code. A person's Git Access, on their profile, names the stored secret that tasks started from their account push with. See People.

Tasks find a secret by its Name, so make the name say what it's for. Slashes in a name file it in folders, which the Tree view shows.

What happens to a secret​

A secret value is written once and never read back on screen. When you open a secret, its secret fields show dots (●●●●●●●●●●●); leave them empty to keep what they hold. A filled round mark before a secret's name means a value is stored; a hollow one means none is stored yet.

A secret has no states of its own beyond that. Its life is short to describe:

  1. Added, with its values.
  2. Attached to the projects that need it, if any.
  3. Replaced when a token expires or is revoked: type the new value into the same secret, and everything that uses it picks it up.
  4. Deleted when it's no longer needed. Deleting removes every value stored with it and can't be undone.

Jaah encrypts every stored value. A secret marked NodeVault goes further: its values are sealed with a key only your organization's nodes hold, so a leak of Jaah's database, backups or keys can't reveal them. Tasks on your nodes receive them as before. NodeVault is part of some plans; an Org Owner or Admin sets it up once. See How NodeVault works.

Never paste a secret into a task's description, a project's commands or its agent instructions: anyone who can view those can read it.

Secrets and model accounts​

A secret and a model account both hold something secret, but they do different jobs:

SecretModel account
What it's forThe services a task's work touches: Jira, Slack, GitHub, AWS.The AI model itself: the account a runner signs in as to think and write.
Where it livesDirectory, then Secrets.Directory, then AI Accounts.
How it's chosenGiven to a task by its owner or its project.Picked for each run from the accounts your organization has.
What it showsWhether a secret is stored.Its quota, its sessions and the nodes it's signed in on.

A model account is a Subscription (OAuth) that a person signs in to on a node, or an API key Jaah stores and never shows again. A run uses a subscription's quota, or is billed per token on an API key. A task refusal that asks for an AI account (older: a credential account) means a model account, never a secret: see "No AI account". See How model accounts work and Model accounts.