Builds

A build is one execution of a pipeline. Every push, pull request, or manual run produces exactly one build. The build is the thing you watch in the dashboard, the thing you debug, and the thing that produces images, artifacts, and deploys.

If a pipeline is the recipe, a build is the meal.

From the terminal

You can list and inspect builds from the Loha CLI (loha builds) as well as the dashboard (coming soon). The underlying API (GET /api/v1/builds) is live today.

Identifying a build

Every build has a unique build id: this is the canonical way to refer to a build. It's the first column of the builds list, it's in the build's page title, and it's the last part of the build's URL (/workspaces/<workspace>/builds/<build-id>).

The build id is what you share when you need to point a teammate at a specific build: paste it into a chat or a ticket, or open the build's URL directly. The builds table shows a shortened form with a copy button that copies the full id to your clipboard.

A build id is stable and unique for the lifetime of the build. It never changes and is never reused. A retry produces a new build with its own id, so the original and the retry are each independently addressable. Behind the scenes the same id identifies the build's underlying execution in the cluster, so platform operators can trace a dashboard build straight through to its logs and events.

Lifecycle

A build moves through a small set of states:

State	Meaning
Queued	Accepted by Loha, waiting for a runner. Usually milliseconds.
Running	At least one job is executing. Logs stream live.
Succeeded	All jobs finished cleanly.
Failed	At least one job exited non-zero, or a step timed out.
Cancelled	A user clicked Cancel, or a newer commit superseded this build.
Timed out	The build exceeded its plan-defined wall-clock limit.

Inside the build, each job has its own status, and inside each job, each step has its own status. The build's overall status is derived from the worst job state: one failed job means a failed build.

What you see live

While a build is running, the dashboard shows:

• Live logs for every step, streamed character-by-character.
• Step-level timing: start, duration, current status.
• Job graph: visual needs: dependencies, what's done, what's running, what's still waiting.
• Status badge: sharable URL to the latest build for a branch.

Logs are persisted after the build finishes, so failed builds are debuggable hours or days later. Sensitive values from your secrets are redacted from logs before they reach your browser.

What a build produces

Depending on what your pipeline does, a build can output:

• Container images: pushed to a container registry you bring and configure under Settings → Registries. See the buildah-build and docker-build tasks. Every image a successful build pushes is recorded as a release, with its digest.
• Manifests: updated GitOps manifests committed back to a manifests repo. See git-update-manifest.
• Notifications: LINE, Slack, or generic webhook pings. See notify-line and notify-webhook.

Outputs persist beyond the build itself. Logs are kept according to your plan's retention window; releases are kept indefinitely, so the record of what a commit produced outlives the build that produced it.

Caching

Most pipelines repeat work: fetching the same npm dependencies, compiling the same Go modules. Loha provides a cache step with key + restore-keys semantics so dependencies are downloaded once and reused on subsequent builds. See the caching guide for patterns.

Caches are scoped to the workspace: never shared across workspaces, never visible to another customer.

Retries and re-runs

A retry is always a new build with a new id. The build history keeps both the original and the retry, so the audit trail stays honest. A retry uses the same commit and inputs as the build it retries.

The build page offers these retry actions:

Action	What runs again
Retry failed jobs (the main button)	Jobs that failed or never finished, plus every job downstream of them. Everything else is reused.
Retry (everything reruns)	The same button when Loha cannot reuse anything from the original build. Every job runs again.
Retry all (in the More retry options menu next to the button)	Every job, exactly like starting the same build again.
Retry this job (on a job in the logs, passed jobs included)	That job, every job downstream of it, and anything those jobs need that cannot be reused. Rest is reused.

Each action opens a confirmation dialog before anything starts. It lists the jobs under Will run again, each with the reason, and the jobs it reuses under Reused, not run again. For a matrix job, the build page offers Retry this job on each shard, and it retries that shard only. To retry every shard of a matrix job at once, use the API: a retry request whose jobs list names the job id as written in .loha.yml (for example { "jobs": ["test"] }) retries every shard, and a shard id (for example test-18) retries that shard only.

