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-pathsfor a service without images.
Build the latest pushed commit¶
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 <pkg> --branch main |
| An exact commit | alis build <pkg> --commit <sha>; add --branch to require that the commit is on that branch |
| Only some images | alis build <pkg> --build-path . --build-path worker |
| Infrastructure changed, code did not | alis build <pkg> --retag keeps the previous images under the new version; --retag-path retags only some |
| A service without any Dockerfile | alis build <pkg> --confirm-no-paths |
| A hotfix of an older commit | alis build <pkg> --commit <sha> --branch <hotfix> --definition-version <X.Y.Z> 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 |
| Build on this machine instead of the platform | alis build <pkg> --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¶
--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 ShiftB, and Build locally first, then deploy under ShiftD on a deployment environment.
Do not wait for the build¶
The result carries the operation name and the exact next command. Re-attach with alis operations wait <name>, 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¶
--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.
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 <operation> 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 <operation>.