SpinneryDocs
Browse documentation

Docs / Repo-prep PR flow

Repo-prep PRs make workspace setup reviewable.

Spinnery starts by reading the repository, then opens a small spinnery.yml setup PR. The PR is the place to review previews, inputs, outputs, environment mappings, setup commands, and tests before any branch workspace depends on them.

Review repo contractBack to first workspace
repo prepreview first

$spinnery repo connect

repo: github.com/acme/scheduler

detected: npm, Vite web, Backend /api

$spinnery prepare-pr

PR opened: add spinnery.yml workspace contract

Flow

Prepare the repo before the first runtime wakes.

The setup PR is deliberately small. It names the workspace contract in code review so the first spin up uses a shared, approved shape instead of a one-off operator note.

  1. Discoverspinnery repo connect

    Read the repo before writing config

    Detect the package manager, service command, ports, test entry points, and obvious resource inputs before opening a setup PR.

  2. Draftspinnery prepare-pr

    Open one focused spinnery.yml PR

    Keep the diff reviewable: Compose previews, cross-service inputs and outputs, environment mappings, setup commands, and tests in the repo that owns them.

  3. Reviewrepo owner review

    Approve the workspace contract

    Repo owners review the same contract branch workspaces will use, including how the service receives URLs, resources, and dev traffic.

  4. Runspin up <branch>

    Branch workspaces inherit the PR

    After merge, developers and agents attach to the reviewed workspace shape instead of rebuilding local setup from memory.

Review surface

Review the contract before branch workspaces depend on it.

The PR should read like an application contract, not cloud wiring. Repo owners should be able to check the service command, resource inputs, previews, setup commands, and test commands behavior without seeing raw VM hostnames or cloud credentials.

spinnery.ymlsetup PR
version: 1

compose:
  file: docker-compose.yml
  previews:
    - service: web
      port: 5173
      hmr: true

default_preview: web

inputs:
  api_url:
    required: true
    description: URL exposed by the API service

outputs:
  app_url:
    from: service.url

environment:
  VITE_API_URL:
    from: input.api_url
  APP_KEY:
    secret: app-key
  VITE_APP_ENV:
    value: development

setup:
  install:
    - npm install

tests:
  unit:
    - npm test

cli:
  seed:
    command: npm run seed
    description: Seed development data

Acceptance

A repo-prep PR is ready when review can answer these checks.

Keep setup review focused on what future workspaces will actually run and expose. Anything private stays behind authenticated workspace access or control-plane secret handling.

  • The PR is one repo-scoped spinnery.yml change, not a generated cloud dump.
  • Compose previews, environment mappings, setup commands, and tests are visible enough for repo owners to verify.
  • Inputs name contracts like API_URL or DATABASE_URL instead of embedding shared secrets.
  • Preview routes expose application ports without exposing SSH, logs, secrets, or runtime admin.
  • Docker Compose remains the source of truth for commands, health checks, volumes, and same-repository dependencies.