Reused jobs

A reused job is not executed again. Its files (the outputs it declared with artifacts:) and its image digests come from the build that originally ran it, and the jobs that do run again receive them as if the job had just finished.

• The build page shows these jobs in a Reused jobs card and links each one as Reused from #N, where N is the build that executed the job. If you retry a retry, the link still points to the build that actually ran the job, not to the build in between.
• Reused jobs are not billed again. A retry is billed for the time its own jobs run, nothing more.
• A reused job that was skipped by its own if: condition stays skipped.
• A reused image job produces nothing new: no new release, scan, signature or promotion. The original build stays the record for that image digest, so a retry never re-scans, re-signs or re-promotes an image you did not rebuild.

Loha reuses a job only when it can prove that running it again would give the same result. When it cannot, the job runs again, and the dialog tells you why. These always run again:

• Approval jobs. An approval gate asks every time.
• Image jobs that did not record an image digest, or whose original build failed the final security gate. With an enforcing security policy, a build that failed before the gate ran has no gate decision, so its image jobs run again.
• Jobs whose saved output expires within 24 hours. An archive that is about to be deleted is not a safe thing to hand on.
• Jobs that hand files on without declaring them. A job that does not declare artifacts: may have passed files to later jobs through the shared workspace disk, which a retry cannot recreate. Declare the files with artifacts: (an empty paths: [] is fine for a job that hands nothing on) to make the job reusable. A pipeline with no uses: steps at all shares nothing on disk between jobs, so this rule does not apply to it.
• Everything, when the original build has no pinned commit. A manual Run now build follows the branch tip instead of a fixed commit, so a retry cannot prove that the reused results match its code.

Why did a job run again?

The confirmation dialog gives one reason per job that runs again. Reasons are:

Reason	The dialog says	What it means
selected	Selected to run again.	You chose this job with Retry this job.
failed	It failed or did not finish last time.	Retry failed jobs picked it because it failed, was cancelled, or never started.
depends_on	Linked to job, which runs again.	The job is linked by needs to a job that runs again, either upstream or downstream, so it has to run again too.
no_artifacts_declared	It declares no artifacts, so later jobs cannot reuse its result.	The job does not declare artifacts:, so its files cannot be handed on from the old build.
image_digest_missing	Its image digest was not recorded, so the old result cannot be reused.	The original build did not record the digest of the image this job pushed.
gate_failed	The security gate failed on its image, so it runs again.	The original build's final security gate did not pass for this image (or never ran), so it is not reused.
approval_gate	Approval gates always ask again.	Approval jobs are never reused.
artifact_expired	Its saved output has expired or is about to.	The job's archive is gone or expires within 24 hours.
skipped_by_condition	Job was skipped by its condition and stays skipped.	Not a rerun: the job's if: skipped it the first time and skips it again. The dialog shows it as a note.

If a job runs again because of a reason that is not "you chose it", the fix is usually in the pipeline: declare artifacts: on the job, or make sure the build can record its image digest.

Fix the pipeline from a failed build

When a build comes from a trigger that reads its pipeline from your repository (a .loha.yml file), the first failing step shows Fix pipeline from this build. It opens the Pipeline Builder on the trigger with that step's job and step already selected. A retry runs the pipeline of the original build, so commit your change to the repository and start a new build to run the edited pipeline.

Cancelling

Click Cancel in the dashboard to stop a running build. In-flight steps are killed, and downstream jobs that haven't started are skipped. The build moves to Cancelled.

If a newer commit lands on the same branch while an older build is still running, Loha can be configured to auto-cancel the older one: useful when only the latest commit's result matters.

Concurrency limits

Each plan caps how many builds can run in parallel within a workspace. When you exceed the cap, the next build sits in Queued until a slot opens. Free-tier workspaces typically run one at a time; higher tiers run several.

Where to go next

• Pipelines: defining what a build runs
• Triggers: what causes a build to start
• Caching: making builds faster
• Dashboard tour: finding builds in the UI