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.

Slipway supports both GitHub and GitLab. Each slipway organization is anchored on exactly one upstream — a GitHub installation or a GitLab group. If you have repos on both, link them separately; you’ll end up with one slipway org per provider account.
Only gitlab.com is supported today. Self-hosted GitLab instances are on the roadmap but ship behind a dedicated security workstream.

​
Operator setup

To enable the GitLab sign-in surface, the slipway operator registers an OAuth application on gitlab.com and supplies the credentials to slipway-master.
  1. Sign in to gitlab.com and go to User Settings → Applications.
  2. Create a new application with:
    • Name: slipway (anything you’ll recognize)
    • Redirect URI: https://<your-slipway-host>/api/auth/gitlab/callback
    • Scopes: api, read_user, read_repository
    • Confidential: checked
  3. Copy the Application ID and Secret into slipway-master’s environment: 
    SL_GITLAB_OAUTH_CLIENT_ID=<application id>
SL_GITLAB_OAUTH_CLIENT_SECRET=<application secret>
  4. Restart slipway-master. The login page will now show Continue with GitLab alongside GitHub.
If either env var is empty the GitLab affordance is hidden from the UI and /api/auth/gitlab/start returns 400.

​
Connecting a group

Once OAuth is configured, end users connect a GitLab group as follows:
  1. From the login page (or the sidebar “Add an organization” button), click Continue with GitLab.
  2. Authorize the slipway application in gitlab.com.
  3. Slipway redirects to /gitlab/setup and lists every group where you have at least Maintainer (access level 40).
  4. Pick a group. Slipway:
    • Mints a group access token named slipway with api, read_repository, and write_repository scopes, valid for 365 days.
    • Registers a group webhook on /webhooks/gitlab subscribed to Push, Merge Request, and Subgroup events. A unique random token is stored on the installation row and used to authenticate every incoming webhook.
    • Creates a new slipway organization tagged as a GitLab provider org.
    • Ingests every project under the group (including subgroups), excluding archived projects.
After connect you land on /{slug}/repos with the projects ready to enable.
You must be Maintainer or higher on the group. Slipway can’t mint a group access token from a Developer or Reporter role; the connect step will fail with that error message and a hint to ask a group owner to invite you as Maintainer.

​
Deployment surface

Once a project is enabled in slipway, GitLab-backed repos work the same way GitHub-backed repos do:
  • Push to the default branch — triggers a deploy via the group webhook.
  • Open / update / close a Merge Request — slipway treats MRs like GitHub PRs:
    • On open and reopen: spins up a preview environment (the project must have slipway.yaml).
    • On update (synchronize): redeploys the existing preview at the new HEAD SHA.
    • On close (whether merged or not): tears the preview down.
  • Commit statuses — slipway posts a commit status to the MR’s head SHA. GitLab upserts statuses by (sha, name); slipway re-posts on each deployment phase change (running → success/failed).
  • MR notes — on terminal states (live, failed, torn down, rebuilding) slipway posts (and edits in place) a comment on the MR with the preview URLs.

​
Webhooks and tokens

ConcernGitHubGitLab
Webhook secret scopeone app-wide secretone per installation (per group)
Webhook auth headerX-Hub-Signature-256 (HMAC)X-Gitlab-Token (bearer compare)
Repo tokeninstallation access token (1 hour)group access token (365 days)
Token rotationautomatic via App JWTscheduled (daily rotator, refreshes tokens within 14 days of expiry)
GitLab’s per-installation webhook secret means a leaked token compromises one tenant, not all of them — a small win over the app-wide HMAC model.

​
Nested groups

GitLab supports nested groups (e.g. acme/backend/api). Slipway uses last-slash semantics when splitting a project’s full path, so nested groups round-trip without data loss. The connect step’s include_subgroups=true flag ingests every project below the chosen group, however deep the nesting.

​
Differences from GitHub

A handful of small behaviors differ from the GitHub path:
  • No install picker. GitHub’s App install flow shows a “pick a target” screen on github.com; GitLab uses a group picker rendered by slipway at /gitlab/setup. The UX shape matches but the round-trip is different.
  • No App suspension state. GitLab groups can revoke a group access token at any time. Slipway treats the row as connected until an actual API call fails; there’s no equivalent of GitHub’s “suspended” badge.
  • Avatar URL. GitHub avatars come from https://github.com/{login}.png — a stable derived URL. GitLab doesn’t have an equivalent; the slipway sidebar falls back to the signed-in user’s avatar for GitLab orgs.

​
Self-hosted GitLab

Out of scope for v1. Supporting self-hosted instances introduces SSRF surface (slipway making outbound HTTP to a customer-controlled URL), per-tenant OAuth credential storage, and TLS-validation footguns that warrant a dedicated security workstream. The roadmap covers it as v2.