Environments

Environments let one project carry parallel resource configurations - most usefully separate credential sets (a staging Linear workspace vs the production one) - without duplicating workflows.

Environment model

Each Rensei project can define named environments (e.g. dev, staging, prod) - rows in the project_environments table, unique per project. They are managed in Project Settings → Environments (operators also have an admin surface at Admin → Project Environments).

No environments are auto-created. When a credential ref doesn't name an environment, resolution uses the implicit environment name default.

Per-environment credentials (shipped)

This is the environment surface that is live end-to-end. Each environment holds credential bindings: a mapping from an env-var name (e.g. LINEAR_API_KEY) to a stored credential. Bindings are managed in Project Settings → Environments → [environment] → Credentials.

Workflow definitions reference them with $ref expressions:

Two rules to know:

• Explicit env never falls back. project.credential.staging.LINEAR_API_KEY fails loudly if staging has no LINEAR_API_KEY binding - it does not silently fall back to default.
• Org-pool fallback by name is unconditional. When no project-env binding matches, the resolver falls back to the org credential pool by name.

At dispatch time the credential adapter resolves bindings for the session's (projectId, envName) tuple and snapshots them into the worker's credential set. This means your dev environment can use a sandbox Linear workspace while prod uses the real one - with no change to the workflow definition.

Environment-scoped resources (plumbing shipped, not yet active)

project_resources rows carry an optional env_name column scoping a resource to one environment (NULL = applies to all environments). The resolver prefers an env-specific row over the env-agnostic one when both match (project, kind, role) - but executor call-sites do not yet pass an active environment, so in practice resolution today runs env-agnostic. This is the substrate for future per-environment model/capacity overrides, not a feature you can drive yet.

The environment picker (editor)

Node config fields that take an environment render the Environment Ref Picker - a combobox listing the project's environments with inferred tier badges (prod / staging / dev). Selecting one emits { "$ref": "project.environment.<name>" } into the node config (or a raw string in static mode). It is a value picker for environment-typed config fields - it is not a per-node override table showing each environment's resolved ref values (that UI does not exist).

Selecting the active environment (not yet available)

There is currently no way to choose an environment per run:

• The manual trigger API has no environmentName parameter.
• Webhook/subscription triggers have no per-project default-environment setting.
• The editor's execution toolbar has no environment dropdown.

Credential refs that name an environment explicitly (project.credential.staging.…) are the one per-environment mechanism a workflow can use today. If you need fully distinct dev/prod behaviour now, clone the workflow per environment and point each clone's refs at the right environment.

Environments in lifecycle config

The lifecycle config (spec.lifecycle) uses tracker-native state names. If you use different Linear teams per environment, the tracker state names may differ - use environment-specific workflow variants (clone the workflow and customise the lifecycle config) rather than trying to parameterise lifecycle state names. See Lifecycle Config.

Feature flags per workspace

Workflow feature flags are resolved per workspace, not per environment. Feature flag availability for your workspace is managed by your Rensei operator. This is separate from environments, which scope resource configuration rather than feature availability.

Related pages

• Credentials Overview - credential storage and the dispatch adapter
• Publish and Deploy - the workflow lifecycle
• Foundational Nodes - the node types environments will eventually override
• Lifecycle Config - tracker-native state names per environment considerations