---
title: Build, test and publish an app
description: Build a new app or bring existing code, test it locally and in development, then publish the tested version to production.
slug: /getting-started/build-test-and-publish-an-app
order: 13
visibility: public
redirects_from: []
---

# Build, test and publish an app

Prompt:

> Build me a notes app with sign-in. Let me test it before you put it live.

Follow this sequence to take an app from code to a checked production version. Each phase links to the procedure your AI tool follows.

## What your AI tool does

Your AI tool writes or adapts the app, tests its behavior, and deploys it to a development environment. It promotes the tested version when you ask, then checks production.

## What you need

- An AI coding tool connected and signed in through [Connect your AI assistant](/cloud/getting-started/connect-your-tool/).
- A description of what the app should do, or access to the existing project's files.
- For local runs and tests, the software in [What your computer needs](/cloud/getting-started/prerequisites/). Its [Windows PowerShell section](/cloud/getting-started/prerequisites/#windows-powershell) gives the Windows commands.

Without a shell, use [Deploy from a chat](/cloud/getting-started/build-an-app-from-a-chat/) for the file workflow. Your AI tool can check the hosted app, but it reports local tests as not run.

## Before your AI starts

For the AI tool: confirm the intended behavior, the project folder, and whether this is a new or existing application. Ask the person to choose an application's size where needed; [Size and usage](/cloud/guides/plan-and-usage/) explains the choices.

For this workflow, confirm that the person wants development before the first deploy. With nobody to ask, turn it on only if their request already asks for development. Otherwise stop and report before deploying. An application starts with production alone, so a deploy without development puts the version live.

For an unattended run or a computer using a token, follow [Deploy with nobody at the keyboard](/cloud/guides/deploy-with-nobody-at-the-keyboard/). Keep the token's value out of chat.

## Steps

For the AI tool: follow these phases in order. Read each linked procedure before doing its work.

### 1. Start from a template or existing code

For a new app, follow [Starting a new service](/cloud/concepts/turnzero-command/#starting-a-new-service) to choose a template and create the project. The [`notes-app` template](/cloud/concepts/turnzero-command/#the-notes-app-template) provides sign-in and private database notes.

For existing code, read `skill:move-existing-app` with `read_context` and use [Bring an existing application](/cloud/guides/bring-an-existing-application/) to prepare the code. Keep its project layout; do not scaffold over it. Before adding a capability, read [Use the library](/cloud/guides/use-the-library/) to check for a feature package and its integration instructions.

In this phase, prepare the project only. Follow phases 2 and 3 below before any linked procedure reaches a deploy.

### 2. Create the application and turn development on

Read the deployment skill with `read_context`, id `skill:deploy`. Follow [Create the application](/cloud/getting-started/deploy-an-application/#1-create-the-application), reusing the application's identifier if it already exists.

Read `skill:develop-then-promote` and `skill:release` with `read_context`. Then follow [Turn the development environment on](/cloud/guides/turn-on-development-and-promote/#turn-the-development-environment-on), before deploying. Record the development hostname the response returns. Take production's hostname from a later platform response, rather than composing it. Keep each check on its intended environment.

### 3. Declare the services and prepare local settings

Read `skill:manifest-author` with `read_context`, then follow [Author the manifest](/cloud/guides/author-the-manifest/) to submit the whole declaration. For sign-in, also read `skill:add-sign-in` and follow [Add sign-in to your app](/cloud/guides/add-sign-in-to-your-app/).

Before deploying, follow [Store a secret](/cloud/getting-started/store-a-secret/) to supply each secret a manifest setting references, at a scope the target environment reads. Check development and production separately; a value stored only for one does not supply the other.

For a local run, follow [Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/). Its provision command writes the development credentials into the environment file without passing their values through chat. Keep that file out of Git and follow the guide for settings the command does not write.

### 4. Test locally and deploy to development

Follow [Test your application locally](/cloud/guides/test-your-application-locally/) to check the app's behavior. Start and check the real local server using [Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/), then stop the processes you started.

Fix failing checks before deployment. Follow [Deploy to development](/cloud/guides/turn-on-development-and-promote/#deploy-to-development) and its linked upload procedure. Wait until the deploy ends successfully, following the returned status call where needed.

Without a shell, use the linked chat workflow instead. Report which local checks could not run, then perform the hosted checks in phase 5.

### 5. Check the task in development

Follow [Check development before promoting](/cloud/guides/turn-on-development-and-promote/#check-development-before-promoting). Check the behavior the person requested, its saved data where applicable, and the logs. A successful health check alone does not prove the app works.

For sign-in, follow [Test sign-in with test end users](/cloud/guides/test-sign-in-with-test-end-users/), explicitly choosing development. For the notes app, check that a signed-in user can save and read their notes, and another user cannot read them.

Fix a failed check and deploy the corrected version to development before repeating it. Report the checked version and results when asking the person whether to publish it.

### 6. Promote and check production

Promote only when the person has asked for that promote. Otherwise ask and wait. Follow [Promote to production](/cloud/guides/turn-on-development-and-promote/#promote-to-production), including its database migration cautions, and wait for the outcome.

Follow [Check the release](/cloud/getting-started/deploy-an-application/#check-the-release) against production. That section distinguishes read-only checks, first-deploy test-user checks, and other production writes needing the owner's confirmation on an app with real users. Apply those production-write limits when checking signed-in behavior too.

Report the production address, the version serving there, the checks that passed, and anything still unchecked. If the promote fails, read its recorded outcome before choosing the recovery in the linked guide.

## Expected result

Development serves the version whose requested behavior you checked. After an authorized promote, production's status shows that version as deployed, and the production checks report what worked and what remains unchecked.

Your AI tool gives you the production address and check results. In a run without a shell, it identifies local checks as not run.

## Refusals

This table covers common refusals only. The linked procedures and the [refusals reference](/cloud/reference/refusals/) give the other causes and remedies.

| Refusal | Cause | Remedy |
| --- | --- | --- |
| `manifest_missing` | The application has no manifest on file. | Submit it using phase 3 before deploying. |
| `setting_secret_missing` | The target environment lacks a secret a setting needs. | Use [Store a secret](/cloud/getting-started/store-a-secret/), then repeat the refused operation. |
| `deploy_in_flight` | Another deploy is still running. | Read its status and wait for its outcome before starting another. |
| `nothing_to_promote` | Development serves no version and the promote names none. | Complete the development deploy in phase 4 first. |
| `environment_not_created` | The application has production alone. | Confirm the intended workflow and turn development on using phase 2. |

For a local test failure, use [Test your application locally: Refusals](/cloud/guides/test-your-application-locally/#refusals) and the affected package's test-double instructions. If a prerequisite remains unavailable, stop and report what is needed before continuing.

## Related

- [Find the guide for a task](/cloud/getting-started/find-a-guide/) covers other application tasks.
- [Deploy from your computer](/cloud/getting-started/deploy-an-application/) gives the full deploy procedure.
- [Test in development, then promote](/cloud/guides/turn-on-development-and-promote/) explains the environment changes and production switch.
- [Manage versions and environments](/cloud/guides/manage-versions-and-environments/) covers version history and rollback.
