Merge 9f6ebb11fe into cc6c6cdf1b

Bumps [buildpacks/github-actions](https://github.com/buildpacks/github-actions) from 5.9.1 to 5.9.3.
- [Release notes](https://github.com/buildpacks/github-actions/releases)
- [Commits](https://github.com/buildpacks/github-actions/compare/v5.9.1...v5.9.3)

---
updated-dependencies:
- dependency-name: buildpacks/github-actions
  dependency-version: 5.9.3
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

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

content/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`)
 

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,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`.
 
-* 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:
+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.
 
-| Env Variable           | Description                                       | Detect | Build | Launch |
+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 |
 |------------------------|---------------------------------------------------|--------|-------|--------|
 | `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 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 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/).

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.

tools/go.mod

@@ -89,7 +89,7 @@ require (
 	github.com/chrismellard/docker-credential-acr-env v0.0.0-20230304212654-82a0ddb27589 // indirect
 	github.com/clbanning/mxj/v2 v2.7.0 // indirect
 	github.com/cli/safeexec v1.0.1 // indirect
-	github.com/cloudflare/circl v1.3.7 // indirect
+	github.com/cloudflare/circl v1.6.1 // indirect
 	github.com/containerd/log v0.1.0 // indirect
 	github.com/containerd/stargz-snapshotter/estargz v0.15.1 // indirect
 	github.com/containerd/typeurl/v2 v2.1.1 // indirect

tools/go.sum

@@ -238,8 +238,8 @@ github.com/clbanning/mxj/v2 v2.7.0/go.mod h1:hNiWqW14h+kc+MdF9C6/YoRfjEJoR3ou6tn
 github.com/cli/safeexec v1.0.1 h1:e/C79PbXF4yYTN/wauC4tviMxEV13BwljGj0N9j+N00=
 github.com/cli/safeexec v1.0.1/go.mod h1:Z/D4tTN8Vs5gXYHDCbaM1S/anmEDnJb1iW0+EJ5zx3Q=
 github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
-github.com/cloudflare/circl v1.3.7 h1:qlCDlTPz2n9fu58M0Nh1J/JzcFpfgkFHHX3O35r5vcU=
-github.com/cloudflare/circl v1.3.7/go.mod h1:sRTcRWXGLrKw6yIGJ+l7amYJFfAXbZG0kBSc8r4zxgA=
+github.com/cloudflare/circl v1.6.1 h1:zqIqSPIndyBh1bjLVVDHMPpVKqp8Su/V+6MeDzzQBQ0=
+github.com/cloudflare/circl v1.6.1/go.mod h1:uddAzsPgqdMAYatqJ0lsjX1oECcQLIlRpzZh3pJrofs=
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
 github.com/cncf/udpa/go v0.0.0-20200629203442-efcf912fb354/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=
 github.com/cncf/udpa/go v0.0.0-20201120205902-5459f2c99403/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=