Variables & Secrets

The ctx.vars and ctx.secrets objects provide access to environment variables and secure secrets during run execution.

For env file naming, load order, and system fallback, see Environments & Secrets. This page focuses on SDK runtime access patterns.

The rule

Put normal runtime config in ctx.vars and sensitive values in ctx.secrets. For shared HTTP setup, prefer configure() with {{KEY}} placeholders so secrets stay out of source and every check imports the same client.

Required vs optional

Use require() when the test cannot continue without a value. Use get() when a sensible fallback exists.


export const healthCheck = test("health", async (ctx) => {
  const baseUrl = ctx.vars.require("BASE_URL");
  const region = ctx.vars.get("REGION") ?? "us-east-1";
});

Secrets

Secrets should always be accessed through ctx.secrets. Do not put API keys in ctx.vars.


export const requireApiKey = test("require-api-key", async (ctx) => {
  const apiKey = ctx.secrets.require("API_KEY");
  ctx.assert(apiKey.length > 0, "API key secret is configured", {
    actual: apiKey.length > 0,
    expected: true,
  });
});

Values read through ctx.secrets are registered as sensitive runtime values and participate in the runner’s redaction pipeline. Still avoid logging secrets, derived tokens, signatures, or manually concatenated credential strings — use {{KEY}} placeholders in shared clients and keep secret-shaped values out of assertion messages and custom logs.

For project code, the same auth is usually cleaner in configure():


import { configure } from "@glubean/sdk";
 
export const { http: api } = configure({
  http: {
    prefixUrl: "{{BASE_URL}}",
    headers: {
      Authorization: "Bearer {{API_TOKEN}}",
    },
  },
});

Validation functions

You can pass a validator to require() when presence alone is not enough:


export const validateConfig = test("validate", async (ctx) => {
  const port = ctx.vars.require("PORT", (v) => !isNaN(Number(v)));
 
  const jwt = ctx.secrets.require("JWT_TOKEN", (v) => {
    const parts = v.split(".");
    if (parts.length !== 3) {
      return "must be a valid JWT containing 3 parts separated by dots";
    }
    return true;
  });
});

Validator return values:

true, undefined, or null — validation passed
false — validation failed (generic error)
string — validation failed with a custom error message

Using with configure()

When many checks share the same vars and secrets, declare them once with configure(). Values use {{KEY}} template syntax and resolve lazily:


import { configure, test } from "@glubean/sdk";
 
const { vars, secrets, http } = configure({
  vars: { baseUrl: "{{BASE_URL}}" },
  secrets: { apiKey: "{{API_KEY}}" },
  http: {
    prefixUrl: "{{BASE_URL}}",
    headers: { Authorization: "Bearer {{API_KEY}}" },
  },
});

See Configuration for full details.