Skip to content

Clarify supported buildpack/lifecycle archive types and URI schemes #863

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+40 −26
Open

Clarify supported buildpack/lifecycle archive types and URI schemes #863

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
65f9530
Clarify supported buildpack/lifecycle archive types and URI schemes
xonas1101 Oct 25, 2025
8167481
Fix Vale style issues: active voice, wrap buildpacks terms, clean gra…
xonas1101 Oct 25, 2025
348d9b8
Fix Vale style issues: active voice, wrap buildpacks terms, clean gra…
xonas1101 Oct 25, 2025
6095b00
Fix Vale style issues: active voice, wrap buildpacks terms, clean gra…
xonas1101 Oct 25, 2025
9f5ced6
Fix Vale style issues: active voice, wrap buildpacks terms, clean gra…
xonas1101 Oct 25, 2025
3a3c2df
Fix Vale style issues: active voice, wrap buildpacks terms, clean gra…
xonas1101 Oct 25, 2025
90fc043
Fix Vale style issues: active voice, wrap buildpacks terms, clean gra…
xonas1101 Oct 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 40 additions & 26 deletions content/docs/reference/config/builder-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,13 @@
The schema is as follows:

- #### `description` _(string, optional)_

A human-readable description of the builder, to be shown in `builder inspect` output
(run `pack builder inspect -h` for more information).

- #### `buildpacks` _(list, optional)_
A list of buildpacks, each with the following fields:

A list of `buildpacks`, each with the following fields:

- **`id`** _(string, optional)_\
An identifier for the buildpack. Must match ID specified in buildpack's `buildpack.toml` file.
Expand All @@ -26,51 +28,52 @@
The version of the buildpack. Must match version specified in buildpack's `buildpack.toml` file.

- **`uri`** _(string)_\
A URL or path to an [archive](#supported-archives), a packaged buildpack (saved as a `.cnb` file), or a directory. If path is relative, it must be relative to the `builder.toml`.
A URL or path to an [archive](#supported-archives), a packaged buildpack (saved as a `.cnb` file), or a directory. If path is relative, it must be relative to the `builder.toml`.

Check warning on line 31 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 31, "column": 1}}}, "severity": "INFO"}

- #### `order` _(list, required)_
A list of buildpack groups. This list determines the order in which groups of buildpacks
will be tested during detection. Detection is a phase of the [lifecycle] where
buildpacks are tested, one group at a time, for compatibility with the provided application source code. The first
group whose non-optional buildpacks all pass detection will be the group selected for the remainder of the build. Each
group currently contains a single required field:

- **`group`** _(list, required)_\
A set of buildpack references. Each buildpack reference specified has the following fields:
A list of buildpack groups. This list determines the order in which the lifecycle tests groups of `buildpacks` during detection. Detection is a phase of the [lifecycle] where the lifecycle tests each `buildpacks` group, one at a time, for compatibility with the provided app source code. The first
group whose non-optional `buildpacks` all pass detection will be the group selected for the remainder of the build. Each group currently contains a single required field:

Check warning on line 36 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Will] Avoid using 'will'.

Raw Output:
{"message": "[Google.Will] Avoid using 'will'.", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 36, "column": 60}}}, "severity": "WARNING"}

- **`group`** _(list, required)_\
A set of buildpack references. Each buildpack reference specified has the following fields:

- **`id`** _(string, required)_\
The identifier of a buildpack from the configuration's top-level `buildpacks` list. Buildpacks with the same ID may
appear in multiple groups at once but never in the same group.
- **`id`** _(string, required)_\
The identifier of a buildpack from the configuration's top-level `buildpacks` list. `Buildpacks` with the same ID may
appear in multiple groups at once but never in the same group.

- **`version`** _(string, optional, default: inferred)_\
The version of the buildpack being referred to. This field may be omitted if
exactly one version of the buildpack
occurs in either the top-level `buildpacks` list or those buildpacks' dependencies.
- **`version`** _(string, optional, default: inferred)_\
The version of the buildpack being referred to. This field may be omitted if

Check warning on line 46 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('be omitted').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('be omitted').", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 46, "column": 70}}}, "severity": "INFO"}

Check warning on line 46 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('being referred').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('being referred').", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 46, "column": 36}}}, "severity": "INFO"}
exactly one version of the buildpack
occurs in either the top-level `buildpacks` list or in the dependencies of those `buildpacks`.

- **`optional`** _(boolean, optional, default: `false`)_\
Whether this buildpack is optional during detection.
- **`optional`** _(boolean, optional, default: `false`)_\
Whether this buildpack is optional during detection.

- #### `build` _(required)_

Build-time information. It contains the following field:

- **`image`** _(required, string)_\
Image to use as the build-time base

- #### `run` _(required)_

Run-time information. It contains the following:

