Build

View as Markdown

Build turns a local source directory into an immutable container artifact. It snapshots your source, runs the build, and stores the resulting Open Container Initiative (OCI) image in Container Registry.

Why use Build?

Running software starts with packaging its source and dependencies into something a runtime can execute. Build handles that step and gives you a recorded result that downstream tools can identify by its digest.

What you can do

Submit a snapshot of the current directory with the CLI.
Inspect build status, follow logs, and cancel an unfinished build.
List previous Builds and inspect their resulting Artifacts.
Pass the published image to Run or another compatible OCI consumer.

Core concepts

A Build records the source, execution status, logs, and result. An Artifact identifies the immutable OCI output. Its digest identifies the image content, so a deployment can refer to an exact result.

Build packages software. Runtime configuration, Secret bindings, and hostnames are configured separately in Run. This keeps application credentials out of the build output.

Build and deploy an existing web app

This example updates an existing Run service from a Bun web application. It does not create a Project or Workload.

Before you start:

Install the Socra CLI with the Account, Build and Run plugins, then sign in to the Account that owns the Project. Follow Project setup if you still need an authorized Project with Build, Run and Container Registry enabled.
Use a configured service Workload that you can deploy to. Its runtime settings, port and Secret references must match the application. The Build identity needs access to any private dependencies.
For the bun-web profile below, bun run build must produce .output/server/index.mjs and its required files. The resulting image runs that server with Bun and PORT=3000. A source tree that needs a different build or runtime must use a compatible profile. Verify dependency installation and the build locally before starting a Cloud Build.
Check Cloud pricing and funding before starting. Build and runtime usage have separate costs. Review the source directory and keep credentials out of source; configure runtime Secrets in Run.

From the repository root, replace PROJECT_ID with your Project's proj_… ID and WORKLOAD_NAME with the existing Workload name:

socra build create --project PROJECT_ID --profile bun-web --root . --name WORKLOAD_NAME

This snapshots the current directory and waits. Continue only when the returned status is succeeded and artifact contains an art_… ID. Retrieve that Artifact:

socra build artifact get ARTIFACT_ID

Check its Project and name. Copy the complete image value, including @sha256:…, into IMAGE_DIGEST:

socra run deploy WORKLOAD_NAME --project PROJECT_ID --image IMAGE_DIGEST

A successful response includes status: succeeded, a Deployment ID and a Revision ID. Save those IDs. Inspect the deployment and its runtime health, then open the service URL and check the application behavior you changed:

socra run deployment get DEPLOYMENT_ID
socra run status DEPLOYMENT_ID

Deployment success and a working application are separate checks. If health is unknown or stale, inspect logs and events rather than treating that reading as application verification.

If the attempt fails

For a Build failure, keep its ID and inspect socra build get BUILD_ID and socra build logs BUILD_ID; a failed Build supplies no successful artifact to deploy. For a deployment failure or interrupted terminal, inspect the existing attempt before retrying. Use socra run logs DEPLOYMENT_ID and socra run events DEPLOYMENT_ID to investigate. The Run CLI reference covers returning to a known successful Revision; rollback does not undo application data changes.

Use Build

Read the CLI reference for other profiles and command options or the API reference for resources, request fields, and responses.