Skip to content
Gisila

Deployments API

Routes under /apps/{appId}/deployments, /apps/{appId}/webhook and /webhooks. See Deployments for the lifecycle.

Deployments

Section titled “Deployments”
Method Path Permission Body Returns
GET /apps/{appId}/deployments/ Viewer {results}, newest first, each with canRollback
POST /apps/{appId}/deployments/ Developer {sourceType, gitCommitSha?, artifactId?, forceRebuild?} The deployment (status: "queued")
POST /apps/{appId}/deployments/artifacts Developer Raw file, Content-Type: application/octet-stream, ≤ 50 MB {artifactId}
POST /apps/{appId}/deployments/{id}/rollback Developer The new rollback deployment (rollback_of_id set)
GET /apps/{appId}/deployments/{id}/logs Viewer {results}: {id, deployment_id, line, stream, created_at}. stream is stdout, stderr or system.

Trigger body

Section titled “Trigger body”
Field Type Description
sourceType string Required. Must equal the app’s source type (git, binary or zip).
gitCommitSha string Git apps: deploy this commit instead of the branch head.
artifactId string Binary and ZIP apps: required, from the artifacts route. Refused for git apps.
forceRebuild bool Skip the dependency and build cache. Default false.

Deployment object

Section titled “Deployment object”

id, app_id, triggered_by_id (null for webhook deploys), source_type, git_commit_sha, status (queued, building, deploying, succeeded, failed, rolled_back), failure_reason, is_active, rollback_of_id, release_id, started_at, finished_at, created_at, plus canRollback. The recorded configuration snapshot is never returned.

When to use:

  • Upload, then trigger, for binary and zip apps. An upload must look like its kind (a ZIP archive, or an ELF binary or #! script). The panel keeps the 5 newest uploads per app.
  • Rollback is refused (400) unless the target succeeded, isn’t live, still has its release on disk, and recorded its configuration.
  • For live build output, use /ws/apps/{appId}/build-logs/{id}.

Example

Terminal window
H='Authorization: Bearer gsl_xxxxxxxxxxxxxxxx'
curl -sX POST https://panel.example.com/apps/42/deployments/ -H "$H" \
  -H 'Content-Type: application/json' -d '{"sourceType": "git", "forceRebuild": true}'

Push-to-deploy webhook

Section titled “Push-to-deploy webhook”
Method Path Permission Body Returns
GET /apps/{appId}/webhook Viewer {configured, enabled, path, branch, lastDeliveryAt, lastDeliveryResult}. Never the secret.
POST /apps/{appId}/webhook Admin {path, branch, secret}. Creates the webhook or rotates its secret. The secret is only returned here.
DELETE /apps/{appId}/webhook Admin {detail}. Later deliveries are refused.
PUT /apps/{appId}/webhook/status-token Admin {token} (≤ 500 characters) {detail}. Turns on commit statuses. Stored encrypted, never returned.
DELETE /apps/{appId}/webhook/status-token Admin {detail}. Turns commit statuses off.

Webhook delivery

Section titled “Webhook delivery”
Method Path Permission Body Returns
POST /webhooks/apps/{appId} Public, checked by signature. 120/min, 5 MB. The repository host’s push payload 202 {deploymentId}, 200 {ignored: "<reason>"}, or 401 invalid_signature

Called by GitHub, Gitea, Forgejo (X-Hub-Signature-256 HMAC of the body) or GitLab (X-Gitlab-Token). A push to the app’s branch (or the repository’s default branch when the app has none) queues a deployment of that commit. Pings, other events, tags, other branches, deleted branches, redelivered delivery ids, and pushes while a deployment is still queued are ignored. An unknown app, a removed webhook and a bad signature all return the same 401.

With a status token, each push-triggered deployment is reported on its commit as gisila-panel/deploy (pending, then success or failure). The status URL is taken from the signed push and used only when it’s https on the app’s own git host (or api. plus it). Failed posts are retried up to 5 times. Set PANEL_PUBLIC_URL to link statuses to the app’s page.