# Getting Started

URL: https://docs.usestitch.ai/docs/getting-started



Follow these steps in order. Start from the current example; do not design a new workflow first.

## 1. Connect and authenticate [#1-connect-and-authenticate]

Ask the user to [sign in](https://app.usestitch.ai/login), select the intended organization,
and [connect the repository](https://app.usestitch.ai/repositories).

```sh
npm install -g @usestitch/cli
stitch auth login
stitch auth whoami
stitch repositories list
git rev-parse --show-toplevel
git remote -v
```

Node.js 24+ is required. Alternatively use `bunx @usestitch/cli` or `npx @usestitch/cli`.
For another deployment, set `FACTORY_URL` to its HTTPS origin.
Give the user the login result's `verificationUrl` and `userCode`; wait for `authenticated`.
`whoami` must return the intended non-null `organizationId`.
Match the checkout's GitHub owner/repo to an entry with `active: true`.
Save its `id` and `defaultBranch`. Stop if access or the checkout cannot be verified.

## 2. Download the current example [#2-download-the-current-example]

At the verified repository root, read repository instructions and download the
[current starter](/examples/autonomous-delivery.yaml) to `stitch-factory.yaml`.
Preserve it byte-for-byte during this step. Stop if the download fails.
Ask before replacing an existing file. Do not reconstruct the example from memory.

## 3. Explain and agree on changes [#3-explain-and-agree-on-changes]

Read the downloaded file. It triages issues, implements bug/enhancement/chore labels,
reviews newly opened non-draft pull requests for over-engineering, and fixes feedback
from `work_needed` labels or human change-request reviews. It does not review every push.
Explain its run limits, OpenCode harnesses, BYOK Vercel sandboxes, and disabled triggers.

Inspect available repository skills and read relevant instructions. Suggest only skills
you found and explain where they help. Ask whether to keep or change the workflow.
Make only agreed changes; do not redesign it first.

Check the required `build`/`review` agents, `code-review` skill, and GitHub labels.
The starter does not create them. Ask how to resolve missing dependencies.
Replace the Vercel team/project placeholders. Keep triggers disabled until prerequisites
are ready and activation is approved.

## 4. Add secrets privately [#4-add-secrets-privately]

```sh
stitch secrets list
stitch secrets add OPENCODE_API_KEY
stitch secrets add VERCEL_TOKEN
stitch secrets list
```

For the unchanged starter, these are the OpenCode API key and Vercel access token.
If authentication changed, use the names now referenced in the file.
Ask the user to enter values in the CLI's hidden prompt in their private terminal.
Reuse existing secrets; ask before replacing them. Confirm all names exist in the active organization.

## 5. Validate [#5-validate]

```sh
stitch validate --dry-run
stitch validate --repository <connected-repository-id>
```

Resolve missing dependencies and placeholders first. Fix reported errors with agreement.
Validation does not apply configuration or test provider credentials.

## 6. Approve and push [#6-approve-and-push]

Show the final changes. Ask for permission to commit and push, and separately to activate.
If approved, enable only the intended triggers and validate again. Commit only agreed files.
Stitch reads the default branch: another branch must be merged before configuration applies.
Verify the applied state in the [application](https://app.usestitch.ai/repositories),
or report verification as pending. There is no CLI `apply` or startup command.

## Schema [#schema]

[Factory JSON Schema](/schema/factory.json). See [CLI validation](/docs/factory/cli).