Deploy with GitHub Actions

GitHub Actions is GitHub’s built-in automation system: it runs jobs in response to repository events, such as a push to your main branch. This page shows a complete, working setup that builds your app and deploys it to Comwit Cloud automatically every time you push.

The deploy itself is done by the comwit CLI, the same command-line tool you would run on your own machine. The only difference in CI is that you authenticate with a token stored as a repository secret instead of logging in through a browser.

What you’ll set up

The flow has three pieces:

1. A cwt_ personal access token with the app:deploy scope, created in the console.
2. That token stored as a GitHub repository secret, plus your project and app ids stored as repository variables.
3. A workflow file (.github/workflows/deploy.yml) that builds the app, installs the CLI, authenticates, and runs comwit deploy.

Note

This page assumes you already have a runtime app. If you don’t, create one first with comwit apps create --project <project-id> --name web (see Deploy an app). A “runtime app” is a deployable Next/V8 isolate application powered by Comwit Cloud’s runtime.

Step 1 — Create a deploy token

In CI you can’t open a browser to log in, so you need a token that is created once and stored. Comwit Cloud uses cwt_ personal access tokens: scoped credentials tied to your user that can only do what their scopes allow and only touch projects you’re a member of.

1. Open the console at https://cloud.comwit.io and go to API tokens at /tokens.

2. Create a token and give it the app:deploy scope. That scope grants exactly what a deploy needs:

   Scope	Grants
   app:deploy	Deploy builds, roll back

3. Copy the token value. The plaintext is shown once at creation — if you lose it, revoke it and create a new one.

Tip

Scope the token as narrowly as the job needs. app:deploy is enough to ship a build. If the same workflow also needs to create apps or set environment variables, you’d additionally need app:write — but for a pure deploy job, keep it to app:deploy. You can revoke any token from the same /tokens page.

Caution

Use a cwt_ user token only. Never put PLATFORM_API_SERVER_TOKEN (the internal operator/web token) into a workflow — it bypasses scope and membership checks and is not a user credential.

Step 2 — Store the token and ids in GitHub

GitHub separates secrets (encrypted, never printed in logs) from variables (plain config values). Put the token in a secret and the ids in variables.

In your repository, go to Settings → Secrets and variables → Actions, then:

• Under Secrets, add COMWIT_TOKEN with your cwt_... value.
• Under Variables, add COMWIT_PROJECT (your project id) and COMWIT_APP (your app id).

These names map straight onto how the workflow references them: ${{ secrets.COMWIT_TOKEN }}, ${{ vars.COMWIT_PROJECT }}, and ${{ vars.COMWIT_APP }}.

Note

The project id is also accepted via the COMWIT_PROJECT environment variable by the CLI itself, which is why the workflow below sets it once at the job level. Authentication, however, is always done with comwit login --token (or the saved config file) — there is no separate “API key” environment variable.

Step 3 — Install the CLI in CI

The workflow needs the comwit binary on the runner. The repository ships an install script, scripts/install-comwit.sh, that you can use locally; it works like this:

• It first tries to download a GitHub release asset named like comwit_<os>_<arch>.tar.gz.

• It supports a few environment overrides:

  install-comwit.sh environment overrides

  COMWIT_VERSION=v0.1.0 scripts/install-comwit.sh
  COMWIT_INSTALL_DIR=/usr/local/bin scripts/install-comwit.sh
  COMWIT_INSTALL_REPO=comwit/comwit-cloud scripts/install-comwit.sh

• COMWIT_VERSION pins the release tag, COMWIT_INSTALL_DIR chooses where the binary lands, and COMWIT_INSTALL_REPO chooses which GitHub repo to pull the release from.

Caution

Released binaries are not published yet. Until release assets exist, the installer falls back to building the CLI from source out of a checkout and installing it to ~/.local/bin/comwit. The workflow below reflects that: it checks out the comwit-cloud repo and builds the CLI, which works today. Once comwit_<os>_<arch>.tar.gz release assets are published, you can replace the build step with a download of that asset (or run scripts/install-comwit.sh with COMWIT_VERSION/COMWIT_INSTALL_REPO) and drop the source checkout.

