This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo Go Buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo Go Buildpack How To documentation.
The Go Paketo Buildpack supports several versions of Go. For more details on the specific versions supported in a given buildpack version, see the release notes.
The Paketo Go Buildpack is a composite buildpack designed to build applications written in Go.
With the Go CNB, there are three options for package management depending on your application:
Support for each of these package managers is mutually-exclusive. You can find specific information for each option below.
The buildpack will vendor dependencies using go modules if the app source
code contains a
go.mod file. During the build phase, the
buildpack checks to see
if the application requires any external modules and if it does, 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 packages required for the build.
The buildpack 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.
The buildpack runs
go build to compile Go source code into executables. By
default, it sets the flag
-buildmode=pie. If there is a
go.mod present in
the app’s root directory, it also builds with
mod=vendor. See the Go tool’s documentation for details about build configuration.
The Go CNB sets a few environment variables during the
phases of the app lifecycle. The sections below describe each environment
variable and its impact on your app.
GOPATH environment variable tells Go where to look for artifacts such as
source code and binaries. The Go CNB takes care of setting the
you, depending on your app and which package management option your app uses.
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, the dependencies 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
GOPATH isn’t persisted beyond vendoring the dependencies and gets
overwritten by a subsequent buildpack.
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.
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.
|Paketo CA Certificates Buildpack||Optional||Installs custom CA certificates|
|Paketo Go Dist Buildpack||Required||Installs the Golang toolchain|
|Paketo Go Mod Vendor Buildpack||Optional||Installs app Go modules|
|Paketo Go Build Buildpack||Required||Compiles source code|
|Paketo Procfile Buildpack||Optional||Sets a user-specified start command|
|Paketo Environment Variables Buildpack||Optional||Sets user-specified launch-time environment variables|
|Paketo Image Labels Buildpack||Optional||Adds user-specified labels to app image metadata|
|Paketo Watchexec Buildpack||Optional||Installs
|Paketo Git Buildpack||Optional||Enables
The Go buildpack supports the full software bill of materials
(SBOM) in Syft, CycloneDX, and
SPDX formats. For apps with a
go.mod, this includes Go module
data. See Extract Go Module Information from a Build. The Go buildpack also
includes limited support for the Paketo-specific SBOM format.
This SBOM does not include Go module information.
Last modified: March 16, 2023