First Delivery
This tutorial defines the first delivery path at the control-plane boundary. It is intentionally conservative: the API can record applications, release bundles, workflow runs, and execution tasks, while real build/deploy execution still depends on configured runners and providers.
Prerequisites
- A running Soha control plane from First Deploy.
- A registered cluster from First Cluster when the deploy target is Kubernetes.
- An access token with delivery permissions.
- A configured runner/provider if you expect the execution task to move beyond queued or disabled status.
Create An Application
Create the application record first:
export SOHA_SERVER=http://localhost:8080
export SOHA_TOKEN=replace-with-access-token
curl -sS -X POST "$SOHA_SERVER/api/v1/applications" \
-H "Authorization: Bearer $SOHA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "billing-api",
"ownerTeam": "platform",
"repositoryUrl": "https://git.example.com/platform/billing-api"
}'The API reference name is POST /api/v1/applications. In the console, use Application Delivery → Applications → Create / Onboard Application. Add later services only from the application’s Services tab.
Bind An Environment
Open the application detail Environments tab and bind one item from Platform Configuration → Environment Directory. The directory is reusable platform inventory; the application binding owns this application’s targets and release policy.
Keep the returned application-environment binding ID for the delivery plan below.
Build and update in the console
Open Build and update on an application service and choose build-and-deploy, build-only, existing-artifact deployment, or configuration-only update. Saving service configuration does not execute; running creates a batch. For repeated or cross-service delivery, save targets and order in Workflow center → Workflows, then run the definition separately.
After the build produces a verified image digest, inspect the final deployment plan, environment, rendered resources, and approval. The server resumes the batch after approval; do not separately confirm batch-owned plans. Deployment and configuration updates also require authorization, preflight, and approval. The API example below is for a standalone DeliveryPlan.
Create And Confirm A Delivery Plan
DeliveryPlan is the canonical user-visible delivery intent for build, deploy, workflow, verification, and rollback actions.
curl -sS -X POST "$SOHA_SERVER/api/v1/delivery/plans" \
-H "Authorization: Bearer $SOHA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"applicationId": "app-1",
"applicationEnvironmentId": "binding-1",
"action": "build_deploy",
"source": "manual",
"refType": "branch",
"refName": "main"
}'
curl -sS -X POST "$SOHA_SERVER/api/v1/delivery/plans/plan-1/confirm" \
-H "Authorization: Bearer $SOHA_TOKEN"The API reference names are POST /api/v1/delivery/plans and POST /api/v1/delivery/plans/{planID}/confirm. The older build, workflow, and release trigger endpoints remain compatibility APIs, not additional console write paths.
Trigger Through AI Gateway
When AI Gateway is enabled for delivery, the controlled action tool is delivery.actions.trigger. It still re-enters the delivery application service and may return pending_approval, pending_human_confirm, dry_run, disabled, or queued execution state.
soha tool call delivery.actions.trigger \
--profile gateway-admin \
--input-json '{"applicationId":"app-1","applicationEnvironmentId":"binding-1","action":"build_deploy"}'Inspect Execution Tasks
curl -sS "$SOHA_SERVER/api/v1/delivery/execution-tasks?applicationId=app-1&limit=20" \
-H "Authorization: Bearer $SOHA_TOKEN"The API reference name is GET /api/v1/delivery/execution-tasks.
Expected Output Shape
The runner/provider state may be disabled, queued, or pending approval in a fresh environment. The durable API response should still include application and task identity:
Fixture artifact: first-delivery.expected.txt
POST "$SOHA_SERVER/api/v1/applications"
POST "$SOHA_SERVER/api/v1/delivery/plans"
POST "$SOHA_SERVER/api/v1/delivery/plans/plan-1/confirm"
GET "$SOHA_SERVER/api/v1/delivery/execution-tasks?applicationId=app-1&limit=20"{"item": {"id": "app-1", "name": "billing-api", "ownerTeam": "platform"}}
{"item": {"id": "plan-1", "applicationId": "app-1", "applicationEnvironmentId": "binding-1", "status": "draft"}}
{"item": {"plan": {"id": "plan-1", "status": "confirmed"}, "result": {"executionTaskId": "task-1", "status": "queued"}}}
{"items": [{"id": "task-1", "taskKind": "build", "status": "queued"}]}Import a reusable definition
Save this as node-image.soha.yaml. It only defines build commands; actual delivery still needs service, build environment, and artifact configuration:
apiVersion: delivery.soha.io/v1alpha1
kind: BuildTemplate
metadata:
name: node-image
spec:
buildCommands:
- npm ci
- npm run buildValidate offline, then preview using an authenticated local profile:
soha delivery documents validate --file node-image.soha.yaml
soha delivery documents preview --profile local --file node-image.soha.yamlReview file diagnostics and changes. Use data.id and data.candidateDigest from this response, with one stable idempotency key for this import:
soha delivery documents import --profile local \
--preview-id PREVIEW_ID --candidate-digest CANDIDATE_DIGEST \
--idempotency-key IMPORT_KEYImport only creates a draft. Review and publish it in Templates before explicitly binding its returned ID and published version. Export a published version for inspection or migration; the output file must not already exist:
soha delivery documents export BuildTemplate TEMPLATE_ID \
--profile local --version 1 --format yaml --out exported.soha.yamlTo update an existing draft, use preview --input request.json and pair targetId with the current expectedRevision on its files entry; never rely on name-based overwrite. Template pages also offer YAML/JSON editing, import previews, and exports.
In Git sources on a template page, select a registered repository, ref, and directory. Save, synchronize, review the fixed commit and changes, then apply that SyncRun. The CLI provides the same flow through soha delivery template-sources create|sync|run|apply, with get|runs|objects for inspection. Publishing, adopting a service version, and running a workflow remain separate steps. See Application Delivery for triggers, removed files, and supported limits.
Exit Criteria
- The application record is visible from the application list or detail API.
- Delivery-plan confirmation returns a durable record, a queued execution task, or a clear disabled/unsupported state.
- Execution task state can be inspected without reading runner-local files.
Known Gaps
This tutorial does not claim the delivery runner is fully production-ready. The route to a completed build/deploy requires configured providers, runner claim/callback, artifact metadata, and cluster target credentials.