--- title: "Build a version" url: "https://docs.alisx.com/how-to/alis-build/build-a-version/" --- # Build a version Turn a pushed commit of the product's build repo into a new, immutable service version with its Docker images. Build is the second step of Define, Build, Deploy. ## Prerequisites - Your changes are committed and pushed. Build reads the remote, never your working tree. - A Dockerfile in the service folder, or `--confirm-no-paths` for a service without images. ## Build the latest pushed commit ```bash title="Terminal" alis build acme.sh.orders.v1 ``` By default the latest pushed commit that touched the service folder on the currently checked-out branch is built. Progress streams to stderr; the finished operation prints to stdout with the new `version`, one entry per image under `images[]` and a `logsUri`. Inside the service folder the package id can be omitted. ## Choose what to build | Goal | Command | |---|---| | A specific pushed branch (recommended in automation) | `alis build --branch main` | | An exact commit | `alis build --commit `; add `--branch` to require that the commit is on that branch | | Only some images | `alis build --build-path . --build-path worker` | | Infrastructure changed, code did not | `alis build --retag` keeps the previous images under the new version; `--retag-path` retags only some | | A service without any Dockerfile | `alis build --confirm-no-paths` | | A hotfix of an older commit | `alis build --commit --branch --definition-version ` carries the definition that code was built against (the version `go.mod` requires), so the deploy syncs no unrelated schema changes; see [the build reference](https://docs.alisx.com/reference/cli/build.md#definition-version) | | Build on this machine instead of the platform | `alis build --local` builds the pushed commit with your Docker, pushes the images and registers the version; see below | A detached checkout must pass `--branch`. Retagging an image whose build context changed since the last build prints a warning. ## Build on your own machine ```bash title="Terminal" alis build acme.sh.orders.v1 --local ``` `--local` runs the Docker builds here instead of on the platform's builder: the pushed commit is staged in a temporary worktree, each image is built for `linux/amd64` with the product's build credentials mounted as a secret (private Alis packages resolve as on the platform) and pushed to the product's registry, and the version is then registered from the pushed images. The commit must still be pushed; the version, tag and deploy are the same as for a platform build. It needs a running Docker with buildx and is not available inside agent sandboxes. In the TUI it is **Build locally** under ++shift+b++, and **Build locally first, then deploy** under ++shift+d++ on a deployment environment. ## Do not wait for the build ```bash title="Terminal" alis build acme.sh.orders.v1 --async --json ``` The result carries the operation `name` and the exact `next` command. Re-attach with `alis operations wait `, or give up waiting on a running build with `--timeout 10m` (the build continues server-side). `--quiet` hides progress; `--poll-interval` changes how often progress is read (default 2s). ## Build and deploy in one step ```bash title="Terminal" alis build acme.sh.orders.v1 --deploy -e ``` `--deploy` attaches a deployment request that runs once the build succeeds. Repeat `-e` for several deployment environments; when the product has exactly one deployment environment it is used without `-e`. `--plan-only` turns the attached deploy into a Terraform plan. A production environment needs confirmation, and a deployment environment with designated branches asks before deploying a version built from another branch (`--allow-branch-mismatch`). See [Deploy a version](https://docs.alisx.com/how-to/alis-build/deploy-a-version.md). ## Read the result A version is in one of these states: `BUILDING`, `BUILT`, `RETAGGED` or `FAILED`. On failure the operation's `error` and `images[].progress.failure` name the step that failed; `alis logs build ` prints the log tail. The console lists versions on the product's **Services** page; select a deployment to see every version and its state. A build runs on the organisation's shared build server. When that server restarts or is stopped while a build is running, the build fails on its own with the reason in its log ("the build server restarted while this execution was running"), and a build the server never reports on within 90 minutes of its start fails with `BUILD_UNREPORTED`; in both cases the version is `FAILED` and a new build can start at once. A build still running can be stopped with `alis operations cancel `. ## Related - [Dockerfile detection](https://docs.alisx.com/reference/dbd/dockerfile-detection.md) - [Operations and output](https://docs.alisx.com/reference/dbd/operations-and-output.md) - [Deployment environments and versions](https://docs.alisx.com/explanation/environments-and-versions.md)