# 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. Source: https://support.orkosi.com/docs/deploy-guide 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 ```text task created ──▶ agent builds on branch task/ ──▶ automated review ──▶ merged into dev │ GitHub push webhook ──┘ ▼ dev environment: build image ──▶ deploy ──▶ verify ──▶ live │ you click "Promote" ───┘ ▼ main branch ──▶ prod environment deploy ──▶ live ``` 1. **Build.** A worker claims your task, checks out a `task/` branch of your repository and implements the change. You can watch the build log live from the task panel. 2. **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. 3. **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. 4. **Deploy to dev.** The push to `dev` triggers a webhook that Orkosi verifies and turns into a deployment of your **dev environment**. 5. **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..orkosi.app` | `https://.orkosi.app` or your custom domain | | Database schema | `tenant_` | `tenant__prod` | | Database role | `app__dev` | `app__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](https://support.orkosi.com/docs/database). 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](https://support.orkosi.com/docs/billing). > **Tip:** Treat dev as your staging area. Agents deploy there without asking, so you can test each change at `dev..orkosi.app` before anyone else sees it. ## Promoting dev to prod 1. Open your product hub and go to **Hosting**. 2. Check the dev environment is `live` and behaves as you expect. 3. 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: ```bash curl -X POST "https://api.orkosi.com/api/customer-apps//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: 1. Go to **Hosting → Deployments** for the environment. 2. Find the deployment you want to restore and choose **Rollback**. 3. 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 #_. 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](https://support.orkosi.com/docs/telegram). Each successful deployment is metered as one build unit on your usage page. See [Billing](https://support.orkosi.com/docs/billing).