Push-to-deploy apps
Register an app and drive one-shot or staged deploys. Duplicate names in a tenant are rejected, never replaced.
POST /api/v1/appsSS-47 · Northflank-class app plane
Push a repo; get a governed, routable app.
What it does
The unit of ownership is an App — {name, repo, branch} inside a tenant. Around it hangs everything that keeps a deploy safe: a resumable deploy saga, secure admission, revisions and rollback, autoscaling, crons, PR previews, a full CI/CD control plane, self-hosted runners, DBaaS/secret addons and a sovereign-exit export.
In-mesh base http://ss-47-skyforge.shared-services.svc.cluster.local:8047 · auth is an SS-01 bearer token + X-Tenant-Id on every /api/v1 route.
Sub-capabilities
Register an app and drive one-shot or staged deploys. Duplicate names in a tenant are rejected, never replaced.
POST /api/v1/appsA durable build → gate → admit → roll → route sequence; each step is persisted and the roll step is exactly-once, so a crash resumes at the failed step (ADR-0005).
POST /api/v1/apps/{app}/deploy/sagaNo revision is minted unless the image is SS-04-admitted: Cosign-signed + SBOM'd + scanned. An unadmitted image halts the saga 403 with the build marked refused.
GET /api/v1/apps/{app}/buildsThe rollout tracks active vs last-good revision; an unhealthy health report compensates back to last-good and emits an SS-08 incident.
POST /api/v1/apps/{app}/rollout/healthA completed route step gives the revision a routable TLS URL; the deploy saga returns it on the route step.
POST /api/v1/apps/{app}/deploy/saga/{id}/advanceRegister linux runners you own and drain on your terms; OS-agnostic builds offload to an online runner or fall back in-cluster (ADR-0070).
POST /api/v1/runnersA per-PR ephemeral deploy with a TTL lease; merge/close tears it down and erases its SS-02 claims, and a sweeper reclaims lapsed leases.
POST /api/v1/apps/{app}/previewsProvision a managed backing resource as an SS-02 DBaaS claim with an SS-05 Vault secret ref. Catalog-gated — embedded datastores are refused.
POST /api/v1/apps/{app}/addonsA min/max/target policy against cpu/memory/http_rate, applied behind a tenant replica-quota ledger so concurrent scale-ups can't both overrun.
PUT /api/v1/apps/{app}/scaleWorked example
The governed happy path, driven over the API. Auth is an SS-01 bearer token plus X-Tenant-Id on every route.
/api/v1/apps{name, repo, branch}. Duplicate names 409.
/api/v1/apps/{app}/gitPick a provider from GET /providers; auto-deploy starts disabled.
/api/v1/apps/{app}/deploy/sagaRecords desired state at current_step: build.
/api/v1/apps/{app}/deploy/saga/{id}/advanceBuild runs; the SS-32 gate verdict is evaluated.
/api/v1/apps/{app}/deploy/saga/{id}/advanceSS-04 admission: signed + SBOM + scanned, or the saga halts 403.
/api/v1/apps/{app}/deploy/saga/{id}/advance?run=all mints the revision, re-points the rollout and returns the TLS url.
/api/v1/apps/{app}/rollout/healthHealthy promotes to last_good_revision; unhealthy auto-rolls-back.
Endpoint catalog
Real method + path from services/skyforge/openapi.json. The full contract, including ops endpoints, is the 61-operation surface.
/api/v1/appsList the tenant's apps (cross-tenant rows never returned)/api/v1/appsRegister a new app within the tenant/api/v1/apps/{app}Fetch one app's definition/api/v1/apps/{app}/exportSovereign-exit: portable desired state (ADR-0055)/api/v1/apps/{app}/deployidempotentOne-shot deploy: build → gate → admit → roll → route/api/v1/apps/{app}/deploy/sagaidempotentStart the resumable staged deploy saga/api/v1/apps/{app}/deploy/saga/{id}/advanceApply one step, or ?run=all to a terminal state/api/v1/apps/{app}/deploy/saga/{id}Fetch one saga's persisted state/api/v1/apps/{app}/deploy/sagasList every deploy saga for the app/api/v1/apps/{app}/buildsList build records with gate verdict + admission status/api/v1/apps/{app}/revisionsList immutable, monotonically numbered revisions/api/v1/apps/{app}/rolloutActive / last-good revision, status and history/api/v1/apps/{app}/rollout/healthReport health; unhealthy auto-rolls-back to last-good/api/v1/apps/{app}/rollbackRe-point to an existing revision (no new build)/api/v1/incidentsThe tenant's auto-rollback incidents (SS-08 feed)/api/v1/apps/{app}/scaleInstall a scaling policy (clamped, quota-reserved)/api/v1/apps/{app}/scalePolicy, applied replicas and event history/api/v1/apps/{app}/scale/observeFeed an SS-06 metrics tick; apply behind quota/api/v1/quotaSet the tenant's total replica quota/api/v1/quotaReport quota and current ledger usage/api/v1/providerspublicThe ten-provider git catalog + signature schemes/api/v1/apps/{app}/gitConnect a repository to an app/api/v1/apps/{app}/gitRead the repo connection + auto-deploy policy/api/v1/apps/{app}/detectidempotentDetect deployable app types from the repo tree/api/v1/apps/{app}/deployablesRead stored deployable-detection results/api/v1/apps/{app}/autodeploySet continuous-deployment policy (branch glob, gates)/api/v1/webhooks/{provider}Inbound git-webhook listener (signature verified first)/api/v1/apps/{app}/cicd/runRun the pipeline manually (recorded whatever the outcome)/api/v1/apps/{app}/cicd/runsList pipeline runs, newest first/api/v1/apps/{app}/cicd/runs/{id}One run's full stage trace/api/v1/apps/{app}/cicd/flakyFlaky-test detection over run history/api/v1/apps/{app}/gatesReplace the app's quality-gate rules/api/v1/apps/{app}/gatesRead gate rules + most recent evaluation/api/v1/cicd/doraThe four DORA keys from the rollout spine/api/v1/cicd/insightsPer-stage duration analytics + top-failing stage/api/v1/cicd/alertsRegister a pipeline alert rule/api/v1/cicd/alertsList alert rules + fired alerts/api/v1/runnersList registered linux build runners/api/v1/runnersRegister a self-hosted linux runner/api/v1/runners/{id}/heartbeatLiveness heartbeat from the runner agent/api/v1/runners/{id}/onlineMark a runner online / available for offload/api/v1/apps/{app}/previewsCreate/renew a per-PR preview with a TTL lease/api/v1/apps/{app}/previewsList an app's previews (lapsed reads as expired)/api/v1/apps/{app}/previews/{pr}/closeTear down on merge/close, erase SS-02 claims/api/v1/previews/sweepSweeper: reclaim every lease-expired preview/api/v1/apps/{app}/addonsProvision an SS-02 claim + SS-05 secret ref/api/v1/apps/{app}/addonsList bound + erased addons (erasure retained)/api/v1/apps/{app}/addons/{name}Erase the addon's claim, record the erasure/api/v1/apps/{app}/cronsDefine a recurring job (SS-21 schedule)/api/v1/apps/{app}/cronsList crons with applied effect counts/api/v1/apps/{app}/crons/{name}/fireRecord a slot delivery (exactly-once effect)/api/v1/apps/{app}/crons/{name}/firesFire records incl. deduped redeliveries/api/v1/apps/{app}/gpugatedRequest a GPU workload (feature-gated, ADR-0060)/api/v1/apps/{app}/gpuList GPU workload requests/api/v1/apps/{app}/pipelineDefine ordered promotion stages/api/v1/apps/{app}/pipelineRead stages + revision promoted into each/api/v1/apps/{app}/pipeline/promotePromote a revision; gated stages park pending/api/v1/apps/{app}/pipeline/promotionsPromotion history incl. refusals (evidence)/api/v1/apps/{app}/pipeline/promotions/{id}/approveHuman approval; an agent is refused 403 (OPS09)Architecture placement
PaaS app plane does not reimplement the platform — it composes it. These are the services it leans on and the seams between them.
OIDC bearer token gates every /api/v1 route; tenant binding comes from the token.
Executes the hermetic build behind the saga's build step; the Tekton rail runners schedule onto.
Cosign signature + SBOM + scan admission at the admit step.
Independent quality-gate verdict evaluated at the gate step.
Addons are DBaaS claims with Vault secret refs; SkyForge never holds credentials.
Metrics ticks drive autoscale; auto-rollbacks emit incidents.
vCPU-hr / GB-hr / egress metered per second, rolled into billing.