Projects, environments and secrets
Secrets belong to an environment, environments to a project, and projects to an organization:
Organization (my-company) │ ├── Project (api) │ ├── dev │ │ ├── DATABASE_URL = postgres://localhost/mydb │ │ ├── API_KEY = sk-dev-xxx │ │ └── AUTH_SECRET = random-dev-key │ ├── preview │ │ ├── DATABASE_URL = postgres://preview-host/mydb │ │ └── API_KEY = sk-preview-xxx │ └── prod │ ├── DATABASE_URL = postgres://prod-host/mydb │ └── API_KEY = sk-live-xxx │ └── Project (web) ├── dev │ └── NEXT_PUBLIC_API_URL = http://localhost:3001 └── prod └── NEXT_PUBLIC_API_URL = https://api.example.com
Organizations, and who may do what in them, are on Teams and access.
Projects
A project holds the secrets of one app or service. Any member of the organization can create one with New project in the sidebar, or with the CLI:
sigillo orgs # the organization's ID sigillo projects create --org <ORG_ID> --name my-app
A new project comes with three environments: Dev, Preview and Prod, with the slugs
dev, preview and prod.The project's Settings tab renames or deletes it. Anyone who can open the project can do that, unless it has an admin-only environment, which takes an org admin, or a protected one, which takes an org admin with a passkey approval. Deleting asks you to type the project's name: its environments, secrets, history and API tokens go with it.
Project names don't have to be unique. The CLI finds a project by its ID or its name (
--project, SIGILLO_PROJECT), and refuses a name that more than one project you can see has: use the ID then.Environments
The project's Environments tab lists them. Add Environment takes a name and a slug. Click a name or slug to change it. A slug is lowercase letters, digits and dashes, starting with a letter or digit, at most 63 characters, and unique in its project: it's what
-c takes.Two settings there change who reaches an environment:
- Min Role: Admin makes it admin-only: members can't open its secrets.
- Protected: On makes reading or changing its values take a passkey, and records every read. See protected environments.
Only org admins change them. Deleting an environment asks you to type its slug when it has secrets. Its secrets and their history go with it, and a token scoped to it alone stops working.
Secrets
The project's Secrets tab shows the names of an environment's secrets. A value loads when you reveal it, with the eye icon or by clicking it, or all at once with Show all secrets. In a protected environment, each reveal is recorded.
- Add Secret adds a row for a name and a value. Save then asks which environments the changes go to: the current one, and any others, where secrets are matched by name and missing ones are created.
- Import .env takes pasted
KEY=valuelines, with quotes,exportand comments, into the current environment. If one name in it isn't valid, nothing is imported. - The trash icon deletes a secret, from the environments you pick.
- A name is letters, digits and underscores, and doesn't start with a digit.
Names that another environment of the project has, but this one doesn't, show as red missing rows. Type a value to add one, or copy them all with Sync missing, from the environment you pick. Secrets that already exist aren't touched.
From the CLI:
sigillo secrets # names; in a terminal, also which are empty or missing sigillo secrets get DATABASE_URL --raw # one value sigillo secrets set API_KEY sk-live-xxx # set a value sigillo secrets set API_KEY -c dev -c preview # several environments; asks for the value echo "multiline\nvalue" | sigillo secrets set CERT # from stdin sigillo secrets delete OLD_KEY # delete
Without a value in a terminal,
secrets set asks for it without showing it, and an empty answer sets an empty secret to fill in later.Download all secrets
In the web UI, Download .env saves the environment as
.env.<slug>, and Copy as .env puts it on the clipboard. In a protected environment, both are recorded as downloads.The CLI downloads in more formats; the default is YAML:
sigillo secrets download --format env > .env
| Format | Use case |
json | Application config files |
env | Shell scripts with quotes |
env-no-quotes | Shell scripts without quotes |
yaml | The default |
docker | Docker --env-file |
dotnet-json | .NET appsettings.json (uses __ for nested keys) |
xargs | NUL-delimited pairs for shell pipelines |
To send them to another platform without a file, see Sync to other platforms.
History and old values
Every change is kept: Sigillo stores secrets as a log of changes, and a secret's value is its latest one. The History tab lists an environment's changes, newest first: the secret, set or delete, when, and who, a person, a token or a workload. The eye icon on a set shows the value it had then; in a protected environment, that is recorded too. To go back to an old value, reveal it and save it again.
The log is part of a history your instance signs, which
sigillo audit verify checks; a row marked unsigned was added to the database around it. See the signed history.Old values stay readable to anyone who can open the environment. Purge old values, on the History tab, removes all of them but each secret's current one, deleted secrets' values included. Only org admins can purge, with their passkey, and it can't be undone. The log keeps who changed what and when, and the history still verifies.