Build Optimizer

Overview

The Build Optimizer is in preview. The API below works for every organization with AI features enabled, as long as build analysis is available on its Qovery instance (otherwise starting an analysis returns 503, see Start Errors); the Console entry point is not available to every organization yet. The result format and the analysis itself may still change.

The Build Optimizer analyzes the latest Docker build of an application or job and explains how to make it faster. It reads the Dockerfile, the build logs and the cache history of earlier builds, finds the steps that re-ran instead of being cached, and tells you what invalidated their cache. Use it when a build takes longer than it should, for example when a dependency install (npm ci, pip install, go mod download) runs on every deployment although your dependencies did not change. Typical causes are COPY . . placed before the dependency install, or a build argument declared before the install whose value changes between builds. The analysis runs on demand, on one build, from the API or the Console. It is not a Copilot chat command. It never changes your Dockerfile, your build settings or your image: it returns suggestions for you to review and apply.

For a scheduled agent that reviews build and deployment times and opens pull requests with the changes, see the Build & Deployment Optimizer Agent Task.

Requirements

Requirement	Details
AI features enabled	The organization must have AI features enabled (`ai_features_enabled` on the organization). Otherwise starting an analysis returns `403`. An organization admin can change it with Edit the organization’s AI features opt-in.
Supported services	Applications built from a git repository with a Dockerfile, and cron or lifecycle jobs built from a Dockerfile, either stored in the git repository or written inline on the job. Services deployed from a container image have no build to analyze.
A build to analyze	Only the latest build of the service can be analyzed: its most recent deployment that ran a build, successful or failed (a failed build only through the API). A deployment that reused an existing image did not build anything and does not count. `latest_build_execution_id` is `null` when no deployment in the kept history ran a build.
A readable Dockerfile	Qovery reads the Dockerfile from the repository at the commit of that build, or the job’s inline Dockerfile. It must not be empty and must be at most about 100 KB (102,400 characters). Otherwise starting an analysis returns `422`.
Permissions	Starting an analysis needs the Deploy permission or higher on the service’s environment. Reading the result needs Read-Only. See Members & RBAC.
One at a time	A service runs one analysis at a time. Starting another while one is running returns `409`.

Run an Analysis

From the Console

Where the Console entry point is available for your organization:

Open the logs of the latest build

Open the service, go to Deployments, and open the logs of its latest deployment that ran a build. In the Console, the build must have succeeded; to analyze a failed build, use the API.

Start the analysis

On the Build step, click Optimize. The button shows Analyzing while the analysis runs; hover it to see the current step.

Build step of the deployment logs, with the Optimize button next to the step name

Optimize is disabled, with the reason on hover, when the build did not succeed, when the deployment is not the service’s latest build, or when the build analysis is unavailable. If the previous analysis failed, hovering Optimize shows why, and clicking it starts a new one.

Read the result

The result opens by itself when the analysis you started is done. If it fails, an error message shows the reason. Later, the button reads Open analysis and opens the same result.The result shows the review confidence, the estimated time saved (when there is one), the assets reviewed, the summary and the Improvements target. Below them, Prompt for AI agents and Reworked Dockerfile (when the analysis returns one) are collapsed, each with a Copy button. Values hidden from the analysis appear as <redacted> in the reworked Dockerfile: put them back before using it.

Build optimization analysis with High review confidence, an estimated time saved of 1min 30s – 1min 50s, the assets reviewed and the summary

From the API

The examples use an application. For a cron or lifecycle job, set URL to https://api.qovery.com/job/$JOB_ID/buildAnalysis.

Get the latest build

Read the build analysis of the service. latest_build_execution_id is the only build you can analyze, and analysis holds the previous analysis, if any.

QOVERY_API_TOKEN="REPLACE_WITH_YOUR_API_TOKEN"
APPLICATION_ID="REPLACE_WITH_APPLICATION_ID"
URL="https://api.qovery.com/application/$APPLICATION_ID/buildAnalysis"

RESPONSE=$(curl -sS --fail-with-body "$URL" -H "Authorization: Token $QOVERY_API_TOKEN")
echo "$RESPONSE"
EXECUTION_ID=$(echo "$RESPONSE" | jq -r '.latest_build_execution_id')

{
  "latest_build_execution_id": "6e5c1d3a-6b6f-4c35-9a2f-8f1d2c3b4a5e-42",
  "analysis": null
}

Start the analysis

Send that execution ID. The API answers 202 with the new analysis in PENDING, and the analysis continues in the background. Any other status means the analysis did not start: see Start Errors, and do not wait for a result.

curl -sS --fail-with-body -X POST "$URL" \
  -H "Authorization: Token $QOVERY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"execution_id\": \"$EXECUTION_ID\"}"

