Building blocks of a Cloud Native Buildpack

Now we will set up the buildpack scaffolding.

Let’s create the directory where your buildpack will live:

Using the Pack CLI

The buildpack new <id> command will create a directory named for the buildpack ID.


pack buildpack new examples/ruby \
    --api 0.8 \
    --path ruby-buildpack \
    --version 0.0.1 \
    --stacks io.buildpacks.samples.stacks.jammy

This command will create ruby-buildpack directory which contains buildpack.toml, bin/build, bin/detect files.

Additional Parameters

  • -a, --api Buildpack API compatibility of the generated buildpack
  • -h, --help Help for ’new'
  • --path the location on the filesystem to generate the artifacts.
  • --stacks Stack(s) this buildpack will be compatible with. Repeat for each stack in order, or supply once by comma-separated list
  • -V, --version the version of the buildpack in buildpack.toml


You will have ruby-buildpack/buildpack.toml in your buildpack directory to describe our buildpack.

# Buildpack API version
api = "0.8"

# Buildpack ID and metadata
  id = "examples/ruby"
  version = "0.0.1"

# Stacks that the buildpack will work with
  id = "io.buildpacks.samples.stacks.jammy"

You will notice two specific fields in the file: and The buildpack ID is the way you will reference the buildpack when you create buildpack groups, builders, etc. The stack ID is the root file system in which the buildpack will be run. This example can be run on one of two different stacks, both based upon Ubuntu Bionic.

detect and build

Next, we will cover the detect and build scripts. These files are created in bin directory in your buildpack directory.

Now update your ruby-buildpack/bin/detect file and copy in the following contents:

#!/usr/bin/env bash
set -eo pipefail

exit 1

Also update your ruby-buildpack/bin/build file and copy in the following contents:

#!/usr/bin/env bash
set -eo pipefail

echo "---> Ruby Buildpack"
exit 1

These two files are executable detect and build scripts. You are now able to use this buildpack.

Using your buildpack with pack

In order to test your buildpack, you will need to run the buildpack against your sample Ruby app using the pack CLI.

Set your default builder by running the following:

pack config default-builder cnbs/sample-builder:jammy

Tell pack to trust our default builder:

pack config trusted-builders add cnbs/sample-builder:jammy

Then run the following pack command:

pack build test-ruby-app --path ./ruby-sample-app --buildpack ./ruby-buildpack

The pack build command takes in your Ruby sample app as the --path argument and your buildpack as the --buildpack argument.

After running the command, you should see that it failed to detect, as the detect script is currently written to simply error out.

err:  examples/ruby@0.0.1 (1)
ERROR: No buildpack groups passed detection.
ERROR: failed to detect: buildpack(s) failed with err

Next Step