docs / getting-started

Getting started

On this page

Prerequisites
1. .sprout.yaml at the repo root
2. CI variables (you set these)
3. CI wiring (one include)
What you get
Next step
See also

Reach a first preview in one sitting: one .sprout.yaml, two CI variables, one CI include. About five minutes on a repo that already ships a Dockerfile that serves HTTP.

This lesson takes the GitLab path. On GitHub the steps are the same shape with a caller workflow instead of an include — branch at step 3 to CI integration and rejoin at What you get.

Exact key contract: Adopting a repo.
Gateway setup (operator work): Operator deploy.

text · prompt onboarding-prompt.md

You are onboarding this repository to sprout (every pull request gets its own
preview database plus an optional preview app).

Step 1 — read the docs first, in this order.
1. https://simpros.github.io/sprout/llms.txt — the index of every doc page.
2. https://simpros.github.io/sprout/docs/adopting-a-repo.md — the
   `.sprout.yaml` manifest reference.
3. https://simpros.github.io/sprout/docs/ci-integration.md — CI wiring for
   this forge (GitLab component or GitHub reusable workflow).
Fetch each URL; do not rely on memory of this product.

Step 2 — inspect the repo before writing anything. Runtime and package
manager, the Dockerfile(s), how migrations run, whether fixtures/seed data
exist, which forge hosts it, and the existing CI workflow files. State what
you found in one short paragraph.

Step 3 — derive, then confirm. Propose `slug` and the preview hostname
template (must contain `{pr_id}`, bare host, no scheme/port/path) from the
repo name and its existing deploy conventions, and ask me to confirm both
before you write them. Never invent a domain or a hostname pattern.

Step 4 — write only these files.
- `.sprout.yaml` — the minimal working config: `slug`, `preview.hostname`,
  plus `health` and `seed`/`db`/`services`/`mail` only where this repo
  actually needs them. Match the manifest keys exactly
  (`unknown key: <path>` rejects typos).
- `Dockerfile.seed` — only if preview data is wanted and no seed image
  exists yet.
- The CI file for this forge: the GitLab one-include component
  (`templates/preview.yml` shape, `sprout_version` pinned) or the GitHub
  caller workflow (`examples/adopting-repo/.github/workflows/sprout.yml`
  shape, `sprout_version` pinned, `contents: read` + `pull-requests: write`
  + `packages: write`).

Step 5 — tell me the CI variables to set myself (names, masked/secret,
where they go): `SPROUT_URL` (gateway URL), `SPROUT_TOKEN` (deploy token
scoped to this repo), optional `SPROUT_APP_ENV` / `SPROUT_SEED_ENV` dotenv
blobs and `GITLAB_TOKEN` for MR notes. Do not create, print, commit or
guess their values. If you cannot find a required value, ask me. Never
deploy against an unverified gateway URL without asking.

Step 6 — verify what you can without a running gateway: run the CLI's own
manifest loader over the file you wrote (`apps/cli/src/yaml.ts`
`parseSproutYaml`) and paste the result. Then name my next step
(`sprout doctor`, then a first `sprout ci preview` run from CI).

Do not:
- rewrite or refactor application code,
- touch files other than the ones in Step 4,
- invent operator-side settings (`SPROUT_PREVIEW_POSTGRES_URL`,
  `SPROUT_TRAEFIK_*`, networks), tokens or endpoints,
- run a deploy or open a PR against a live instance without asking me first.

When you are done, summarise in five lines: files written, values you
confirmed with me, CI variables I must set, commands I should run next,
anything you could not determine.

Prerequisites

A repo with a Dockerfile that serves HTTP.
A gateway URL plus a deploy token for the repo from the operator. Bootstrapping is operator work: Operator deploy.
Merge-request pipelines (GitLab) or pull_request workflows (GitHub).

Copy-paste app files live in examples/adopting-repo/README.md.

1. `.sprout.yaml` at the repo root

Write this file. Replace myapp and the domain with values confirmed with a human — never invent a domain. The template must contain {pr_id} as a bare host: no scheme, port, or path.

yaml .sprout.yaml

slug: myapp
preview:
  hostname: "pr-{pr_id}.myapp.preview.example.com"

Unknown keys are rejected (unknown key: <path>), so typos fail on the first sprout ci preview.

When this deploys, add seeding next: Adopting a repo.

2. CI variables (you set these)

Set two masked variables in the repo's CI settings:

SPROUT_URL — the gateway URL. (Alternatively pass the sprout_url input; one of the two is required.)
SPROUT_TOKEN — the deploy token scoped to this repo's canonical id.

For GitLab MR notes, an optional GITLAB_TOKEN (masked) lets the CLI create notes; without it the CLI falls back to CI_JOB_TOKEN on a best-effort basis either way.

App or seed secrets never go in the manifest. Declare { required: true } there and supply values here as masked File variables (SPROUT_APP_ENV / SPROUT_SEED_ENV dotenv blobs).

3. CI wiring (one include)

Add the include to .gitlab-ci.yml. Replace <group>/sprout-ci with the component project path on the instance and v0.9.0 with the adopted release:

yaml

include:
  - component: $CI_SERVER_FQDN/<group>/sprout-ci/preview@v0.9.0
    inputs: { stage: deploy }

Open a merge request. The sprout-preview job installs the pinned CLI, builds and pushes the app image, deploys, and posts the MR note with the preview URL.

What you get

Open / synchronize: the job deploys and writes PREVIEW_URL=. Read the URL from the CLI output — never reconstruct the hostname in CI.
Close / merge: sprout ci teardown runs via on_stop (idempotent — exit 0 when already gone).
Manual wipe + redeploy: sprout ci reset (data wiped).
A missed teardown is recovered by the gateway sweep.
The gateway reports anonymous install telemetry by default (SPROUT_TELEMETRY=off stops it) — operator concern, nothing to do in this lesson.

Next step

Run the agent block in Onboarding prompt, or verify by hand: sprout doctor, then a first sprout ci preview run from CI.