Skip to content
Source
Sign inSign up

Add a secret

CI / Secrets and trust

Add a CI secret

Your jobs need tokens, like an npm token or an Nx Cloud token, and production needs other values than a preview. A CI secret keeps one value for each CI environment, and the forge sends the value only to the hosts that you bind it to.

10 min read

You need admin access to the repository. Only admins see the CI secrets in the Secrets section.

A secret is a stored value first. To let a job use it, bind it: give it the hosts that the value can go to, and the one request header that it goes in. A secret with no host is only stored: see Store a secret that no job sends.

This example gives the preview environment a read-only Nx Cloud token, and production a read-write token.

1. Open the Secrets section

Open the repository, then Settings, then Secrets under Code (/@<owner>/<repo>/settings/secrets). Pick preview in the environment list next to Secrets.

2. Add the secret and bind it

Click Add secret. Name it NX_CLOUD_ACCESS_TOKEN, bind it to the host cloud.nx.app, and set its header to Authorization.

The forge sends the value only to these hosts, and only in this header.

3. Type the value and save

Type the read-only token in its row, then click Save. The dialog lists what changes, by name only. Leave the other environments unticked, and click Save.

Note

Values are write-only. A saved value shows as dots, and the page never gets it back.

4. Give production its own value

Pick production. NX_CLOUD_ACCESS_TOKEN is under Action required, because it has a value in another environment and none here. Type the read-write token in its row, then click Save.

Done

NX_CLOUD_ACCESS_TOKEN has a read-only value in preview and a read-write value in production. A job that names one of these environments gets the value of that environment. To declare the secret on a job, see Use a secret in a job.

Add secrets from a terminal

Run src secret set. It uses your src login and the repository of your clone. --env is required. The value comes from stdin, from --body, or from a dotenv file with --env-file, so it stays out of your shell history.

src secret set NX_CLOUD_ACCESS_TOKEN --env preview --host cloud.nx.app --header Authorization < nx-read-only.txt
src secret set NX_CLOUD_ACCESS_TOKEN --env production < nx-read-write.txt
src secret set NPM_TOKEN --env production --host registry.npmjs.org --header Authorization < npm-publish.txt
src secret list
Command or flagWhat it does
--host and --headerBind the secret. A secret with a --host needs a --header or --in-body. With no --host, the secret is only stored, and src secret set says so in a terminal. A secret that exists keeps its hosts and its header when you leave the flags out.
src secret set NPM_TOKEN --unbindRemoves the hosts, the header and the body setting. The values stay, and no job can send them.
src secret list --env productionLists only the secrets with a value there. The Last used column says when a job last used each secret and in which environment, or never. The Sent to column names the hosts and the header, with body when the secret also goes in request bodies, or stored only.
src secret delete NPM_TOKEN --env productionDeletes the value of one environment. Without --env, it deletes the secret with all its values.
src secret set NPM_TOKEN --skip-env previewMarks preview as not needing the secret, as Dismiss does on the tab. --unskip-env preview takes it off. REST and MCP take skip and unskip lists, and list the skippedEnvironments of each secret.

Change the hosts or the header later

When a secret gets a new host or a new header, or --in-body turns on, the forge deletes its values in write-only environments (readers nobody, like production). This way a value of production only ever goes where it went when you set it.

  • To keep a value, set it again in the same command.
  • For a write-only preview, its branch values go too.
  • src secret set and the settings page say which values went. Enter them again.
  • Removing a host keeps the values.

Add secrets over REST or MCP

PUT the secret with the personal access token of an admin:

export TSS_FORGE_URL=https://forge.example/api/v1
export TSS_TOKEN=<your personal access token>

curl -X PUT "$TSS_FORGE_URL/repos/acme/app/ci/secrets/NX_CLOUD_ACCESS_TOKEN" \
  -H "Authorization: Bearer $TSS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environments":{"preview":"<read-only token>","production":"<read-write token>"},"hosts":["cloud.nx.app"],"header":"Authorization"}'
  • An environment that you leave out keeps its value, and null removes the value of an environment.
  • Hosts and a header that you leave out stay as they are. A secret needs neither.
  • An empty hosts list removes the binding, "header": null takes the header off, and "inBody": true lets the value go in request bodies.
  • The answer's droppedEnvironments names the write-only environments whose value a new host, a new header or inBody deleted.
  • The MCP tool set_ci_secret takes the same fields.

Store a secret that no job sends

Some values are secret, but no CI job sends them in a header: a database URL that your Worker reads, or a signing key. Store them with no host and no header.

  1. Save the secret with only a value: src secret set DATABASE_URL --env production < url.txt. On the web, click Add secret and leave Bound hosts empty.
  2. To put it on a Cloudflare Worker, declare it on the deploy job and add syncWorkerSecrets(). See Sync the secrets of a Worker.
  3. To read it on your machine, use src secret get DATABASE_URL --env development or src env pull. Only the readers of an environment read its values, and never the values of production.