Starting an analysis replaces the previous one of the service.

Wait for the result

Read the build analysis again until analysis.status is DONE or FAILED. The loop prints each status. It also stops, and prints the error, when a request fails (for example an invalid token), and it stops on null when the service has no analysis.

while :; do
  RESPONSE=$(curl -sS --fail-with-body "$URL" \
    -H "Authorization: Token $QOVERY_API_TOKEN") || { echo "$RESPONSE"; break; }
  STATUS=$(echo "$RESPONSE" | jq -r '.analysis.status')
  echo "$STATUS"
  case "$STATUS" in DONE|FAILED|null) break ;; esac
  sleep 10
done

Read the result

curl -sS --fail-with-body "$URL" -H "Authorization: Token $QOVERY_API_TOKEN" | jq '.analysis'

See What You Get Back for the fields.

API reference: Get the build analysis of an application, Analyse the latest build of an application, and the same calls for a job.

Start Errors

Code	Meaning
`400`	`execution_id` is missing or blank.
`403`	You lack the Deploy permission, or AI features are disabled for the organization.
`404`	The service does not exist.
`409`	The execution is not the latest build, the service has no build, or an analysis is already running. Read the build analysis again to get the current `latest_build_execution_id`.
`422`	Qovery cannot read the Dockerfile of this build, for example a path that does not exist at the build commit.
`500`	Qovery could not load the build or the service’s secret values, which it needs to keep them out of the analysis. Retry later.
`503`	Build analysis is not available on this Qovery instance. Retrying does not help.

Progress

Status	Step	What happens
`PENDING`	Starting	The analysis is accepted. The Dockerfile was already read when the API answered `202`.
`COLLECTING`	Reading build logs and cache history	Qovery gathers what the analysis reviews (see below).
`ANALYSING`	Analysing with AI	The AI model works on the build.
`DONE`	Done	`analysis.result` holds the result.
`FAILED`	Failed, or Timed out	`failure_code` and `failure_reason` say why.

Failure code	Meaning
`MODEL_ERROR`	The AI model failed or returned an unusable result.
`TIMEOUT`	The analysis took too long, for example the AI model did not answer within 4 minutes.
`INTERNAL_ERROR`	Any other error.

If Qovery restarts cleanly during an analysis, the analysis fails with INTERNAL_ERROR and failure_reason says so: start it again. If the Qovery process stops without warning, the analysis keeps its last status (COLLECTING or ANALYSING) for up to 11 minutes, then reads as FAILED with TIMEOUT. During those 11 minutes, starting a new analysis returns 409.

Follow progress live with the websocket route

Progress is also streamed on the websocket route /build/analysis of wss://ws.qovery.com, with the query parameters organization, cluster, project, environment and service (all IDs). It needs the same access as the service logs.Each frame is one progress event:

{
  "status": "COLLECTING",
  "step": "Reading build logs and cache history",
  "message": null,
  "terminal": false
}

Past events are replayed first, then new ones as they come. message explains a failure. The connection closes with code 1000 after the event with "terminal": true (DONE or FAILED). Without that event, it closes with 1011 when the progress is unavailable, or 1001 after 15 minutes. Read the build analysis to get the result.

What the Analysis Reviews

Asset	What Qovery reads
`DOCKERFILE`	The Dockerfile of the build: from the repository at the build commit (`dockerfile_source: GIT`), or the job’s inline Dockerfile (`INLINE`).
`DOCKERIGNORE`	Whether a `.dockerignore` file exists in the root path of the repository at the build commit. Only for a Dockerfile from git.
`BUILD_SETTINGS`	The root path, the Dockerfile path, the target build stage, and the names of the build arguments.
`BUILD_LOGS`	For each BuildKit step: its instruction, its duration, and whether it was cached or re-ran. Also the base image digests, the build context size, and, when reported, the CPU and memory used by the builder and any out-of-memory kill.

The analysis also reads the cache history: up to 10 earlier builds that can have written the cache this build started from. The layer cache is shared by every build of the same repository, root path, Dockerfile and target stage on the same cluster, whatever the branch or environment. The history only includes builds of your own organization. So the history includes earlier builds of the service and builds of other services built from the same repository, for example the same application in another environment. When those builds alternate, each one can start from a cache the other overwrote. For each build argument, the analysis learns whether its value differs from the build that last wrote the cache, and how many distinct values it has across the services sharing the cache. Qovery compares the values itself and sends only the result. assets_reviewed in the result lists what was available for this analysis.

What You Get Back

