docs(build): document Docker image rebuild rules

[fabienfleureau]

Summary by cubic

Documents exactly when Qovery rebuilds Docker images and what inputs affect the generated image tag.

• Explains that the tag is computed from commit, Dockerfile path/content, declared ARG values, secret mount IDs, target stage, injected files, fragments, and the Git submodule setting, with two existence checks before and after parsing the Dockerfile.
• Clarifies that build.disable_buildkit_cache disables layer caching but does not force a rebuild, while force_build only bypasses the first check.
• Updates the environment variables, advanced settings, and optimization guide pages to match the new rebuild rules.

^{Written for commit a62cca9. Summary will update on new commits.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
qovery	🟢 Ready	View Preview	Sep 22, 2026, 10:14 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[Copilot]

Copilot review overview

🟡 Changes recommended

Documentation ordering, terminology, and completeness issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2

Open (2)

• Reorder build flow before push and repository organization · New
• Clarify secret values, not mount IDs, affect final tag · New

What changed in this PR

This PR documents Qovery’s Docker image rebuild and reuse rules and the inputs affecting generated image tags.

Changes:

• Documents image-tag inputs and existence checks.
• Clarifies cache, force-build, submodule, variable, and secret behavior.
• Updates optimization and configuration guidance.

File	Summary
docs/​getting-started/​guides/​qovery-101/​optimize.mdx	Updates build optimization guidance.
docs/​configuration/​service-advanced-settings.mdx	Clarifies cache and submodule settings.
docs/​configuration/​environment-variables.mdx	Documents build-variable tag behavior.
docs/​configuration/​deployment/​image-mirroring.mdx	Adds detailed image rebuild rules.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cubic-dev-ai]

5 issues found across 4 files

Confidence score: 4/5

• docs/configuration/environment-variables.mdx does not clearly document that declared build-secret values affect image-tag recomputation, and its wording can imply the tag depends only on ARGs and secret mount IDs; clarify the value inputs and complete tag inputs to avoid incorrect rebuild expectations.
• docs/configuration/deployment/image-mirroring.mdx leaves the behavior of unmatched optional secret IDs unclear: the secret mount is omitted and /run/secrets/<id> is absent, while required=true changes the behavior; document this explicitly or link to the build-secret rules.
• docs/getting-started/guides/qovery-101/optimize.mdx does not explain that an existing mirrored tag can cause Qovery to skip the Docker build even when an input changes; state the tag-existence condition and rename the monitoring heading to match the content.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/configuration/environment-variables.mdx">

<violation number="1" location="docs/configuration/environment-variables.mdx:147">
P3: 'recomputes the tag using only its declared ARG values and secret mount IDs' reads as if the final tag is computed solely from those variables, while the linked section lists commit ID, Dockerfile path/content, injected files, and others as tag inputs. Restrict 'only' to the variable inputs so the sentence cannot be misread as contradicting the complete tag-input list.</violation>

<violation number="2" location="docs/configuration/environment-variables.mdx:147">
P2: The recomputation description omits secret values and names only the mount IDs, contradicting the rule above that rotating a declared build secret changes the image tag. State that Qovery includes the values of build secrets referenced by their mount IDs, not just the IDs, so users can distinguish tag invalidation from BuildKit layer-cache reuse.</violation>
</file>

<file name="docs/getting-started/guides/qovery-101/optimize.mdx">

<violation number="1" location="docs/getting-started/guides/qovery-101/optimize.mdx:196">
P2: When a changed input produces a tag that already exists in the mirroring registry, Qovery skips the Docker build. The image-mirroring rules explicitly make the build conditional on that tag being absent, so this unconditional `Rebuilds when` claim can make users expect a build that will not occur. Describe the new-tag calculation and existing-tag reuse condition here.</violation>

<violation number="2" location="docs/getting-started/guides/qovery-101/optimize.mdx:198">
P3: The heading no longer matches its content: "Monitoring Git commits" describes tracking which services commits affect, while the new text only states that the commit is added to the image tag. Rename the label to describe the tag behavior, e.g. "Tagging images with the Git commit", so the three bullets stay parallel with the change.</violation>
</file>

<file name="docs/configuration/deployment/image-mirroring.mdx">

<violation number="1" location="docs/configuration/deployment/image-mirroring.mdx:43">
P2: An unmatched optional secret ID omits the mount, so `/run/secrets/<id>` does not exist; this new secret-input rule does not tell readers that. State the omission and `required=true` behavior, or link to the build-secret rules.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When a changed input produces a tag that already exists in the mirroring registry, Qovery skips the Docker build. The image-mirroring rules explicitly make the build conditional on that tag being absent, so this unconditional Rebuilds when claim can make users expect a build that will not occur. Describe the new-tag calculation and existing-tag reuse condition here.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/getting-started/guides/qovery-101/optimize.mdx, line 196:

<comment>When a changed input produces a tag that already exists in the mirroring registry, Qovery skips the Docker build. The image-mirroring rules explicitly make the build conditional on that tag being absent, so this unconditional `Rebuilds when` claim can make users expect a build that will not occur. Describe the new-tag calculation and existing-tag reuse condition here.</comment>

<file context>
@@ -193,9 +193,9 @@ Qovery optimizes your application builds to save time and resources.
 Qovery avoids unnecessary rebuilds by:
 
-- **Detecting code changes**: Only rebuilds when application code changes
+- **Detecting build-input changes**: Rebuilds when the commit, Dockerfile, declared build arguments or secrets, target stage, injected files, fragments, or submodule setting changes
 - **Skipping unchanged services**: If no changes detected, uses previous build
-- **Monitoring Git commits**: Tracks which services are affected by commits
</file context>

