Automate deploys (CI/CD)

CI/CD (“continuous integration / continuous delivery”) means letting a pipeline — GitHub Actions, GitLab CI, a build server, or any script — build and ship your app automatically instead of running deploys by hand from your laptop. On Comwit Cloud this works the same way a manual deploy does: your automation authenticates with a token and calls the platform API at https://api.cloud.comwit.io, either through the comwit CLI or with raw HTTP.

This page covers the pieces that are the same no matter which CI system you use: the token, the build artifact, and the two integration styles. For copy-paste workflows, see GitHub Actions and other CI systems.

Use a scoped cwt_ token

Automation authenticates with a personal access token — a cwt_ token. It is tied to your user, can only act on projects you are a member of, and can only do what its scopes allow. That makes it safe to drop into a pipeline: even if the secret leaked, it can only do the narrow set of things you granted.

For deploy automation you almost always want one of two scopes:

Scope	Grants
app:deploy	Deploy builds, roll back
app:write	Create/delete apps, set env, attach hostnames

If your pipeline only ships new builds of an app that already exists, app:deploy is enough. If the pipeline also creates the app, sets environment variables, or attaches hostnames, add app:write. (app:read lets a pipeline list apps and inspect builds if you need that for a check.) See Authentication for the full scope table.

Never use the operator token

PLATFORM_API_SERVER_TOKEN is an internal operator/web token. It bypasses scope and project-membership checks and must never be used as a CI secret or a user token. User tokens always start with cwt_. If you only have a server token, stop — create a scoped cwt_ token instead.

Create the token

Create a scoped cwt_ token from the console at https://cloud.comwit.io/tokens (“API tokens”). Pick the scopes your pipeline needs and nothing more. The plaintext token is shown once at creation — copy it then. You can revoke it from the same page at any time.

Tip

Use a separate token per pipeline (or per repository) with the minimum scopes it needs. Revoking or rotating one then never disturbs the others.

Store it as a CI secret

Save the cwt_ token as an encrypted secret in your CI provider — never commit it to your repository or print it in build logs. Most providers expose secrets to the build as environment variables; a common convention is COMWIT_TOKEN.

The build artifact

A deploy ships one build artifact: your app’s compiled output. Comwit accepts it in two shapes:

• a directory of build output (a brrrd output directory), or
• a prebuilt .tar.zst package file.

When you point the CLI at a directory, it packs the directory into a temporary .tar.zst for you using local tar --zstd. If your CI image’s tar does not support zstd, build the .tar.zst yourself (or have your build step produce one) and pass that file instead.

Over raw HTTP there is no directory upload: the deployment request body is the raw application/octet-stream .tar.zst artifact.

Two integration styles

A. Run the comwit CLI in CI

The friendliest option when you can install a binary in your pipeline. Authenticate non-interactively with --token (no browser device flow in CI), then deploy.

CI pipeline (comwit CLI)

# Authenticate with the token from your CI secret store.
comwit login --token "$COMWIT_TOKEN" --project "$COMWIT_PROJECT"

# Build artifact is a directory or a prebuilt .tar.zst.
comwit deploy \
  --project "$COMWIT_PROJECT" \
  --app "$COMWIT_APP" \
  --package ./apps/web/dist/brrrd

comwit login --token stores the token in the CLI config instead of running the interactive device flow, so it works headless. You can also pass the project with the COMWIT_PROJECT environment variable instead of --project.

comwit deploy accepts the same optional flags in CI as anywhere else:

comwit deploy (optional flags)

comwit deploy \
  --project "$COMWIT_PROJECT" \
  --app "$COMWIT_APP" \
  --package ./dist/brrrd \
  --host app.example.com \
  --env-ref brrrd/env/app \
  --max-concurrent-requests 100

For installing the binary in a pipeline, see Install the CLI.

B. Call the API over raw HTTP

Use this when installing the CLI is awkward — a minimal container image, a platform where you can only run curl, or tooling in another language. Send the token as a bearer header and POST the .tar.zst artifact as the raw request body. Hosts, env-ref, and concurrency go on the query string (not in the body).

CI pipeline (raw HTTP)

curl -sS -X POST \
  -H "Authorization: Bearer $COMWIT_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./dist/brrrd.tar.zst \
  "https://api.cloud.comwit.io/v1/projects/$COMWIT_PROJECT/apps/$COMWIT_APP/deployments"

The deploy endpoint is:

POST /v1/projects/{projectId}/apps/{appId}/deployments

A request whose token lacks the required scope, or that targets a project you are not a member of, returns 403. For the full status-code list and retry behavior, see Errors and idempotency and the API overview.

Note

Generic Idempotency-Key support for long-running workflows is planned, not yet live. Today the API is synchronous where the upstream control plane is synchronous; design your pipeline so a retried deploy is acceptable.

Next steps

• GitHub Actions — a ready-to-use workflow.
• Other CI systems — GitLab CI, build servers, and raw-HTTP patterns.
• App deploys — what a deploy does and how rollbacks work.
• Authentication — token classes and the full scope table.