Step 4 — Add the workflow file

Create the file below at .github/workflows/deploy.yml in your application repository. It runs on every push to main, builds your app into ./dist, installs the CLI, authenticates with your token, and deploys.

.github/workflows/deploy.yml

name: Deploy to Comwit Cloud

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    # Project id is read by the CLI from COMWIT_PROJECT when --project is omitted;
    # we pass it explicitly below as well.
    env:
      COMWIT_PROJECT: ${{ vars.COMWIT_PROJECT }}

    steps:
      # 1. Check out YOUR application source.
      - name: Check out app
        uses: actions/checkout@v4

      # 2. Build your application into ./dist.
      #    Replace this with your real build. The output can be a built
      #    directory (the CLI packs it with `tar --zstd`) or a prebuilt
      #    `.tar.zst` package file.
      - name: Build app
        run: |
          npm ci
          npm run build
          # Ensure your build output ends up in ./dist

      # 3. Install the comwit CLI.
      #    Release binaries are not published yet, so build from source.
      #    (Replace this step with a release-asset download once
      #    comwit_<os>_<arch>.tar.gz assets exist.)
      - name: Install comwit CLI
        run: |
          git clone --depth 1 https://github.com/comwit/comwit-cloud.git /tmp/comwit-cloud
          (cd /tmp/comwit-cloud && just cli-build)
          mkdir -p "$HOME/.local/bin"
          cp /tmp/comwit-cloud/dist/comwit "$HOME/.local/bin/comwit"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      # 4. Authenticate with your cwt_ deploy token.
      #    `comwit login --token` stores the token in the CLI config file
      #    so later commands are authenticated.
      - name: Authenticate
        run: |
          comwit login \
            --token ${{ secrets.COMWIT_TOKEN }} \
            --project ${{ vars.COMWIT_PROJECT }}

      # 5. Deploy the build.
      - name: Deploy
        run: |
          comwit deploy \
            --project ${{ vars.COMWIT_PROJECT }} \
            --app ${{ vars.COMWIT_APP }} \
            --package ./dist

What each command does

• comwit login --token <cwt_...> --project <project-id> stores your cwt_ token (and a default project) in the CLI config file, ~/.config/comwit/config.json. After this, the CLI is authenticated for the rest of the job.
• comwit deploy --project <project-id> --app <app-id> --package ./dist uploads your build and activates it. --package may be a built directory — which the CLI packs into a temporary .tar.zst using local tar --zstd — or an already-prebuilt .tar.zst file.

Note

If your CI runner’s tar does not support zstd, pass a prebuilt .tar.zst package file to --package instead of a directory.

Optional deploy flags

comwit deploy accepts a few extra flags you can add to the deploy step:

Deploy step with optional flags

- name: Deploy
  run: |
    comwit deploy \
      --project ${{ vars.COMWIT_PROJECT }} \
      --app ${{ vars.COMWIT_APP }} \
      --package ./dist \
      --host app.example.com \
      --env-ref brrrd/env/app \
      --max-concurrent-requests 100

• --host binds one or more hostnames on deploy (comma-separated, e.g. a.example.com,b.example.com). See Custom hostnames.
• --env-ref selects a runtime environment reference.
• --max-concurrent-requests sets the runtime concurrency cap.

How authentication works in CI

It’s worth being precise about what the token can and can’t do, because that’s what keeps the setup safe:

• The cwt_ token authenticates every API call the CLI makes via Authorization: Bearer <token>.
• It can only perform actions its scopes allow and can only touch projects you’re a member of. A deploy with an out-of-scope token or a project you’re not a member of returns HTTP 403.
• The token is the only secret in the workflow. Keep it in secrets.COMWIT_TOKEN, never in a variable, log line, or committed file.

For the full token and scope model, see API authentication. For other CI systems, see Other CI providers.