Secrets and Environment Variables#

Jobs often need values they should not hardcode: API keys, tokens, endpoints. GearTrain gives you two ways to provide them, and scripts read both the same way, with the env module.

Reading Values in a Script#

The env module’s env.get returns the value of a variable by name:

// weather.js
import env from "env";

const apiKey = env.get("API_KEY");

const res = await fetch(
    `https://api.example.com/weather?token=${apiKey}`,
);
console.log(await res.text());

env.get throws an error when the name does not exist. A missing value therefore fails the run at the read, with a clear error, instead of sending an empty secret somewhere. See the env module for the full contract.

Saved Secrets#

Secrets are named values that GearTrain stores encrypted. Every run of every job can read them, and the plaintext is never shown in the interface again after you save it.

1. Open Secrets and click the create control.
2. Enter a name (for example API_KEY) and the value.
3. Save. Scripts can now read it with env.get("API_KEY").

The rules:

• Names are permanent. A secret’s name cannot be renamed. Delete the secret and create a new one if you need a different name.
• Values are write-only. You can set a value, but the interface never shows it again. To change a value, delete the secret and create it again with the same name.
• Names are unique. Two secrets cannot share a name.

Per-Run Environment Variables#

Sometimes you want a value for a single run only, such as testing against a staging endpoint. The workbench’s Run now panel takes temporary variables for exactly that: one KEY=VALUE pair per line in the Environment field.

• Variables exist only for that run. They are not saved anywhere and do not affect the next run or the schedule.
• Blank lines and lines starting with # are ignored.
• Surrounding quotes around values are removed automatically, so TOKEN="abc" and TOKEN=abc are the same.
• Limits: at most 50 variables per run, names up to 200 characters, values up to 10 KB each.

Which Values Win#

If a per-run variable has the same name as a saved secret, the per-run value takes priority for that run. The saved secret is untouched. This is the intended way to override a secret temporarily:

API_KEY=staging-token

With that line in the Environment field, env.get("API_KEY") returns staging-token for this run only; scheduled runs keep using the saved secret.

Which One Should I Use?#

Either way, scripts never change: they call env.get and get a value.