Tasks

Using secrets

A job sends a secret to one named place, and its script never reads the value.

A secret is a value such as an API token.

The controller keeps the secret in the store, encrypted so that only the controller can read it.
A job's allow: list names the secret and the one place it can go: secret:GITHUB_TOKEN@net:api.github.com.
The controller puts the value in that job, which is encrypted for its runner.
The script gets a handle, never the value.

What Corbie does depends on where the script sends the handle.

When the script sends the handle to api.github.com, Corbie sends the value in its place.
When the script sends the handle to any other host, Corbie refuses, and the job fails with status denied.
When a reply contains the value, Corbie replaces it with [secret GITHUB_TOKEN].

Set a secret

corbie controller secret set GITHUB_TOKENkept by the controller, for every run corbie run submit flow.yaml --secret GITHUB_TOKENsent with a run, for it and its child runs

Each asks for the value at the terminal and does not show what is typed. A value is never given on the command line. In a script or a CI job, name where the value is read from:

corbie controller secret set GITHUB_TOKEN --envthe environment variable GITHUB_TOKEN corbie controller secret set GITHUB_TOKEN - < tokenstandard input, to the end corbie run submit flow.yaml --secret-env GITHUB_TOKENthe environment variable GITHUB_TOKEN

When the variable has another name, set it for the one command: GITHUB_TOKEN=$GH_PAT corbie run submit flow.yaml --secret-env GITHUB_TOKEN.

corbie controller secret set runs on the controller's computer. A secret sent with a run replaces a controller secret of the same name, and corbie test takes both flags.

A job that names a secret set in neither way fails before its script is sent to a runner: the secret GITHUB_TOKEN is not set.

Other places a secret can go

secret:DEPLOY_TOKEN@exec:deployto that program secret:APP_KEY@fs.write:/etc/app/keyinto that file secret:HOME_TOKEN@net.unencrypted:192.0.2.8:8123to that host, encrypted or not secret:TG_BOT@*anywhere the job is allowed

A secret bound with net: is sent only over an encrypted connection. For a device that accepts only plain HTTP, write net.unencrypted: anyone on the network path can then read the secret.

Use it in a script

allow: [net:api.github.com, "secret:GITHUB_TOKEN@net:api.github.com"]

const gh = secrets.get("GITHUB_TOKEN")
const me = http.get("https://api.github.com/user", {
  headers: { Authorization: secrets.text`Bearer ${gh}` },
  as: "json",
})
return me.body.login                // gives "octocat"

net:api.github.comneeded too: a secret: entry grants no connection, program or file secrets.getreturns the handle secrets.textjoins text and handles into a new handle

Each plugin's page lists where its calls take a handle, such as a header, a URL, a body, a program's argument or a file. A script cannot convert a handle to text, compare it, measure it, return it or emit it.

A script allowed to connect to a secret's destination can learn the secret from the server there: see What Corbie does not defend against.

Reference

secrets every call a script can make on a handle
http where a request takes a handle
Permissions how an entry is written, and the layers that limit a job
corbie run submit the flags of corbie run submit, --secret and --secret-env among them