`secret`

Function, in @jr2/orchestrator/src/http-effect.ts. It is an export of @jr2/orchestrator, on the Authoring surface page, in Effects.

Overload 1

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

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

Overload 2

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

secret ​

Overload 1 ​

Overload 2 ​

`secret`

Overload 1

Overload 2