You go from a one-sentence description to a live production app at its own URL. The trip takes about ten minutes. You write no code. This page walks the whole arc, step by step.

1. Use this template

1. Open open-platform/app-template.
2. Click Use this template.
3. Pick an organization as the owner.

Every app belongs to an organization. The registry grants package-write access through org teams. If you have no org yet, first create a personal org such as <you>-apps.

One app already exists: your platform's front door at https://www.open-platform.sh is open-platform/www, the template exactly as shipped, deployed with the platform. It is what a fresh app looks like before the crew touches it — and it is yours to change: file an issue against it like any other app.

2. The name and the description are the spec

There is no spec document. The repo name becomes the app's name. The description is the entire v1 brief for the builder. Write a real sentence, not a placeholder. A better description gives a better v1.

A plain description:

a quick poll app: create a question, vote once, see live results

An ambitious description:

a reading-group tracker: members propose books, vote each month, log chapter progress, and see a group timeline of finished books with short reviews

Click Create. The platform needs no further action from you.

3. The first pull request opens within a minute

The builder picks up the new repo within a minute. It opens the first pull request (PR #1) on the prime branch, titled 🏗️ v1: <app>. The builder works in public. You watch the commits land.

The builder posts a link to a live preview environment. The preview is a real deployment. It has its own database, its own URL, and its own sign-in.

The builder also writes the app's documentation as it builds. The repo's Wiki tab gets an overview plus the pages the app earns (API, data model, runbook). The platform publishes the wiki on merge. The crew keeps it current as the app evolves.

While the 🏗️ prefix is on the PR title, your comments steer the builder. Comment "make the results a bar chart" or "one vote per signed-in user". The builder adjusts mid-build.

4. The reviewer posts one verdict

When the 🏗️ prefix drops, the reviewer takes over. The reviewer signs into the live preview with a real browser. It exercises your core flows and checks security. It then posts exactly one verdict comment.

Verdict	What happens
✅ Ship it	The PR auto-merges and v1 releases.
⚠️ Ship with nits	The PR auto-merges and v1 releases.
❌ Blockers found	The builder reworks the PR. Rework is bounded at 2 rounds, then the work hands to you.
❌ Untestable	An infrastructure failure blocked the review. No rework starts. The PR waits for you.

5. Your app is live

On ✅ Ship it or ⚠️ Ship with nits, the PR auto-merges. The platform releases v1 to:

https://<app>-<org>.open-platform.sh

Sign-in works through Forgejo OAuth from the first visit. The app has its own Postgres database. Metrics already flow. Open the URL and use your software.

What runs underneath

The repo's Actions tab shows the machinery. Three workflows carry the lifecycle:

• check runs lint, typecheck, build, and a boot smoke-test on every push. A red check stops anything from shipping.
• preview builds each PR. It provisions an environment at https://pr-<N>-<app>-<org>.open-platform.sh with its own database and its own OAuth app. The platform tears the environment down when the PR closes.
• release fires on a version tag. It ships the image and the chart. Flux rolls them to production.

CI jobs run in isolated, unprivileged containers on the platform's own runner pool. For the details, see CI and Builds.

Switch it off, or delete it

The repository is the switch, and Forgejo's own permissions guard it.

• Archive the repository (Settings → Danger Zone → Archive this repository; repo admins). The app is switched off but its data is kept: every PR preview is torn down, the web pods go to zero, the database hibernates on its disk. Visitors see an "archived" page. The repo is read-only, so the crew leaves it alone. Unarchive and it comes back as it was.
• Delete the repository (repo owners and org admins). Everything goes, for good: the running app, its database and disks, its preview environments, its login credentials, and its built images and charts. The platform confirms with Forgejo that the repo is really gone before it removes anything.

Keep going

v1 is a starting point. Issues are your roadmap. Agents are your build crew.

1. Open an issue that describes what you want.
2. Add the agent-work label.

An agent builds the change on a branch. It opens a PR with a live preview. The same reviewer gates the PR.

The next skill is writing good issues, steering with comments, and wiring dependencies between them. That skill is the next page: Building with Issues. To describe a whole product instead of one app, see Orgs and Planning.

Warning: never paste credentials into an issue or a comment.

To give your app the API keys it needs, see Secrets and Config.