<!-- Stacklift documentation: "CI/CD". Source: https://stacklift.joynul.com/docs/ci-cd · All pages for LLMs: https://stacklift.joynul.com/llms-full.txt -->

> About Stacklift: Stacklift is a hosted platform with source-available SDKs for shipping app releases and over-the-air updates. It works for mobile (React Native, Expo, Flutter, native iOS and Android, Kotlin Multiplatform, .NET MAUI, Unity), web, desktop (Electron, .NET, Java) and backend apps. Developers create releases with the `stacklift` CLI or the dashboard; the server verifies and signs every artifact (SHA-256 + Ed25519), deploys releases to channels with staged rollouts and rollback, and app SDKs check, download and verify updates. Native apps can change screens over the air with server-driven UI layouts and logic with sandboxed scripts, within App Store and Google Play rules. Apps never depend on Stacklift to keep working: everything has a built-in fallback and an exit path.
>
> This page: GitHub Actions, GitLab CI, Jenkins and Docker.

# CI/CD

CI authenticates with a **project secret key** (`slk_…`). It is confined to one project and to the scopes you give it (`releases:read`, `releases:write`, `artifacts:write`, `deployments:write`, `channels:read`). It cannot manage members, keys, rollouts or rollbacks.

Create one under **API Keys**, store it as a CI secret named `STACKLIFT_TOKEN`, and set `STACKLIFT_API_URL`.

> First-party GitHub Action / GitLab component are **planned**. Today every CI system runs the CLI.

## GitHub Actions

```yaml
name: release
on:
  push:
    tags: ['v*']
jobs:
  stacklift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci && npm run bundle
      - run: npm install -g stacklift
      - run: stacklift release create --version "${GITHUB_REF_NAME#v}" --resume --channel staging
        env:
          STACKLIFT_TOKEN: ${{ secrets.STACKLIFT_TOKEN }}
          STACKLIFT_API_URL: ${{ vars.STACKLIFT_API_URL }}
```

`--resume` makes reruns safe. Deployments carry an idempotency key, so retrying a job never deploys twice.

## GitLab CI

```yaml
stacklift:
  image: node:22
  rules: [{ if: '$CI_COMMIT_TAG' }]
  script:
    - npm ci && npm run bundle
    - npm install -g stacklift
    - stacklift release create --version "${CI_COMMIT_TAG#v}" --resume --channel staging
```

## Jenkins

```groovy
withCredentials([string(credentialsId: 'stacklift-token', variable: 'STACKLIFT_TOKEN')]) {
  sh 'stacklift release create --version $VERSION --resume --channel staging'
}
```

## Docker

```bash
docker run --rm -e STACKLIFT_TOKEN -e STACKLIFT_API_URL -v "$PWD:/app" -w /app node:22 \
  sh -c "npm i -g stacklift && stacklift release create --version 1.4.0 --resume"
```

For backend stacks use the `container-image-ref` artifact kind to record an image digest. Stacklift tracks the reference; it doesn't run your containers.

## Branch / tag triggers

Automatic releases from GitHub, GitLab or Bitbucket pushes are **planned** (they need a GitHub App / OAuth app and webhook ingestion). Trigger the CLI from your own pipeline in the meantime.

## Desktop installers

Build, sign and (on macOS) notarize the installers in CI first; Stacklift's own signature is separate from OS code signing. Then upload one installer per OS, ideally from the matching runner, into the same release:

```bash
stacklift release create --version "$VERSION" --runtime-version 3.0.0 \
  --artifact windows:desktop-installer:dist/App-Setup.msi \
  --artifact macos:desktop-installer:dist/App.dmg \
  --artifact linux:desktop-installer:dist/App.AppImage \
  --channel staging
```

A release can only be deployed once **all** the platforms it declares have verified artifacts. Rollbacks of installers are refused; ship a fixed higher version instead. See [Desktop apps](https://stacklift.joynul.com/docs/desktop.md).
