Vars

Plain configuration for your workflows: a workspace value, overridden per workflow, changed without a redeploy.

Reading vars

Your code reads vars from the run context. A name that is not set reads as absent, not as an error.

refund-check

import { workflow } from "shiftlabs";

export default workflow<{ id: string }>(async ({ payload, vars, log }) => {
  const region = vars.REGION ?? "us-east";
  const limit = Number(vars.REFUND_LIMIT_CENTS ?? "5000");
  log.info("checking refund", { id: payload.id, region, limit });
});

from shiftlabs import workflow


@workflow
async def refund_check(ctx):
    region = ctx.vars.REGION or "us-east"
    limit = int(ctx.vars["REFUND_LIMIT_CENTS"] or "5000")
    ctx.log.info("checking refund", {"id": ctx.payload["id"], "region": region, "limit": limit})

vars.NAME
TypeScript: a string, or undefined when the var is not set.
ctx.vars.NAME ctx.vars["NAME"]
Python: a string, or None when the var is not set.
{{ var.NAME }}
In a connection template, the gateway fills it in for the calling workflow. There a var that is not set refuses the request.

Values are always strings. Parse numbers, flags or JSON yourself.

Workspace and workflow

A workspace var applies to every workflow. A workflow's own var with the same name wins for that workflow only.

shellcurl

# A workspace var (developer key). Answers {"name", "value", "workflow": null, "updatedAt"}.
curl -X PUT https://api.shiftlabs.org/v1/vars/REGION \
  -H "authorization: Bearer $SHIFTLABS_API_KEY" -H "content-type: application/json" \
  -d '{"value": "us-east"}'

# refund-check's own value wins over the workspace's.
curl -X PUT https://api.shiftlabs.org/v1/workflows/refund-check/vars/REGION \
  -H "authorization: Bearer $SHIFTLABS_API_KEY" -H "content-type: application/json" \
  -d '{"value": "eu-west"}'

# Delete the override: refund-check reads the workspace value again.
curl -X DELETE https://api.shiftlabs.org/v1/workflows/refund-check/vars/REGION \
  -H "authorization: Bearer $SHIFTLABS_API_KEY"

Vars · ridgeline-ops

2

Name	Value	Overridden by
`REFUND_LIMIT_CENTS`	`5000`	—
`REGION`	`us-east`	refund-check

Workflow overrides

edit them on each workflow

Workflow	Name	Value
refund-check	`REGION`	`eu-west`

Updated 2026-10-20 21:05 UTC

Takes effect
No redeploy. Each time a run is dispatched, its code loads with the current values, so a run that resumes after a sleep reads the new ones.
Keep a value
To hold on to the value a run started with, return it from a step.run: a resumed run gets the stored result.
Before deploy
A workflow's vars can be set before its first deploy.
Deleting
Deleting a workspace var leaves workflow overrides in place.

Vars are not secrets

Use a var for a region, a channel or a threshold. Put credentials in a secret.

Readable
Everyone in the workspace, viewers included, can read every var and its value, in the dashboard and at GET /v1/vars.
Plain text
Secrets are sealed with your workspace's own data key, and no endpoint returns their values. Vars are stored as they are and listed with their values.
In your code
Your code holds the value itself, not a stand-in, so it goes wherever the code sends it: logs, step results, any host.
Audited
Every change is written to the audit log as var_put or var_delete, with the workflow for an override.

Dashboard and API

Developers and admins add, change and delete vars. Viewers read them.

Vars screen
The workspace vars, each with the workflows that override it, and the overrides below. Add or change one with its name and value, or edit and delete it from its row.
Workflows screen
Open a workflow and find its Vars section: its own values, and the workspace vars it inherits marked tenant. Save for this workflow sets an override.
Names
Uppercase letters, digits and underscores, starting with a letter, up to 64 characters: the same rule as secret names. Another name answers 400 {"error": "invalid var name"}.
Values
A string of up to 4 KiB (4,096 bytes as UTF-8). A longer value, or one that is not a string, answers 400.

Routes
Route	Method	Minimum role
`/v1/vars` every var: [{name, value, workflow, updatedAt}], workflow null for workspace vars	GET	viewer
`/v1/vars/:NAME` {"value"}	PUT · DELETE	developer
`/v1/workflows/:workflow/vars/:NAME` {"value"}	PUT · DELETE	developer

PUT answers the var. DELETE answers {"deleted": "NAME"}, or 404 {"error": "var not found"}.