Skip to main content

CI/CD

Sprintsail integrates with CI/CD systems to automate deployments. The most common approach is GitHub Actions, but any system that can run the ss CLI works.

API tokens​

Create a deploy token for CI use. Tokens are scoped to an organization and can be restricted to specific apps.

ss tokens create --name github-deploy --scope deploy --apps my-app,my-worker
Token created: ss_tok_abc123...
Store this token securely — it will not be shown again.

Add the token as a secret in your CI system (e.g., GitHub repository secrets as SPRINTSAIL_TOKEN).

GitHub Actions​

Basic deploy workflow​

# .github/workflows/deploy.yml
name: Deploy to Sprintsail

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Sprintsail CLI
        run: npm install -g @sprintsail/cli

      - name: Deploy
        env:
          SPRINTSAIL_TOKEN: ${{ secrets.SPRINTSAIL_TOKEN }}
        run: |
          ss push --org my-org --app my-app

Deploy with tests​

name: Test and Deploy

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Sprintsail CLI
        run: npm install -g @sprintsail/cli

      - name: Deploy
        env:
          SPRINTSAIL_TOKEN: ${{ secrets.SPRINTSAIL_TOKEN }}
        run: ss push --org my-org --app my-app

Staging and production​

name: Deploy Pipeline

on:
  push:
    branches: [main, develop]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Sprintsail CLI
        run: npm install -g @sprintsail/cli

      - name: Deploy to staging
        if: github.ref == 'refs/heads/develop'
        env:
          SPRINTSAIL_TOKEN: ${{ secrets.SPRINTSAIL_TOKEN }}
        run: ss push --org my-org --app my-app-staging

      - name: Deploy to production
        if: github.ref == 'refs/heads/main'
        env:
          SPRINTSAIL_TOKEN: ${{ secrets.SPRINTSAIL_TOKEN }}
        run: ss push --org my-org --app my-app

Deploy pre-built image​

If your CI already builds a Docker image, push the image reference:

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build and push to GHCR
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/my-org/my-app:${{ github.sha }}

      - name: Install Sprintsail CLI
        run: npm install -g @sprintsail/cli

      - name: Deploy image
        env:
          SPRINTSAIL_TOKEN: ${{ secrets.SPRINTSAIL_TOKEN }}
        run: |
          ss push --org my-org --app my-app \
            --image ghcr.io/my-org/my-app:${{ github.sha }}

Webhook-based deploys​

Configure a deploy webhook for lightweight integrations:

ss webhooks create my-app --event push --branch main
Webhook URL: https://api.sprintsail.com/hooks/wh_abc123
Secret: whsec_xyz789

Point your Git provider's webhook settings to this URL. When a push to the configured branch is received, Sprintsail pulls the source and runs a standard ss push build.

Webhook security​

Webhooks are verified using HMAC-SHA256 signatures. The X-sprintsail-Signature header contains the signature. Verify it in custom integrations:

ss webhooks list my-app
ss webhooks delete my-app --webhook wh_abc123
ss webhooks rotate-secret my-app --webhook wh_abc123

GitLab CI​

# .gitlab-ci.yml
deploy:
  stage: deploy
  image: node:20
  only:
    - main
  script:
    - npm install -g @sprintsail/cli
    - ss push --org my-org --app my-app
  variables:
    SPRINTSAIL_TOKEN: $SPRINTSAIL_TOKEN

Token management​

List tokens​

ss tokens list
NAME             SCOPE    APPS          CREATED           LAST USED
github-deploy    deploy   my-app        2026-04-01        2 hours ago
gitlab-ci        deploy   *             2026-03-15        1 day ago

Revoke a token​

ss tokens revoke github-deploy

Token best practices​

  • Use one token per CI pipeline, scoped to only the apps it deploys.
  • Rotate tokens every 90 days.
  • Never commit tokens to source control. Use CI secrets.
  • Revoke tokens immediately when team members leave.

Deploy status​

Check deployment status from CI:

ss deploy status my-app --wait

The --wait flag blocks until the deploy completes or fails, returning a non-zero exit code on failure. This is useful for CI pipelines that need to gate subsequent steps.

Next steps​