Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.slipway.sh/llms.txt

Use this file to discover all available pages before exploring further.

A slipway Convoy is a multi-repo composition: N GitHub repositories sharing one variable scope, one secret scope, and a deterministic public URL pattern. There are two kinds of environments:
Convoys list
KindWhat it is
ConvoyThe user-created definition. Lists which repos participate and what ref each one tracks (main, v1.0.0, a SHA). May optionally run as a stable “primary instance” deployed at those tracked refs.
InstanceA child environment spawned automatically when a PR opens against one of the convoy’s tracked refs. The triggering repo runs at the PR branch; sibling repos stay frozen at the SHAs they spawned with. Closed PR ⇒ instance teardown.
The convoy/instance split is the answer to “how do I get a preview for every PR?” — the convoy defines what the stack looks like; each PR gets its own instance instantiated from that definition.

​
Why two kinds

  • Convoys are stable, slow-moving things. A convoy named staging might track main on every repo and run as a primary instance — your team’s always-on staging URL.
  • Instances are short-lived previews. Each open PR against main on the frontend repo spins up a fresh instance with frontend@<PR branch> + api@main + worker@main. When the PR closes, the instance disappears.

​
When to enable the primary instance

The composer has a “Deploy a primary instance” toggle, off by default. Turn it on when:
  • You want an always-on URL at the convoy’s tracked refs (typical staging).
  • You want auto-redeploy on push to a tracked branch.
Leave it off when:
  • The convoy is purely a PR-preview workflow (“every PR on main should get a preview”). No primary instance means no always-on resources sit around between PRs.

​
Concepts

TermWhat it is
ConvoyDefinition + (optionally) a primary instance. Has a stable slug.
InstancePR-spawned child env. Slug = <convoy>-<repo>-pr<n>. Auto-torn-down on PR close.
ComponentOne repository’s contribution. Has its own slug + tracked ref.
CharterA saved template — the convoy’s component shape + variable/secret keys (never values), ready to instantiate again.
Sibling injectionAt deploy time, every service learns its peers as SL_<COMPONENT>_<SERVICE>_URL/HOST/PORT env vars.
Spawn-time frozenSibling repos inside a PR instance pin the SHA they were spawned at. Pushes to sibling tracked refs don’t disturb live PR previews; use the Refresh action to re-resolve.

​
What’s in the UI

Under /<slug>/environments you’ll find:
  • List — all convoys in the org (instances live under their parent). Status, vessel count, “formation strip”, filterable by status.
  • New convoy — composer: pick repos, choose tracked refs, set variables/secrets, optionally enable a primary instance, hit “Weigh anchor”.
  • Convoy detail — header, primary-instance status + public URLs (if enabled), an Active PR instances rail listing each PR-spawned instance, the convoy formation, tabs for Log / Vessels / Variables / Secrets.
  • Instance detail — same template as convoy detail, but with a parent back-link, the PR # + repo of the spawn trigger, and a Refresh siblings action instead of Clone / Save-as-charter.
  • Charters — saved compositions. Two-click instantiation.