Build

Start a build.

Starts a container image build and returns the build record.

For a private repository, either install the Scalix GitHub App for the project (builds then authenticate themselves) or pass auth_token.

post/v1/build

Request

  • Base URL: https://api.scalix.world
  • URL: https://api.scalix.world/v1/build
  • Auth: HTTP bearer

Request body

source_typestring required

Where the source comes from: git or tarball.

source_urlstring nullable

Repository or archive URL. Must be reachable from the builder.

source_refstring nullable

Branch, tag or commit to build. Defaults to main. This is the branch field: git_ref is not recognised and is ignored if sent.

auth_tokenstring password nullable

Credential for a private repository, used as the password in the clone URL. A fine-grained token with read-only Contents access on that one repository is enough. It is held in memory for the build only: never stored, never written to build logs or error messages. Omit this when the Scalix GitHub App is installed for the project - a short-lived installation token is then minted per build and injected automatically.

dockerfile_pathstring nullable

Path to the Dockerfile within the source tree. Auto-detected if omitted.

image_tagstring nullable

Tag for the resulting image. Auto-generated if omitted.

build_argsobject nullable

Build-time ARGs passed to the builder. Project environment variables are merged in as well; values sent here win. These are stored on the build record and readable back from GET /v1/build/{id}, so treat them as non-secret: use them for things like a public API base URL, not tokens.

timeout_secondsinteger nullable

Build timeout in seconds. Default 600, maximum 3600.

Example request

{
  "source_type": "git",
  "source_url": "https://github.com/acme/api.git",
  "source_ref": "main",
  "dockerfile_path": "Dockerfile",
  "image_tag": "api:1.4.0",
  "timeout_seconds": 600
}

Response

Build started

Changes

No recorded changes to this operation across all 1 revision of this API.