---
title: secret
description: "Name an Effect secret: `secret(\"jira\")`."
---

# `secret`

Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.

## Overload 1

```ts
function secret(name: string): Secret
```

Name an Effect secret: `secret("jira")`. The name is the `name` of an entry in the `secrets`
list of `jr2.config.ts`. The Effector reads the value and puts it into the call, or into the env
of a `command`. The Agent never reads it, and the Orchestrator never holds it.

Use it in `bearer`, `basic` or `text`, or in the `env` of a `command`. In an `env`,
`secret("x")` gives the value, and `secret("x").path` gives the path of a file that holds the
value.

`secret(open)` leaves the name to the composer of a packaged Machine, who binds it one time:
`customize(machine, { effects: { <slot>: { secret: "<name>" } } })`. An Effect can have one Open
secret, in its `auth`, a header or its `env`. A url cannot have one: leave the whole url Open
(`url: open`) instead.

It refuses, when you call it:
- a name that is not letters, digits, `.`, `_` and `-`, that starts with `.`, or that is longer
  than 253 characters: `secret("<name>"): a secret's name is letters, digits, ".", "_" and "-",
  and does not start with "." — it is the file the Effector reads it from (ADR-0068)`
- an Effect that names `secret(open)` in two places that are two secrets: `an Effect takes one
  Open secret — it names secret(open) in two places that are two secrets; name one secret(open)
  and use it in each place, or name the others with secret("<name>") (ADR-0054)`
- `secret(open)` in a url: ``secret(open) in a url: a url's secret is not an Open part — leave
  the whole url Open (`url: open`) and let the composer bind it with its secret in its path
  (ADR-0054)``

And at `jr2 up`:
- a name that the `secrets` list does not have: ``workflow "<workflow>": the <kind> Effect
  "<slot>" names secret("<name>"), which the `secrets` list does not hold — add it: secrets: [{
  name: "<name>", value: process.env.<NAME> }] (ADR-0068)``
- a value of fewer than 8 characters: `secrets[<i>] (<name>) is an Effect secret shorter than 8
  characters — the Effector replaces every match of a secret in what it returns, and a value
  this short would match ordinary text. Use the whole credential; the value itself is not shown
  (ADR-0068)`

**Parameters**

- `name`: The name of an entry in the `secrets` list.

**Returns**: The Effect secret, for an Effect. Its `.path` names the file of the secret, for the
`env` of a `command`.

**Example**

```ts
import { command, fail, jr2Setup, secret, workspace, type Workspaced } from "@jr2/orchestrator";

type Input = Workspaced<{}, "app">;

const body = jr2Setup({
  types: {} as { context: Input; input: Input },
  actors: {
    // The command reads the file at $KUBECONFIG. The Agent never reads the secret.
    deploy: command(["kubectl", "apply", "-f", "k8s/"], {
      env: { KUBECONFIG: secret("kube").path },
    }),
    fail: fail(),
  },
}).createMachine({
  id: "deploy",
  context: ({ input }) => input,
  on: { "workspace.lost": ".lost" },
  initial: "deploying",
  states: {
    deploying: { invoke: { src: "deploy", onDone: "done" } },
    done: { type: "final" },
    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  },
});

export const machine = workspace(body, {
  repos: { app: { url: "https://github.com/you/app.git" } },
  spec: () => ({ branch: "deploy" }),
});
```

**See also**

- [Secrets and trust](../../concepts/secrets-and-trust.md)
- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
- [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)
- [ADR-0054: The kit ships Machines, and a shipped Machine leaves its parts Open](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)

## Overload 2

```ts
function secret(name: typeof open): OpenSecret
```

Leave an Effect secret Open: `secret(open)`, in a Machine that you publish as a package. The
composer binds its name one time: `customize(machine, { effects: { <slot>: { secret: "<name>"
} } })`. `secret` tells the rest, and what it refuses.

**Parameters**

- `name`: `open`.

**Returns**: The Open secret, for an Effect. Its `.path` names the file of the secret, for the `env`
of a `command`.

**See also**

- [Secrets and trust](../../concepts/secrets-and-trust.md)
- [Bind a shipped Machine's Open parts](../../guides/bind-open-parts.md)
- [ADR-0054: The kit ships Machines, and a shipped Machine leaves its parts Open](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)