From 65f953089dd2d841ca50e169ae95a1d6c50ddde3 Mon Sep 17 00:00:00 2001 From: xonas1101 Date: Sat, 25 Oct 2025 12:11:02 +0000 Subject: [PATCH 1/7] Clarify supported buildpack/lifecycle archive types and URI schemes Signed-off-by: xonas1101 --- .../docs/reference/config/builder-config.md | 53 ++++++++++++------- 1 file changed, 35 insertions(+), 18 deletions(-) diff --git a/content/docs/reference/config/builder-config.md b/content/docs/reference/config/builder-config.md index 261160c89..964b073ad 100644 --- a/content/docs/reference/config/builder-config.md +++ b/content/docs/reference/config/builder-config.md @@ -13,10 +13,12 @@ The builder config file is used for creating [builders][builder]. 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: - **`id`** _(string, optional)_\ @@ -26,37 +28,40 @@ The schema is as follows: 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`. - #### `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: + - **`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 + exactly one version of the buildpack + occurs in either the top-level `buildpacks` list or those buildpacks' dependencies. - - **`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)_\ @@ -64,13 +69,14 @@ The schema is as follows: 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). @@ -89,6 +95,7 @@ The schema is as follows: [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)_\ @@ -102,6 +109,7 @@ The schema is as follows: > 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. - **`name`** _(string, required)_\ @@ -116,11 +124,20 @@ The schema is as follows: - **`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`. ### Supported archives -Currently, when specifying a URI to a buildpack or lifecycle, only `tar` or `tgz` archive types are supported. +When specifying a URI to a buildpack or lifecycle, the following sources are supported: + +- **Archives:** `.tar` or `.tgz` files, either local or remote. +- **Docker images:** using 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 From 81674810b7e6b81f440b9efd0ce3feefd8436eaa Mon Sep 17 00:00:00 2001 From: xonas1101 Date: Sat, 25 Oct 2025 13:19:19 +0000 Subject: [PATCH 2/7] Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar Signed-off-by: xonas1101 --- content/docs/reference/config/builder-config.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/docs/reference/config/builder-config.md b/content/docs/reference/config/builder-config.md index 964b073ad..2443178fb 100644 --- a/content/docs/reference/config/builder-config.md +++ b/content/docs/reference/config/builder-config.md @@ -42,13 +42,13 @@ The schema is as follows: 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 + 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. + occurs in either the top-level `buildpacks` list or or in the dependencies of those `buildpacks`. - **`optional`** _(boolean, optional, default: `false`)_\ Whether this buildpack is optional during detection. @@ -128,12 +128,12 @@ The schema is as follows: ### Supported archives -When specifying a URI to a buildpack or lifecycle, the following sources 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:** using the `docker://` URI scheme. +- **Docker images:** the `docker://` URI scheme. -**Examples:** +**Examples** - `file:///path/to/buildpack.tgz` - `https://example.com/buildpack.tar` From 348d9b87957a214c60d079bf6970c2789140df2d Mon Sep 17 00:00:00 2001 From: xonas1101 Date: Sat, 25 Oct 2025 13:21:47 +0000 Subject: [PATCH 3/7] Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar Signed-off-by: xonas1101 --- content/docs/reference/config/builder-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/reference/config/builder-config.md b/content/docs/reference/config/builder-config.md index 2443178fb..c9fbcb8dc 100644 --- a/content/docs/reference/config/builder-config.md +++ b/content/docs/reference/config/builder-config.md @@ -48,7 +48,7 @@ The schema is as follows: - **`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 or in the dependencies of those `buildpacks`. + 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. From 6095b00bba644317964eba5dfbb7bfb63e720cd4 Mon Sep 17 00:00:00 2001 From: xonas1101 Date: Sat, 25 Oct 2025 13:30:03 +0000 Subject: [PATCH 4/7] Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar Signed-off-by: xonas1101 --- content/docs/reference/config/builder-config.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/docs/reference/config/builder-config.md b/content/docs/reference/config/builder-config.md index c9fbcb8dc..5076937d2 100644 --- a/content/docs/reference/config/builder-config.md +++ b/content/docs/reference/config/builder-config.md @@ -19,7 +19,7 @@ The schema is as follows: - #### `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. @@ -32,10 +32,10 @@ The schema is as follows: - #### `order` _(list, required)_ - A list of buildpack groups. This list determines the order in which groups of buildpacks + 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 + `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)_\ @@ -110,7 +110,7 @@ The schema is as follows: - #### `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. - **`name`** _(string, required)_\ The name/key of the environment variable. @@ -119,7 +119,7 @@ The schema is as follows: 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. - **`delim`** _(string, optional)_\ The delimiter used to concatenate two or more values for the given `name`. From 9f5ced6c038bf42001adbf811582ba6923999b78 Mon Sep 17 00:00:00 2001 From: xonas1101 Date: Sat, 25 Oct 2025 13:46:50 +0000 Subject: [PATCH 5/7] Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar Signed-off-by: xonas1101 --- content/docs/reference/config/builder-config.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/content/docs/reference/config/builder-config.md b/content/docs/reference/config/builder-config.md index 5076937d2..da44ca320 100644 --- a/content/docs/reference/config/builder-config.md +++ b/content/docs/reference/config/builder-config.md @@ -33,10 +33,8 @@ The schema is as follows: - #### `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: + will be tested 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: - **`group`** _(list, required)_\ A set of buildpack references. Each buildpack reference specified has the following fields: From 3a3c2df5d58ce0931264496f1b357fe3ecbd08fc Mon Sep 17 00:00:00 2001 From: xonas1101 Date: Sat, 25 Oct 2025 13:51:49 +0000 Subject: [PATCH 6/7] Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar Signed-off-by: xonas1101 --- content/docs/reference/config/builder-config.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/docs/reference/config/builder-config.md b/content/docs/reference/config/builder-config.md index da44ca320..763ec4d99 100644 --- a/content/docs/reference/config/builder-config.md +++ b/content/docs/reference/config/builder-config.md @@ -32,9 +32,8 @@ The schema is as follows: - #### `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 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: + 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: - **`group`** _(list, required)_\ A set of buildpack references. Each buildpack reference specified has the following fields: From 90fc0437e2cadcecab31389725ada5e137c26625 Mon Sep 17 00:00:00 2001 From: xonas1101 Date: Sat, 25 Oct 2025 13:59:38 +0000 Subject: [PATCH 7/7] Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar Signed-off-by: xonas1101 --- content/docs/reference/config/builder-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/reference/config/builder-config.md b/content/docs/reference/config/builder-config.md index 763ec4d99..d13d04b3d 100644 --- a/content/docs/reference/config/builder-config.md +++ b/content/docs/reference/config/builder-config.md @@ -32,7 +32,7 @@ The schema is as follows: - #### `order` _(list, required)_ - 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 + 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: - **`group`** _(list, required)_\