Hawthorne001 · pull · Aug 12, 2025 · Aug 12, 2025 · Aug 12, 2025 · Aug 12, 2025
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -24,7 +24,7 @@ jobs:
       - name: Install Dependencies
         run: sudo apt-get install make curl jq
       - name: Install pack
-        uses: buildpacks/github-actions/[email protected].1
+        uses: buildpacks/github-actions/[email protected].3
         with:
           pack-version: '0.36.0'
       - name: Test

diff --git a/...docs/for-app-developers/how-to/build-inputs/configure-build-time-environment.md b/...docs/for-app-developers/how-to/build-inputs/configure-build-time-environment.md
@@ -11,7 +11,12 @@ Environment variables are a common way to configure various buildpacks at build-
 
 <!--more-->
 
-Below are a few ways you can do so. All of them will use our [samples] repo for simplicity.
+Below are a few ways you can do so. All of them use the [samples] repository for
+simplicity. The following documentation assumes that all participating buildpack
+either use `clear-env = false` as the default in their
+[buildpack.toml](https://buildpacks.io/docs/reference/config/buildpack-config/),
+or if they use `clear-env = true`, that they merge in filtered user supplied
+environment variables.
 
 ### Using CLI arguments (`--env`)
 

diff --git a/content/docs/for-app-developers/how-to/build-inputs/use-inline-buildpacks.md b/content/docs/for-app-developers/how-to/build-inputs/use-inline-buildpacks.md
@@ -50,7 +50,7 @@ find . -type f -name $(my_data_files) -delete
 cat <<EOF > ${1}/launch.toml
 [[processes]]
 type = 'bash'
-command = 'bin/bash'
+command = ['bin/bash']
 EOF
 """
 ```

diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/clear-env.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/clear-env.md
@@ -3,20 +3,30 @@ title="Clear the buildpack environment"
 weight=99
 +++
 
-"Clearing" the buildpack environment with `clear-env` is the process of preventing end-users from customizing a buildpack's behavior through environment variables.
-
+"Clearing" the buildpack environment with `clear-env` is the process of preventing the lifecycle from automatically merging user-provided environment variables into the buildpack's executing process's environment variables.
 <!--more-->
 
-Buildpack authors may elect to clear user-provided environment variables when `bin/detect` and `bin/build` are executed. This is achieved by setting `clear-env` to `true` in [buildpack.toml](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpacktoml-toml); by default `clear-env` is set to `false`.
+User-provided environment variables are always written to disk at `$CNB_PLATFORM_DIR/env/` as "platform" environment variables and are available to a buildpack regardless of the `clear-env` setting. For example, if someone runs `pack build --env HELLO=world`, there is always a `$CNB_PLATFORM_DIR/env/hello` file with the contents of `world`.
+
+By default with `clear-env = false`, the lifecycle automatically copies these user-provided environment variables into the current process environment when executing `/bin/detect` and `/bin/build`. This provides a comprehensive stream of all user environment variables for a buildpack that wants easy access to user customization.
+
+Setting `clear-env = true` in the [buildpack.toml](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpacktoml-toml) prevents this automatic merging, giving a buildpack complete control over which user-provided environment variables to use. This provides maximum isolation and predictability for a buildpack that wants to be more selective about environment variable usage.
+
+For example, if a user has specified the `PATH` environment variable, then a buildpack written in bash might unexpectedly find that tools it relies on such as `cp` aren't the ones it expects. However, setting `clear-env = true` won't change runtime behavior.
 
-* When `clear-env` is set to `true` for a given buildpack, the `lifecycle` will not set user-provided environment variables when running `/bin/detect` or `/bin/build`.
-* If a buildpack does allow customization by the end-user through the environment (`clear-env` is `false`), there is a special convention for naming the environment variables recognized by the buildpack, shown in the following table:
+* When you set `clear-env` to `true` for a given buildpack, the `lifecycle` writes user-provided environment variables to disk at `$CNB_PLATFORM_DIR/env/` but it won't copy those variables into the buildpack process when running `/bin/detect` or `/bin/build`.
+* If a buildpack uses `clear-env = false` which allows customization by the end-user through the environment, there is a special convention for naming the environment variables recognized by the buildpack, shown in the following table:
 
-| Env Variable           | Description                                       | Detect | Build | Launch |
+| Environment Variable   | Description                                       | Detect | Build | Launch |
 |------------------------|---------------------------------------------------|--------|-------|--------|
 | `BP_*`                 | User-provided variable for buildpack              | [x]    | [x]   |        |
 | `BPL_*`                | User-provided variable for exec.d                 |        |       | [x]    |
 
-### Further Reading
+Buildpack that use `clear-env = true` should filter and export environment variables from `$CNB_PLATFORM_DIR/env/` while warning on the filtered variables. Emitting a warning helps users understand if runtime behavior differs from build time behavior. Sourcing the user environment variables is critical to allowing sub-processes access to credentials.
+
+For example, if a private gem server hosted on `gems.example.com` needs access in a sub-process such as `bundle install`, the user must provide `BUNDLE_GEMS__EXAMPLE__COM=<username>:<password>`. If `clear-env = true` and the buildpack doesn't use platform environment variables, then trying to access that resource would fail.
+
+
+### Further reading
 
-For more about how environment variables are specified by end-users, see the page for how to [customize buildpack behavior with build-time environment variables](https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment/).
+For more about how end-users specify environment variables, see the page for how to [customize buildpack behavior with build-time environment variables](https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment/).
diff --git a/content/docs/reference/config/buildpack-config.md b/content/docs/reference/config/buildpack-config.md
@@ -29,7 +29,10 @@ The schema is as follows:
     Human readable name.
 
   - **`clear-env`** _(boolean, optional, default: `false`)_\
-    Clears user-defined environment variables when `true` on executions of `bin/detect` and `bin/build`.
+    When `true`, prevents the lifecycle from automatically merging user-provided
+    environment variables into the buildpack process environment during
+    `bin/detect` and `bin/build`. User-provided environment variables remain
+    available at `$CNB_PLATFORM_DIR/env/` regardless of this setting.
 
   - **`homepage`** _(string, optional)_\
     Buildpack homepage.