- **`run.images`** _(list, required)_\
A set of run image references. By default, the first run image specified will be used.
Image extensions (experimental) may be used to switch the run image dynamically at build-time.
Each run image reference has the following:

- **`image`** _(string, required)_\
Image to use as the run-time base
- **`image`** _(string, required)_\
Image to use as the run-time base

- **`mirrors`** _(list, optional)_\
[Mirrors](/docs/for-app-developers/concepts/base-images/run#run-image-mirrors) for the provided image
- **`mirrors`** _(list, optional)_\
[Mirrors](/docs/for-app-developers/concepts/base-images/run#run-image-mirrors) for the provided image

- #### `stack` _(optional, deprecated)_

The stack to use for the builder. See [stack](/docs/for-app-developers/concepts/base-images/stack) concept information for more details.
This field should be specified if it is necessary to maintain compatibility with older platforms.
If specified, the information in this field must be consistent with the `build` and `run` fields (see above).
Expand All @@ -89,6 +92,7 @@
[Run image mirrors](/docs/for-app-developers/concepts/base-images/run#run-image-mirrors) for the stack

- #### `lifecycle` _(optional)_

The [lifecycle] to embed into the builder. It must contain **at most one** the following fields:

- **`version`** _(string, optional)_\
Expand All @@ -102,7 +106,8 @@
> will not change despite new lifecycle versions being released.

- #### `build.env` _(optional)_
The [[[build.env]]](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules) is used to specify [operator-defined](https://github.com/buildpacks/spec/blob/main/platform.md#operator-defined-variables) build-time environment variables for buildpacks. Set `CNB_BUILD_CONFIG_DIR` in pack's environment to override the default directory (`/cnb/build-config/env`) where environment variable files are stored within the builder.

The [[[build.env]]](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules) is used to specify [operator-defined](https://github.com/buildpacks/spec/blob/main/platform.md#operator-defined-variables) build-time environment variables for `buildpacks`. Set `CNB_BUILD_CONFIG_DIR` in pack's environment to override the default directory (`/cnb/build-config/env`) where environment variable files are stored within the builder.

Check warning on line 110 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('are stored').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('are stored').", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 110, "column": 438}}}, "severity": "INFO"}

Check warning on line 110 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('is used').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('is used').", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 110, "column": 122}}}, "severity": "INFO"}

Check warning on line 110 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 110, "column": 1}}}, "severity": "INFO"}

- **`name`** _(string, required)_\
The name/key of the environment variable.
Expand All @@ -111,16 +116,25 @@
The value of the environment variable.

- **`suffix`** _(string, optional)_\
The type of action used to modify the environment variable when end-users or buildpacks define the same name/key, one of [`default`](https://github.com/buildpacks/spec/blob/main/buildpack.md#default), [`override`](https://github.com/buildpacks/spec/blob/main/buildpack.md#override), [`append`](https://github.com/buildpacks/spec/blob/main/buildpack.md#append), or [`prepend`](https://github.com/buildpacks/spec/blob/main/buildpack.md#prepend). Defaults to `default` if this field is omitted. Operator-defined environment variables take precedence over end-user or buildpack-defined environment variables.
The type of action used to modify the environment variable when end-users or `buildpacks` define the same name/key, one of [`default`](https://github.com/buildpacks/spec/blob/main/buildpack.md#default), [`override`](https://github.com/buildpacks/spec/blob/main/buildpack.md#override), [`append`](https://github.com/buildpacks/spec/blob/main/buildpack.md#append), or [`prepend`](https://github.com/buildpacks/spec/blob/main/buildpack.md#prepend). Defaults to `default` if this field is omitted. Operator-defined environment variables take precedence over end-user or buildpack-defined environment variables.

Check warning on line 119 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('is omitted').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('is omitted').", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 119, "column": 487}}}, "severity": "INFO"}

- **`delim`** _(string, optional)_\
The delimiter used to concatenate two or more values for the given `name`.

> The `delim` is required when `suffix` is one of `append` or `prepend`.
> The `delim` is required when `suffix` is one of `append` or `prepend`.

Check warning on line 124 in content/docs/reference/config/builder-config.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('is required').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('is required').", "location": {"path": "content/docs/reference/config/builder-config.md", "range": {"start": {"line": 124, "column": 17}}}, "severity": "INFO"}

### Supported archives

Currently, when specifying a URI to a buildpack or lifecycle, only `tar` or `tgz` archive types are supported.
A URI to a buildpack or lifecycle can use one of the following sources:

- **Archives:** `.tar` or `.tgz` files, either local or remote.
- **Docker images:** the `docker://` URI scheme.

**Examples**

- `file:///path/to/buildpack.tgz`
- `https://example.com/buildpack.tar`
- `docker://example/buildpack:latest`

[builder]: /docs/for-platform-operators/concepts/builder
[lifecycle]: /docs/for-platform-operators/concepts/lifecycle
Loading