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
| Term | Meaning |
|---|---|
| Secret | One stored connection: a Name, a Type and the fields that type asks for. |
| Type | The service the secret connects to, for example Jira, GitHub or AWS. It decides which fields the form asks for. |
| Secret | A field Jaah keeps hidden, such as an API token or a Secret access key. |
| Owner | Who the secret belongs to: Personal, Organization or System. |
| NodeVault | An optional seal on a secret's values: only your organization's nodes can open them. See How NodeVault works. |
| Attached project | A project the secret is attached to. Every task on it receives the secret. |
| Model account | Not 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:
- Added, with its values.
- Attached to the projects that need it, if any.
- Replaced when a token expires or is revoked: type the new value into the same secret, and everything that uses it picks it up.
- 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:
| Secret | Model account | |
|---|---|---|
| What it's for | The 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 lives | Directory, then Secrets. | Directory, then AI Accounts. |
| How it's chosen | Given to a task by its owner or its project. | Picked for each run from the accounts your organization has. |
| What it shows | Whether 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.
Related
- How tasks work — the work a secret is given to.
- How projects work — where secrets are attached.
- How nodes work — the machines runners, and their model accounts, run on.
- How NodeVault works — sealing secrets so only your nodes can open them.
- How team and access work — the roles that decide who may add, attach and change secrets.