Field	Description
`summary`	Two to four sentences on what slows the build and why, with the evidence: the step, its seconds, what invalidated its cache. Says so when the build is already efficient.
`confidence`	`HIGH`, `MEDIUM` or `LOW`. See the table below.
`estimated_time_saved`	Seconds saved on each build once every improvement is applied, as `min_seconds` and `max_seconds`. `null` when there is nothing to save or no timing to base it on.
`improvements`	The changes to make, one sentence each, highest impact first. Empty when the build is already efficient. An improvement can also be a Qovery setting, for example moving a variable from a build argument to a runtime variable.
`dockerfile`	The reworked Dockerfile, made of targeted edits to your original file, never a full rewrite. `null` when no improvement is a Dockerfile change, or when the edits cannot be applied cleanly to your file.
`dockerfile_rationale`	Why the reworked Dockerfile builds faster. `null` when there is no reworked Dockerfile.
`agent_prompt`	A ready-to-paste prompt for your AI coding agent (Claude Code, Cursor, Copilot) to apply the changes in your repository.
`assets_reviewed`	What the analysis read. See What the Analysis Reviews.

The analysis itself also carries execution_id (the analyzed build) and stale, which is true once the service has a newer build than the analyzed one.

Confidence

The confidence says how sure the analysis is that applying the improvements saves the estimated time.

Confidence	When
`HIGH`	The build logs, the cache history or the builder metrics show both the cause (for example a build argument value that changed, or an out-of-memory kill) and the seconds it costs.
`MEDIUM`	One of the two, the cause or the time, is inferred.
`LOW`	Only the Dockerfile suggests the issue, or there are improvements but no time range.

When there is no improvement, the confidence says how sure the analysis is that the build has nothing left to gain.

Apply the Result

Review the analysis

Read the summary and the improvements. The analysis is a suggestion: check that each change keeps your image behaving the same way.

Apply the changes

Use either:

Copy the reworked Dockerfile from dockerfile, when the analysis returns one. Values hidden from the analysis appear as <redacted>: put back the values of your original file before you commit.
Paste agent_prompt into your coding agent. It names the files and the exact changes, asks the agent to keep the image behavior identical, to put back any <redacted> value, to build twice locally and check the second build hits the cache, and to stop for your review before committing or deploying.

Improvements that are Qovery settings, such as build-time variables, are changed in the Console or the API.

Deploy and compare

Commit, then deploy. The first build after a Dockerfile change re-runs the changed steps, so compare the build time on the builds after it. You can run a new analysis on the latest build to check what is left.

Limits and Data Handling

Suggestions only. Qovery never changes your Dockerfile, your build settings or your image. Starting an analysis never triggers a build.
Latest build only. Only the latest build of a service can be analyzed. Qovery keeps one analysis per service: a new analysis replaces the previous one, and the kept one is marked stale once a newer build exists.
AI model. The analysis runs on an Anthropic Claude model through Amazon Bedrock, called by Qovery.
Dockerfile values are hidden. Before the Dockerfile is sent, every literal ARG and ENV value is replaced with <redacted> (references such as $NODE_ENV are kept). So are credential-like strings: AWS access key IDs, GitHub, GitLab and Slack tokens, npm auth tokens, private keys, credentials in URLs and Authorization header values.
Secret values are masked. The values of the service’s secret variables are masked in the Dockerfile and the build logs before they are sent, and in the stored result. Values shorter than 6 characters are not masked.
Build arguments are compared, not sent. The analysis receives their names and whether their values changed between builds. Non-secret values can still appear in the build log lines that are sent, where BuildKit prints them.

Build-Time Variables

Pass variables as build arguments or build secrets.

Build Settings

Build timeout, resources and BuildKit cache.

Deployment Logs

Read the build logs of a deployment.

Build & Deployment Optimizer

Agent Task that reviews build and deployment times and opens pull requests.

Overview

Getting Started

Capabilities

Examples

Build Optimizer

Overview

Requirements

Run an Analysis

From the Console

From the API

Start Errors

Progress

What the Analysis Reviews

What You Get Back

Confidence

Apply the Result

Limits and Data Handling

Build-Time Variables

Build Settings

Deployment Logs

Build & Deployment Optimizer

​Overview

​Requirements

​Run an Analysis

​From the Console

​From the API

​Start Errors

​Progress

​What the Analysis Reviews

​What You Get Back

​Confidence

​Apply the Result

​Limits and Data Handling

​Related

Build-Time Variables

Build Settings

Deployment Logs

Build & Deployment Optimizer

Overview

Requirements

Run an Analysis

From the Console

From the API

Start Errors

Progress

What the Analysis Reviews

What You Get Back

Confidence

Apply the Result

Limits and Data Handling

Related