Secrets

This page shows you how to give agents a credential, such as a Stripe key or an npm token, without pasting it into a ticket. By the end you’ll have added a secret, chosen which agents can use it, and know how to change it later.

A secret is a named value an agent reads as an environment variable while it works, for example STRIPE_API_KEY. By Dawn encrypts it in your browser before it’s saved, for your organization’s paired machines only. So By Dawn’s servers store it but can’t read it, and nobody can view it again once it’s saved, in the app or anywhere else.

Secrets live in Settings›, then Organization›, then Secrets. Anyone in the organization can see the list of names and where each one applies, but never a value. Adding, rotating and deleting secrets needs an org owner or admin.

Before you start

• Pair at least one machine with your organization (see Remote agents and machines). A secret is encrypted for the machines that will run your agents, so with none paired there’s nobody to encrypt for and By Dawn won’t save it.
• Have the value ready to paste. You type it once and never see it again.

Add a secret

1. Choose Add secret. Add a secret opens.

2. Choose a Scope, which decides which agents can use it:

   • Organization: every project and agent in the organization.
   • Project: only agents working on one project’s tickets. Choose the Project.
   • User: only agents running on one member’s behalf. Choose the Member.

3. Give it a Name: the environment variable agents read it as, such as STRIPE_API_KEY. Use letters, digits and underscores, and don’t start with a digit. Names starting with SAW_ are reserved for By Dawn’s own settings, so the form refuses them.

4. Paste the Value.

5. Choose Encrypt & save. Under the value, the drawer says how many machines it’s encrypting for.

Each secret then shows its name, the project or member it applies to, and how many recipients can read it.

Which secret an agent gets

When an agent starts on a ticket, it gets every secret that applies to that ticket: the organization’s, the ticket’s project’s, and those of the member it runs on behalf of. If two share a name, the most specific one wins: user, then project, then organization. So a project can override an organization-wide NPM_TOKEN by adding its own with the same name, without touching anyone else’s.

Change or remove a secret

Open a secret’s menu:

• Rotate value replaces the value. The name, scope and project or member stay the same. Choose Encrypt & rotate to save.
• Delete removes the secret. Agents that start afterwards no longer get it.

Caution

A secret is encrypted for the machines paired when you save it. A machine you pair later can’t read existing secrets until you rotate them, so after pairing a new machine, rotate the secrets its agents need. Rotating with the same value is fine.

Secrets in your repos’ GitHub Actions

Organization and project secrets can also be pushed into a repo’s Actions or Dependabot secrets by a repo bootstrap policy. See Repo bootstrap for how that works and why an agent does the pushing. A value that isn’t secret, such as a region or an environment name, can be an Actions variable instead: see Actions variables.

FAQ

Can I see a secret's value after I've saved it?

No. By Dawn only ever shows a secret’s name and where it applies. To change the value, rotate it.

Why does Add a secret say there are no devices to encrypt for?

Your organization has no paired machines yet, so nothing could ever read the value. Pair a machine first, then add the secret.

An agent says a secret is missing. What should I check?

Check that the secret’s scope covers the ticket’s project, or the member the agent runs for. If it does, the machine running the agent was probably paired after the secret was saved: rotate the secret so that machine can read it.

What does Secrets aren't available in this app mean?

The app you’re using isn’t connected to the service that lists your organization’s machines, so it has nothing to encrypt for. Open Settings›, then Organization›, then Secrets while you’re signed in to your By Dawn organization.

Where to go next

• Remote agents and machines: pair the machines your agents run on.
• Skills & Tools: shared tools often read their credentials from secrets.