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.

When a GitHub event arrives for a repo that’s part of a convoy, slipway reacts in two parallel ways:
  1. Standalone deployment — if the repo is slipway_enabled on its own, a regular deployment happens as usual. Unaffected by convoys.
  2. Convoy reaction — described on this page. Spawns or updates the convoy instances that reference this repo.
Both happen independently. A push can produce a standalone deployment and a convoy component deployment at the same time, and they don’t depend on each other.

​
Pull request events

When a PR opens, syncs, or closes, slipway routes it based on the action:
ActionWhat slipway does
Opened / reopened / marked ready for reviewFor every convoy with a component tracking the PR’s base branch in this repo, spawn a new convoy instance. Clone all components, variables, and secrets from the convoy. The matching component’s ref is overridden to the PR’s HEAD branch; the others stay frozen at the convoy’s tracked refs as of spawn time. Deploy.
Synchronized (new commits on the PR)Find the existing instance for this PR. Redeploy just the triggering component at the new HEAD. Siblings are untouched.
Closed (merged or not)Find the instance and tear it down. URLs go away, history stays in the deployments list.
If GitHub redelivers the same opened event, slipway notices the instance already exists and doesn’t create a duplicate.

​
Why “base branch”, not “head branch”?

Convoys track refs like main (the trunk). A PR is a request to merge into a tracked ref. Matching on the PR’s base branch (where it’s targeted) is what makes “PR against main” trigger the convoy that tracks main.

​
Two PRs on the same repo

Each PR gets its own convoy instance. PR #42 and PR #99 on the same repo, both targeting main, produce two separate instances with independent URLs and independent lifecycles. Closing PR #42 doesn’t affect PR #99.

​
Push events

Pushes to a tracked ref redeploy the matching component only in the convoy’s primary instance, if one is enabled. PR-spawned instances are frozen at spawn time on every component except the one whose PR it is — sibling pushes never disturb them. If the convoy has no primary instance enabled, push events are a no-op for the convoy. The convoy waits for PR events.

​
The component-level “Auto redeploy” toggle

When off, this toggle suppresses push-driven redeploys for that component in the convoy’s primary instance. PR instances ignore the flag entirely — a PR sync always redeploys the triggering component, since that’s the whole point of a PR preview.

​
When a spawn fails

If a convoy reaction can’t complete — for example, the convoy has no components yet, or GitHub denies the clone — slipway rolls back the partial instance so nothing leaks. Failures in one convoy don’t affect any other convoy reacting to the same event. The convoy’s deployments list shows the failure with the reason inline.