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.

This walkthrough creates a convoy with a frontend repo and an API repo, tracking main on each. We’ll leave the primary instance off so the convoy only deploys when a PR opens — the typical preview workflow.

​
Prerequisites

  • The slipway GitHub App installed on your org.
  • Two repos visible through the installation. Each has its own slipway.yaml. Neither needs to be slipway_enabled — that flag controls single-repo deploys; convoys work independently.

​
1. Open the composer

In the sidebar: Convoys → New convoy (/<your-slug>/environments/new).

​
2. Pick vessels

Click + Add vessel. In the searchable popover, pick frontend. Repeat for api. Each vessel defaults to tracking branch:main with the component slug derived from the repo name.

​
3. Name + URL pattern

FieldExample
NameStaging
Slugstaging (DNS-safe, immutable once created)
Leave Deploy a primary instance unchecked for the preview-only workflow. The URL preview switches to show the PR-instance pattern: 
https://staging-<repo>-pr<n>-<component>-<port>.apps.slipway.sh
(If you want an always-on staging URL too, check the toggle. You’ll get both — a stable primary instance at staging-frontend-web.… AND per-PR instances.)

​
4. Set supplies (optional)

Under Variables + secrets, add anything that should override repo/org scopes for this convoy. Secrets are encrypted at rest and never returned after creation.

​
5. Weigh anchor

Hit Weigh anchor. The composer redirects you to the convoy detail page. With the primary instance off, the Active PR instances rail shows “No active PR instances” — that’s expected. The convoy is now armed.

​
6. Open a PR and watch the magic

Open a PR against main on the frontend repo (the PR base branch matters — it has to match a tracked ref). Slipway:
  1. Webhook fires.
  2. Slipway finds your convoy with a component tracking (frontend, branch:main).
  3. Spawns a child instance staging-frontend-pr<n> cloning the convoy’s components, vars, and secrets. The frontend component is rewritten to the PR’s HEAD branch; api stays frozen at the SHA of main at spawn time.
  4. The new instance deploys. Its public URLs go live at https://staging-frontend-pr<n>-<component>-<port>.apps.slipway.sh.
Refresh the convoy detail page — the PR instance is now listed in the Active PR instances rail. Click in to watch it deploy.

​
7. Push to the PR

Pushing new commits to your PR branch triggers a pull_request synchronize webhook. Slipway re-deploys only the frontend component in the existing instance; siblings stay where they were.

​
8. Close the PR

Merging or closing the PR tears the instance down. The namespace and pods disappear; the instance row stays in history.

​
What about pushes to main?

Two cases:
  • Primary instance off (what we set up): pushes to main on frontend redeploy nothing. The convoy is a definition; main pushes don’t trigger anything until they enter a PR.
  • Primary instance on: pushes to main redeploy the matching component in the primary instance only. PR instances are unaffected (spawn-time frozen).
If a PR instance is live and api’s main has moved on, the operator can hit Refresh siblings on the instance detail page — slipway re-resolves every non-triggering component to the parent convoy’s tracked-ref HEAD and redeploys them.