What works:

  • The secret has no placeholder. A job that declares it runs, and gets no variable for it. No job and no agent can send it to any host.
  • The value can hold line breaks, like a PEM key.
  • A database password works this way for an app that connects to the database itself. A job cannot open a database connection: it reaches only https hosts on port 443. To change a database from CI, use a service with an HTTPS API, with a bound secret.
  • When you bind the secret later, the forge deletes its values in write-only environments, as for any new host. A value with a line break never goes in a header.

Work with the Secrets section

Save your changes:

  • The page address keeps the environment that you pick, like ?env=production. A refresh or a shared link opens that environment.
  • Edits wait until you click Save. The page warns you when you leave with changes that are not saved.
  • In the Save dialog, tick other environments to give them the new values that you typed in this one. A new secret is marked not needed in the environments that you leave unticked.
  • Removed values are removed in this environment only.
  • When the forge refuses one environment, the page names the secret and the environment, and keeps that change to save again.

Read the lists:

  • Action required lists the secrets with a value in another environment and none in this one. Type a value, or click Dismiss (or Dismiss all) when the environment does not need it. A value set later takes the secret off the dismissed list.
  • Active lists the other secrets, with a search box.
  • A secret with no host shows Stored only in its row: no job can send it. Click it to give the secret a host and a header.
  • A secret's … menu changes its hosts and header, removes its value in this environment, or deletes it. The … menu next to Save changes, adds or deletes environments.

Each row also says when a job last used the secret and in which environment (Last used 3 days ago in production), or Never used. A secret that no job used in a long time is one to delete.

  • The forge records a use when the first request of a job needs the value, once for each job.
  • src secret list shows the same in its Last used column.
  • GET /ci/secrets and list_ci_secrets answer lastUsedAt and lastUsedIn (null while no job used it).

Import secrets from a file

Import secrets, in the menu next to Add secret, reads ENV lines or a JSON object that you paste or drop. It reads them in your browser, and adds them as changes to save. Its title names the environment that the values go into, in red for production.

Each new secret gets its own hosts and header fields. They are filled in when the name or the value gives the service away:

Name or valueHostHeader
STRIPE_*, and sk_live_ valuesapi.stripe.comAuthorization
OPENAI_API_KEYapi.openai.comAuthorization
ANTHROPIC_API_KEYapi.anthropic.comx-api-key
NPM_TOKEN, and npm_ valuesregistry.npmjs.orgAuthorization
CLOUDFLARE_API_TOKENapi.cloudflare.comAuthorization
SENTRY_AUTH_TOKENsentry.ioAuthorization
GITHUB_TOKENapi.github.comAuthorization

Anything else, like DATABASE_URL, starts with no host and no header. Its row says Stored only: no job can send it without a host. You can import it like that, or give it a host and a header.

  • The import waits only for a new secret that has a host and no header.
  • A secret that exists keeps its hosts and its header.
  • The import shows how many secrets are new and how many replace a value, and lists the lines that it skips.

What the forge refuses

PartThe forge refuses
NameA name that is not an environment variable name. A name has letters, digits and _, and does not start with a digit.
EnvironmentAn environment that the repository does not have.
ValueA value over 16 KiB, or with a NUL character. A value with a line break, for a secret with a header (a secret with no header can hold one, like a PEM key). A value that is a TanStack Source token of any kind (tsp_, tsa_, tsj_, tsl_, and the gfp_, gfa_, gfj_, gfl_ forms): a job gets its own token for the forge.
HostsA host that is an IP address or the git host of the forge, and any host that is not an exact host name. More than 10 hosts for one secret.
HeaderA header or inBody with no host, and hosts with neither a header nor inBody. A header that is not a request header name, or a header like Host or Content-Length that says how a request travels.
CountMore than 100 secrets in one repository.

How the forge keeps the values

  • The list and the answers of a change never show a value. They show the environments that have a value, the hosts, the header, inBody, and when a job last used the secret.
  • The readers of an environment can read its values back with src secret get NAME --env <environment> or src env pull --env <environment>. See Get the values on your machine.
  • The values of production are write-only for everyone, and a job never reads a value back.
  • The values of each environment are encrypted with a key of their own. An admin can replace the key with src secret rotate-key --env <environment>: see Rotate the key of an environment.
  • The master key that protects those keys lives in a separate keys Worker. The site asks it to wrap and unwrap the keys, but never gets a copy of the master key. The CI runner cannot unwrap them at all: it gets the values of a job from the site.