The Tanzu Go Buildpack supports several popular configurations for Go apps.

Specifying a Go Version

The Go Cloud Native Buildpack will attempt to automatically detect the correct version of Go to install based on the version in your app’s go.mod. It is possible to override this version by setting the BP_GO_VERSION environment variable at build time. When specifying a version of Go, you must choose a version that is available within the buildpack. The supported versions can be found in the release notes.

The buildpack prioritizes the versions specified in each possible configuration location with the following precedence, from highest to lowest: BP_GO_VERSION, go.mod.

Specifying a version of Go is not required. In the case that is not specified, the buildpack will provide the default version, which can be seen in the buildpack.toml file.

Configuring Build Flags

The go build command supports a number of flags that allow users to override defaults for more control over build configurations. By default, the buildpack sets the following build flags:

  • -buildmode=pie
  • -mod=vendor (if there is a go.mod file in the app source code)

To set custom values for your build flags or override the defaults, assign a list of flags to the BP_GO_BUILD_FLAGS environment variable as shown below:

BP_GO_BUILD_FLAGS=-buildmode=some-build-mode -tags=paketo,production -ldflags="-X main.variable=some-value" -race

Configuring Targets

The Go CNB allows users to specify multiple targets for go build. This will result in multiples binaries being built.Targets must be a list of paths relative to the root directory of the source code.

To set custom targets for your build assign a list of targets to the $BP_GO_TARGETS environment variable as shown below:


Configuring Import Paths

If you are building a $GOPATH application that imports its own sub-packages, you will need to specify the import paths for those sub-packages. The Go CNB supports setting these import paths via the $BP_GO_BUILD_IMPORT_PATH environment variable:

Configuring File Removal

The Go CNB by default deletes the contents of your app root once it has compiled your app in an effort to optimize the size the final image. However sometimes there are static assets that you would like to appear in the final image. To have these files or directories persist set the BP_KEEP_FILES environment variable.


Package Management Options

With the Go CNB, there are three options for package management depending on your application:

  • The built-in Go modules feature,
  • The Dep tool
  • No package manager

Support for each of these package managers is mutually-exclusive. You can find specific information for each option below.

Package Management with Go Modules

Many Go apps require third-party libraries to perform common tasks and behaviors. Go modules are a built-in option for managing these third-party dependencies that the Go CNB fully supports. Including a go.mod file in your app source code instructs the buildpack to vendor your dependencies using Go modules. During the build phase, the go-mod-vendor buildpack simply runs the go mod vendor command for your app. The resulting vendor directory will exist in the app's root directory and will contain all the packages needed to build your Go app.

Package Management with Dep

Dep is an alternative option to Go Modules for package management in Go apps. Including a Gopkg.toml file (more information about this here) in your app source code instructs the buildpack to download the dep package, and then vendor your dependencies using it. There may be an optional Gopkg.lock file that outlines specific versions of the dependencies to be packaged. During its build phase, the dep-ensure buildpack runs the dep ensure command for your app. The resulting vendor directory will exist in the app's root directory and will contain all the packages needed to build your Go app.

No Package Management

The Go CNB also supports both self-vendored apps and simpler apps that do not require third-party packages. In this case there is no vendoring step, and the go build command is run on the app source code as it is provided.

Import Private Go Modules

The Go buildpack can build apps that import private Go modules. Credentials to access private Go modules are provided via a service binding.

  1. Set up a directory for the service binding:
mkdir /tmp/git-binding
echo "git-credentials" > /tmp/git-binding/type
touch /tmp/git-binding/credentials
  1. Add git credentials for accessing the private modules to /tmp/git-binding/credentials following the git credentials structure.

For example, to access a private module with a Github username and service account key, add the following to /tmp/git-binding/credentials:

  1. Provide the service binding and $GOPRIVATE environment variable at build time:
pack build myapp --buildpack <go-buildpack> \
                 --env GOPRIVATE="" \
                 --env SERVICE_BINDING_ROOT="/bindings" \
                 --volume /tmp/git-binding:/bindings/git-binding

You'll see that the build successfully pulls your app's private dependencies. The secrets stored in the service binding will not be stored in the built app image.

Buildpack-Set Environment Variables

The Go CNB sets a few environment variables during the build and launch phases of the app lifecycle. The sections below describe each environment variable and its impact on your app.


The GOPATH environment variable tells Go where to look for artifacts such as source code and binaries. The Go CNB takes care of setting the GOPATH for you, depending on your app and which package management option your app uses.

  • Set by: go-mod-vendor, dep-ensure and go-build
  • Phases: build
  • Value: path to Go workspace

Go Modules

When using Go modules, the Go CNB sets the GOPATH to a cached module layer in the image so that between builds of the app, thedependencies don't have to be redownloaded. Essentially, the GOPATH is being used to tell the go mod vendor command where to look for dependencies. It's worth noting that in this case, the GOPATH isn't persisted beyond vendoring the dependencies and gets overwritten by a subsequent buildpack.


When using the Dep tool, the Go CNB sets the GOPATH to a temporary directory. The app source code gets copied into the GOPATH location so that the dep ensure command knows where to look for the source code, as well as where to put the vendor directory. The vendor directory that is created is then copied to the original source code directory. The GOPATH in this case is used to run dep ensure, but does not persist beyond that step.


The go-build buildpack participates in the Go CNB in every case, regardless of which package management option is used. The GOPATH is set to a temporary directory which includes the app source code and local sub-packages. The GOPATH is utilized in running go build to compile your app.


The GOCACHE variable specifies where build outputs are stored for reuse in subsequent builds. It gets set to a cached layer in the image by the go-build buildpack, so that it is persisted between builds.

  • Set by: go-build
  • Phases: build
  • Value: Go Cache layer path


DEPCACHEDIR specifies where upstream dependency source code is stored for use by the Dep tool. The dep-ensure buildpack sets this variable to the path of a cache layer in the app image.

  • Set by: dep-ensure
  • Phases: build
  • Value: Dep Cache layer path

Extract Go Module Information From A Build

The Go buildpack produces a Software Bill of Materials (SBOM) for the dependencies installed in the app image during a build. It is possible to extract information about the Go modules used in the build using the build-time SBOM.

With pack and a Command-Line Flag

  1. When building with the pack CLI, use the flag --sbom-output-dir to extract SBOMs from the build:
pack build my-app --buildpack <tanzu-go-buildpack> \
                  --sbom-output-dir /tmp/sbom-output
  1. To view the Go modules used in the build, inspect one of the SBOMs generated by the Go Mod Vendor buildpack. For instance, to view the SBOM as CycloneDX JSON:
cat /tmp/sbom-output/build/tanzu-buildpacks_go-mod-vendor/sbom.cdx.json

Additional Configuration

Install a Custom CA Certificate

Go buildpack users can provide their own CA certificates and have them included in the container root truststore at build-time and runtime by following the instructions outlined in the CA Certificates section of our configuration docs.

Override the Start Process Set by the Buildpack

Go buildpack users can set custom start processes for their app image by following the instructions in the Procfiles section of our configuration docs.

Set Environment Variables for App Launch Time

Go buildpack users can embed launch-time environment variables in their app image by following the documentation for the Environment Variables Buildpack.

Add Custom Labels to the App Image

Go buildpack users can add labels to their app image by following the instructions in the Applying Custom Labels section of our configuration docs.

check-circle-line exclamation-circle-line close-line
Scroll to top icon