buildpack.toml

The buildpack configuration file is a necessary component of a buildpack.

The schema is as follows:

  • api (string, required, current: 0.10)
    The Buildpack API version the buildpack adheres to. Used to ensure compatibility against the lifecycle.

    Not to be confused with Cloud Foundry or Heroku buildpack versions. This version pertains to the interface between the buildpack and the lifecycle of Cloud Native Buildpacks.

  • buildpack (required)
    Information about the buildpack.

    • id (string, required)
      A globally unique identifier.

    • version (string, required)
      The version of the buildpack.

    • name (string, required)
      Human readable name.

    • clear-env (boolean, optional, default: false)
      Clears user-defined environment variables when true on executions of bin/detect and bin/build.

    • homepage (string, optional)
      Buildpack homepage.

    • description (string, optional)
      A short description of the buildpack.

    • keywords (string(s), optional)
      Keywords to help locate the buildpack. These can be useful if publishing to the Buildpack Registry.

    • sbom-formats (string(s), optional)
      SBOM formats output by the buildpack. Supported values are the following media types: application/vnd.cyclonedx+json, application/spdx+json, and application/vnd.syft+json.

    • licenses (list, optional)
      A list of licenses pertaining to the buildpack.

      • type (string, optional)
        The type of the license. This may use the SPDX 2.1 license expression, but it is not limited to identifiers in the SPDX Licenses List. If the buildpack is using a nonstandard license, then the uri key may be specified in lieu of or in addition to type to point to the license.

      • uri (string, optional)
        A URL or path to the license.

  • targets (list, optional)
    A list of targets supported by the buildpack. When no targets are specified, the os/arch will be inferred from the contents of the ./bin directory (./bin/build implies linux/amd64 and ./bin/build.bat implies windows/amd64). For each target, all fields are optional (though at least one should be provided). Cannot be used in conjunction with order list.

    • os (string, optional)
      The supported operating system name.

    • arch (string, optional)
      The supported architecture.

    • variant (string, optional)
      The supported architecture variant.

    • targets.distros (optional)
      A list of supported distributions for the given operating system, architecture, and architecture variant.

      • name (string, optional)
        The supported operating system distribution name.

      • version (string, optional)
        The supported operating system distribution version.

  • stacks (list, deprecated, optional)
    A list of stacks supported by the buildpack. Cannot be used in conjunction with order list.

    • id (string, required)
      The id of the supported stack.

    • mixins (string list, required)
      A list of mixins required on the stack images.

  • order (list, optional)
    A list of buildpack groups for the purpose of creating a composite buildpack (sometimes referred to as a “meta buildpack”). This list determines the order in which groups of buildpacks will be tested during detection. If omitted, targets or stacks list must be present. Cannot be used in conjunction with targets or stacks list.

    • group (list, required)
      A list of buildpack references.

      • id (string, required)
        The identifier of a buildpack being referred to. Buildpacks with the same ID may appear in multiple groups at once but never in the same group.

      • version (string, required)
        The version of the buildpack being referred to.

      • optional (boolean, optional, default: false)
        Whether this buildpack is optional during detection.

  • metadata (any, optional)
    Arbitrary data for buildpack.