Suggested change

	- **Detecting build-input changes**: Rebuilds when the commit, Dockerfile, declared build arguments or secrets, target stage, injected files, fragments, or submodule setting changes
	- **Detecting build-input changes**: Changes to the commit, Dockerfile, values of declared build arguments or secrets, target stage, injected files, fragments, or submodule setting produce a new image tag; Qovery builds it only when that tag is not already in the registry

[cubic-dev-ai]

P2: The recomputation description omits secret values and names only the mount IDs, contradicting the rule above that rotating a declared build secret changes the image tag. State that Qovery includes the values of build secrets referenced by their mount IDs, not just the IDs, so users can distinguish tag invalidation from BuildKit layer-cache reuse.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/configuration/environment-variables.mdx, line 147:

<comment>The recomputation description omits secret values and names only the mount IDs, contradicting the rule above that rotating a declared build secret changes the image tag. State that Qovery includes the values of build secrets referenced by their mount IDs, not just the IDs, so users can distinguish tag invalidation from BuildKit layer-cache reuse.</comment>

<file context>
@@ -142,6 +142,12 @@ RUN --mount=type=secret,id=NPM_TOKEN,required=true npm ci
 
+Variables that the Dockerfile does not declare do not change the final image
+tag. Qovery first makes a prediction from the request, then parses the
+Dockerfile and recomputes the tag using only its declared `ARG` values and
+secret mount IDs. See [when Docker images are rebuilt](/configuration/deployment/image-mirroring#when-is-the-docker-image-rebuilt)
+for the complete list of tag inputs.
</file context>

Suggested change

	Dockerfile and recomputes the tag using only its declared `ARG` values and
	secret mount IDs. See [when Docker images are rebuilt](/configuration/deployment/image-mirroring#when-is-the-docker-image-rebuilt)
	Dockerfile and recomputes the tag using the values of its declared `ARG`s and
	the values of build secrets referenced by their mount `id`s. See [when Docker images are rebuilt](/configuration/deployment/image-mirroring#when-is-the-docker-image-rebuilt)

[cubic-dev-ai]

P2: An unmatched optional secret ID omits the mount, so /run/secrets/<id> does not exist; this new secret-input rule does not tell readers that. State the omission and required=true behavior, or link to the build-secret rules.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/configuration/deployment/image-mirroring.mdx, line 43:

<comment>An unmatched optional secret ID omits the mount, so `/run/secrets/<id>` does not exist; this new secret-input rule does not tell readers that. State the omission and `required=true` behavior, or link to the build-secret rules.</comment>

<file context>
@@ -26,12 +26,48 @@ When Qovery builds your application from Git:
+- Git commit ID and repository root path
+- Dockerfile path and content
+- Values of build arguments declared by the Dockerfile
+- Values of build secrets referenced by `RUN --mount=type=secret,id=...`
+- Target build stage
+- Injected files, including their paths and contents
</file context>

Suggested change

	- Values of build secrets referenced by `RUN --mount=type=secret,id=...`
	- Values of build secrets referenced by `RUN --mount=type=secret,id=...`; an unmatched optional `id` omits the mount, while `required=true` fails the build

[cubic-dev-ai]

P3: 'recomputes the tag using only its declared ARG values and secret mount IDs' reads as if the final tag is computed solely from those variables, while the linked section lists commit ID, Dockerfile path/content, injected files, and others as tag inputs. Restrict 'only' to the variable inputs so the sentence cannot be misread as contradicting the complete tag-input list.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/configuration/environment-variables.mdx, line 147:

<comment>'recomputes the tag using only its declared ARG values and secret mount IDs' reads as if the final tag is computed solely from those variables, while the linked section lists commit ID, Dockerfile path/content, injected files, and others as tag inputs. Restrict 'only' to the variable inputs so the sentence cannot be misread as contradicting the complete tag-input list.</comment>

<file context>
@@ -142,6 +142,12 @@ RUN --mount=type=secret,id=NPM_TOKEN,required=true npm ci
 
+Variables that the Dockerfile does not declare do not change the final image
+tag. Qovery first makes a prediction from the request, then parses the
+Dockerfile and recomputes the tag using only its declared `ARG` values and
+secret mount IDs. See [when Docker images are rebuilt](/configuration/deployment/image-mirroring#when-is-the-docker-image-rebuilt)
+for the complete list of tag inputs.
</file context>

[cubic-dev-ai]

P3: The heading no longer matches its content: "Monitoring Git commits" describes tracking which services commits affect, while the new text only states that the commit is added to the image tag. Rename the label to describe the tag behavior, e.g. "Tagging images with the Git commit", so the three bullets stay parallel with the change.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/getting-started/guides/qovery-101/optimize.mdx, line 198:

<comment>The heading no longer matches its content: "Monitoring Git commits" describes tracking which services commits affect, while the new text only states that the commit is added to the image tag. Rename the label to describe the tag behavior, e.g. "Tagging images with the Git commit", so the three bullets stay parallel with the change.</comment>

<file context>
@@ -193,9 +193,9 @@ Qovery optimizes your application builds to save time and resources.
+- **Detecting build-input changes**: Rebuilds when the commit, Dockerfile, declared build arguments or secrets, target stage, injected files, fragments, or submodule setting changes
 - **Skipping unchanged services**: If no changes detected, uses previous build
-- **Monitoring Git commits**: Tracks which services are affected by commits
+- **Monitoring Git commits**: Includes the Git commit in the generated image tag
 
 This reduces build times and CI/CD costs by avoiding redundant builds.
</file context>

Suggested change

	- **Monitoring Git commits**: Includes the Git commit in the generated image tag
	- **Tagging with the Git commit**: Includes the Git commit in the generated image tag

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	qovery-doc-mintlify-proxy	a62cca9	Sep 22 2026, 10:09 AM