Your first site

This walkthrough goes deeper than Quickstart. We connect a repo, look at the site manifest Showly produces, make a change directly in the editor, and ship it.

Connect the repository

From workspace home, click Connect a site. The GitHub app dialog opens. Pick:

• the organization or personal account that owns the repository
• the repository you want to connect

The GitHub App requests Contents: read & write on the repositories you select — GitHub grants this at the repository level, not per branch. As a product policy, Showly only ever commits to branches under the showly/* prefix; it does not push to your default branch.

After authorizing, the repository appears in your workspace with status Importing.

Review the site manifest

The import step writes a showly.json manifest into the imported workspace. This is an auto-detected starting point — Showly inspects the repo and proposes values; you can review and override any field afterward. It looks like this:

{
  "rootDirectory": ".",
  "runtime": "node",
  "runtimeVersion": "22",
  "packageManager": "pnpm",
  "installCommand": "pnpm install",
  "buildCommand": "pnpm build",
  "output": {
    "directory": ".next"
  }
}

The framework is detected automatically (Showly recognizes Astro, Vite, Next.js export, and plain static HTML), so it is not a field you set in the manifest.

The manifest is the source of truth Showly uses for every build and every agent context query. If your repo's build process changes, edit the manifest — don't fight Showly's auto-detection. See Site manifest for the full schema and field reference.

Set environment variables

Open the site's Environment panel and set the variables your build and runtime need. Showly never reads secrets from your repo; you set them per-environment (preview, production), so a preview build can use different values than production.

Make a change in the editor

The Showly editor opens a chat panel beside a file tree. Try:

Add a new route /about with a short bio.

The agent will respond with a change plan listing the files it will create. Click Apply plan to materialize the patch in an isolated workspace, build, and produce a preview.

The build moves through queued → building and lands on ready (a typical small change takes well under a minute). When it reaches ready, the preview URL appears in the Preview panel — open it to see your change live on an isolated preview deployment. If the build instead ends in failed, expand the deployment to read the build logs, fix the issue (often a build command or runtime setting in the manifest), and apply again.

Publish

In the Releases panel, click Request publish on the ready preview you want to ship. This creates an approval request in the pending state and requires fresh step-up MFA before the deployment is promoted.

Who can approve depends on your plan. On the Team plan, where approval workflows are enabled, a publish request needs one approval from an owner or admin, and the person who requested it cannot approve their own request. Once approved, that same preview deployment is promoted to production. See Roles and approvals for the full role list and approval policy.

What you've just exercised

• GitHub import → site manifest
• Per-environment env vars
• Chat → change plan → patch → preview
• Approval → production publish

That's the entire publish loop. Every later workflow in Showly is a variation of this same path.