Merge 9e99dc88a9 into 85ca62d2ef

.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/setup-pack@v5.9.3
+        uses: buildpacks/github-actions/setup-pack@v5.9.1
         with:
           pack-version: '0.36.0'
       - name: Test

content/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment.md

@@ -11,12 +11,7 @@ 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 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.
+Below are a few ways you can do so. All of them will use our [samples] repo for simplicity.
 
 ### Using CLI arguments (`--env`)
 

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
 """
 ```

content/docs/for-buildpack-authors/how-to/write-buildpacks/clear-env.md

@@ -3,30 +3,20 @@ title="Clear the buildpack environment"
 weight=99
 +++
 
-"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.
+"Clearing" the buildpack environment with `clear-env` is the process of preventing end-users from customizing a buildpack's behavior through environment variables.
+
 <!--more-->
 
-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`.
+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`.
 
-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.
+* 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:
 
-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 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:
-
-| Environment Variable   | Description                                       | Detect | Build | Launch |
+| Env Variable           | Description                                       | Detect | Build | Launch |
 |------------------------|---------------------------------------------------|--------|-------|--------|
 | `BP_*`                 | User-provided variable for buildpack              | [x]    | [x]   |        |
 | `BPL_*`                | User-provided variable for exec.d                 |        |       | [x]    |
 
-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.
+### Further Reading
 
-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 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/).
+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/).

content/docs/reference/config/buildpack-config.md

@@ -29,10 +29,7 @@ The schema is as follows:
     Human readable name.
 
   - **`clear-env`** _(boolean, optional, default: `false`)_\
-    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.
+    Clears user-defined environment variables when `true` on executions of `bin/detect` and `bin/build`.
 
   - **`homepage`** _(string, optional)_\
     Buildpack homepage.