Deploy and promote

You need the Dagy package, a working workspace connection, and flows.read, flows.write, runs.trigger, and runs.read. The default read-only UI key cannot deploy. For interactive work, a developer, admin, or owner session is sufficient; promotion also needs owner/admin environment permissions.

Build a small flow

Save this as orders.py in your project:

from dagy import flow, task

@task
def fetch_orders(region: str) -> list[dict]:
    # Replace this fixture with your application's real source integration.
    return [{"order_id": "order-001", "region": region, "amount": 42.0}]

@task
def total_orders(orders: list[dict]) -> float:
    return sum(order["amount"] for order in orders)

@flow(name="orders_daily")
def orders_daily(region: str = "eu"):
    return total_orders(fetch_orders(region))

Keep task definitions in the same file for this first deployment. Use run_local() to ensure local execution even with a hosted API configured, then build the artifact:

python -c "from orders import orders_daily; print(orders_daily.run_local(region='eu'))"
dagy build orders.py:orders_daily --output-dir ./dist

The build command prints Artifact: .../artifact.zip. Use that exact path in the next command. The builder packages the flow source file and generated specification/metadata; it is not a general recursive project packager. Additional local modules, data files, and native/system libraries are not automatically included. See dependency packages for supported third-party Python dependencies.

Building captures the flow graph. It does not perform external task work. Use task functions for side effects, and keep graph construction deterministic.

Deploy into develop

Sign in if you have not already, with the API URL set as in the connection guide:

dagy login
dagy -e develop deploy /PATH/PRINTED/BY/BUILD/artifact.zip \
  --deployment orders-develop \
  --execution-mode nano \
  --yes

Replace the placeholder artifact path. The default environment is develop. The deployment command uploads the artifact and reports its version and deployment. It derives the flow name from the artifact. Add --namespace analytics to group it under a chosen namespace.

--dry-run previews the target without uploading. --yes skips the CLI confirmation, which is useful in an authorized automated release. Unchanged code hashes cause deployment to be skipped; use --force when you deliberately need another deployment despite unchanged code, such as creating a target that does not yet exist. Do not assume an unchanged-code skip updated runtime, schedule, or target-environment settings.

A deployment references a version; later deployments can change that reference. Record the resulting version with your application release so you can identify and roll it back.

Start and verify a run

dagy run orders-develop --environment develop --param region=eu
dagy runs list --limit 10 --format json

The first command submits a remote run and prints its ID. Inspect hosted details and logs with the REST API, using a service key with runs.read supplied as DAGY_TOKEN by your secret manager:

export RUN_ID="YOUR_RETURNED_RUN_ID"
curl --fail-with-body "$DAGY_API_URL/runs/$RUN_ID" \
  -H "Authorization: Bearer $DAGY_TOKEN"
curl --fail-with-body "$DAGY_API_URL/runs/$RUN_ID/logs" \
  -H "Authorization: Bearer $DAGY_TOKEN"

The current dagy runs show and dagy logs commands inspect local history only. For a saved CLI session without a service key, use the api() helper from Connect to your workspace with api("GET", "/runs/YOUR_RUN_ID") and api("GET", "/runs/YOUR_RUN_ID/logs").

Check that the run reaches SUCCEEDED. A queued response only confirms submission. Inspect failed task records and logs before retrying. The same operation through REST is:

curl --fail-with-body -X POST "$DAGY_API_URL/runs" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deployment":"orders-develop","parameters":{"region":"eu"}}'

Here DAGY_TOKEN is the example bearer variable; obtain an application key through the connection guide. For client code that uses it explicitly, see the runs API.

Configure runtime, dependencies, and scheduling

Choose a tier that fits the flow using Execution. The accepted tiers are nano, micro, small, medium, large, and xlarge; availability depends on the workspace.

Attach completed dependency packages at deployment:

dagy -e develop deploy /PATH/PRINTED/BY/BUILD/artifact.zip \
  --deployment orders-develop \
  --execution-mode micro \
  --dep-packages YOUR_PACKAGE_SLUG \
  --force --yes

After deployment, you can update runtime or dependency settings through PUT /deployments/orders-develop/settings without rebuilding the code. See Flows and deployments.

For a daily run, create an explicit schedule with the correct deployment, version, and timezone. CLI deployment also accepts --schedule "0 6 * * *" --timezone UTC for a cron schedule. Read the resulting schedule's enabled state and next-run time to verify it.

Promote and validate a release

1. Create the destination environment, such as staging, and configure its variables and secrets.
2. Preview and promote the deployment:

dagy promote orders-develop staging --deployment-name orders-staging --dry-run
dagy promote orders-develop staging --deployment-name orders-staging --yes

3. Inspect the target deployment. Promotion currently omits execution tier and dependency-package attachments; explicitly reapply those settings before running.
4. Submit a small staging run with test inputs and inspect outputs/logs.
5. Create or update the target schedule or event trigger only after validation.

Promotion copies the version reference, not the effects of prior runs. It does not copy variables or secrets or enforce an approval gate. See promotion details before automating it.

Roll back safely

List registered versions with GET /flows/orders_daily/versions. Select a known working version and call:

POST /deployments/orders-staging/rollback

{"target_flow_version":"1"}

Read the deployment again and run a small verification workload. Rollback changes the active code version; it does not restore old secret/variable values, remove output data, or undo notifications. If outputs need repair, plan a bounded backfill with idempotent writes.

Release considerations

Pin dependency versions for reproducible runs. Include every required module in the artifact or supported package path, and test imports on the selected runtime. Use explicit environments and stable deployment names in applications. Keep business input identifiers in parameters but keep credentials in secrets.

For production integration work, budget run and API usage, inspect errors after every release, and keep the previous version available. See Errors and retries and usage. Custom upload clients should follow the artifact protocol instead of inventing storage locations.