Environments and variables

The built-in develop environment is permanent. Additional environments are workspace resources; create and configure them with environments.write (owner/admin), and read them with environments.read. Full request fields are in the OpenAPI reference.

Create an environment

curl --fail-with-body -X POST "$DAGY_API_URL/environments" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "env_name":"staging",
    "variables_json":{"DATA_PREFIX":"staging/orders"},
    "promotion_order":1,
    "upstream_env":"develop",
    "is_protected":false,
    "color":"#0d9488"
  }'

POST returns 201 with env_name, workspace metadata, variables, display/order settings, and timestamps. Additional fields include default_executor and config_json. Prefer deployment execution_mode for routine runtime selection; an arbitrary config_json property does not automatically configure a runtime feature.

is_protected prevents deletion. It does not enforce deployment approval, a promotion gate, or member access separation. upstream_env and promotion_order describe the intended progression; they do not enforce that every release passes through each stage. Use approval nodes for supported workflow approval behavior.

Deleting develop returns 400; deleting a protected or missing environment returns 404. Before deleting another environment, remove or move its deployments and schedules and retain needed configuration.

Set runtime variables

Active variables become strings available to executed Python tasks through os.getenv():

import os

prefix = os.getenv("DATA_PREFIX", "orders")

Set them using the environment API:

curl --fail-with-body -X PATCH "$DAGY_API_URL/environments/staging/variables" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"DATA_PREFIX":"staging/orders","BATCH_SIZE":"1000"}}'

Do not use DAGY_ or AWS_ prefixes for custom variables; those names are reserved and skipped during injection. Disabled variables are not supplied to task code. Store JSON as an explicit serialized string if your application needs to parse it; values are otherwise stringified, not automatically decoded into Python structures.

Variables are readable configuration, not secret storage. Use secrets for credentials. Configuring an environment does not change a local dagy run file.py:flow process; provide local values through your normal local environment.

Compare environments

GET /environments/develop/diff/staging compares deployments grouped by flow. It returns:

• only_in_source: flows deployed in develop but not staging.
• only_in_target: flows deployed in staging but not develop.
• version_differs: source and target deployments whose flow versions differ.

This is a deployment/version comparison. It does not compare variable values, secrets, runtime tiers, or every dependency setting. Inspect those separately before release.

Promote a deployment

Promotion creates or replaces a deployment in the target environment using the source's flow/version. It requires environments.write and an existing source deployment and target environment.

curl --fail-with-body -X POST "$DAGY_API_URL/environments/promote" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_deployment":"orders-develop",
    "target_environment":"staging",
    "new_deployment_name":"orders-staging"
  }'

The 201 response contains source_deployment, target_deployment, target_environment, flow_name, flow_version, promoted_from_env, and promoted_at. Optional flow_version selects another registered version. Without new_deployment_name, the target name is the flow name followed by - and the environment name. Promotion can replace an existing target, so choose the name deliberately.

Before starting production work, read GET /deployments/orders-staging and explicitly configure its desired settings:

PUT /deployments/orders-staging/settings

{"execution_mode":"micro","dep_package_slugs":["YOUR_PACKAGE_SLUG"]}

The current promotion operation copies the flow/version, schedule text, and tags, and chooses the target environment's default executor when provided. It does not preserve execution tier or dependency-package attachments. Reapply those settings. A copied schedule string alone does not establish automatic execution in the target; create or update the target schedule.

Variables and secrets are not copied by promotion. Configure destination-specific values and use secret copy only when both environments should use the same credential. Run a small validation workload in the target, inspect the resulting run environment/version, then enable normal triggers.

Common problems