Deploy guide

How a change reaches your users. The task pipeline, dev and prod environments, promoting to production, rolling back, and what determines build time.

Every product on Orkosi has its own GitHub repository and its own hosted environments. This guide explains how a change travels from a task to a running deployment, and how you control what reaches production.

How deployments work

task created ──▶ agent builds on branch task/<id> ──▶ automated review ──▶ merged into dev
                                                                                │
                                                          GitHub push webhook ──┘
                                                                                ▼
                                       dev environment: build image ──▶ deploy ──▶ verify ──▶ live
                                                                                │
                                                         you click "Promote" ───┘
                                                                                ▼
                                                    main branch ──▶ prod environment deploy ──▶ live

Build. A worker claims your task, checks out a task/<id> branch of your repository and implements the change. You can watch the build log live from the task panel.
Review. When the build finishes, an automated reviewer inspects the result. A rejection sends the task back for a fix pass; an approval moves it to the merge queue. There is no pull request for you to manage.
Merge. The merge queue merges the task branch into the dev branch and deletes the branch. If the merge conflicts with newer work, the task is rebuilt cleanly from the current dev instead of failing.
Deploy to dev. The push to dev triggers a webhook that Orkosi verifies and turns into a deployment of your dev environment.
Promote. When you are happy with what you see on dev, you promote it. Orkosi merges dev into main and deploys your production environment.

A deployment itself goes through these states, visible in Hosting → Deployments:

State	Meaning
`queued`	Waiting for the previous deployment of this environment to finish (one active deployment per environment)
`building`	Cloning your repository and building the container image
`pushing`	Pushing the image to the registry, tagged with the commit SHA
`deploying`	Updating the Lambda function (or App Runner service) to the new image
`verifying`	Waiting for the rollout and probing the health endpoint
`live`	Serving traffic. The previous live deployment becomes `superseded`
`failed` / `rolled_back` / `cancelled`	Something went wrong, the platform reverted, or you cancelled it while queued

Dev vs prod environments

	Development	Production
Git branch	`dev`	`main`
URL	`https://dev.<slug>.orkosi.app`	`https://<slug>.orkosi.app` or your custom domain
Database schema	`tenant_<slug>`	`tenant_<slug>_prod`
Database role	`app_<slug>_dev`	`app_<slug>_prod`
Deployed by	Every merged task, automatically	You, by promoting
Environment variables	Managed per environment	Managed per environment

The two environments run the same code path on the same infrastructure but never share data: each has its own schema and its own credentials. See the Database guide.

How many environments you get depends on your plan. The Free Trial provides one hosted production environment; Starter and above provide dev and production. See Billing.

Tip: Treat dev as your staging area. Agents deploy there without asking, so you can test each change at dev.<slug>.orkosi.app before anyone else sees it.

Promoting dev to prod

Open your product hub and go to Hosting.
Check the dev environment is live and behaves as you expect.
Click Promote to production and confirm.

Behind the button Orkosi performs a server-side merge of dev into main on GitHub, then requests a production deployment of the resulting commit. If dev already built an image for that exact commit, the production deployment reuses it and skips the build, so promotion is typically a service update rather than a rebuild.

If main already contains everything on dev, promotion reports that production is up to date. If the merge conflicts, promotion stops and shows the conflicting files; create a task asking the agent to reconcile main and dev, or contact support.

The Promote button is disabled while another promotion is in progress or while production is paused.

You can also promote through the API:

curl -X POST "https://api.orkosi.com/api/customer-apps/<appId>/hosting/promote" \
  -H "Authorization: Bearer $ORKOSI_TOKEN"

Rolling back

Every successful deployment is recorded with the commit it shipped and the immutable image it used. To return to an earlier one:

Go to Hosting → Deployments for the environment.
Find the deployment you want to restore and choose Rollback.
Confirm. A new deployment is created with the trigger rollback.

Because the image for that commit already exists, a rollback does not rebuild anything. It is a service update to the older image and typically completes in under a minute. The history shows it as Rollback of #<id>.

Rollbacks are also automatic in one case: if a new deployment's instances fail their health checks during rollout, the platform reverts to the previous version and records the deployment as rolled_back.

Warning: A rollback restores code, not data. If the newer version ran a database migration, the older code will run against the migrated schema. Templates are written so that migrations are additive, but check the deployment log if you roll back across a migration.

Build times and what affects them

Typical durations observed on the platform:

Operation	Typical time
Full image build and deploy	Around 3 to 4 minutes
Promote or rollback with an existing image	Under 1 minute
Cold start of an idle Lambda function	1 to 2 seconds for the first request, then tens of milliseconds

What makes a build slower or faster:

Whether the image already exists. Images are tagged by commit SHA. Promotions and rollbacks reuse them; only new commits build.
Dependency changes. A task that adds or upgrades packages invalidates the install layer and rebuilds it.
Template type. Mobile and desktop templates build a web preview only; the SaaS and Shopify templates build the full server and client.
Queueing. One deployment per environment runs at a time. If two tasks finish together, the second waits in queued.
Verification. After the rollout, the platform probes your health endpoint up to 12 times, 10 seconds apart. A slow-starting app adds time here; a broken one fails the deployment.

Safety limits: the platform waits up to 20 minutes for a rollout and cancels deployments that exceed it. Keep-warm pings run every five minutes so that production rarely cold-starts.

Following a deployment

Live log stream — open a deployment to watch build output as it happens; the log is kept afterwards.
Deployment history — every environment lists its deployments with state, trigger (push, promote, rollback), commit and duration.
Runtime logs and metrics — Hosting → Logs shows the last 15 minutes of application logs by default; Metrics shows requests and latency over the last 24 hours.
Cancel — a deployment can be cancelled while it is still queued.
Telegram — /deploy returns each environment's state and URL. See Telegram operations.

Each successful deployment is metered as one build unit on your usage page. See Billing.