Heroku Cloud Native Buildpack: Go

heroku/go is the Heroku Cloud Native Buildpack for Go applications. It builds Go application source code into application images with minimal configuration.

Important

This is a Cloud Native Buildpack, and is a component of the Heroku Cloud Native Buildpacks project, which is in preview. If you are instead looking for the Heroku Classic Buildpack for Go (for use on the Heroku platform), you may find it here.

Usage

Note

Before getting started, ensure you have the pack CLI installed. Installation instructions are available here.

To build a Go application codebase into a production image:

$ cd ~/workdir/sample-go-app
$ pack build sample-app --builder heroku/builder:22

Then run the image:

docker run --rm -it -e "PORT=8080" -p 8080:8080 sample-app

Application Requirements

This buildpack should build any Go project that meets the following criteria:

• There is a go.mod at the root of the project.
• The app compiles with go 1.16 or greater.
• The app uses Go Modules for any dependency installation.

This buildpack does not support 3rd party dependency managers such as dep, godep, govendor, glide, etc.

Configuration

Go Version

This buildpack will read the Go version from the go line in go.mod. This is likely correct for most apps, but a different version may be selected using the // +heroku goVersion [{constraint}]{version} build directive in go.mod, if required.

For example, this will select the latest release in the 1.17 line.

go 1.17

While this would select go 1.18.2 exactly.

// +heroku goVersion =1.18.2
go 1.17

The =, ^, ~, >, < semver constraints are supported, but are optional. Note that the semver constraints are only supported for the heroku build directive.

Go Module Vendoring

If a vendor/modules.txt exists at the project root, the buildpack will attempt to use Go Modules from the vendor directory rather than downloading them. If this file does not exist, Go Modules will be downloaded prior to compiling.

Package Installation

This buildpack will build all main packages that it detects in the project, which should be adequate for most apps. A different list may optionally be specified using the // +heroku install {pkgspec} {[pkgspec]}... directive in go.mod if needed.

For example, this would build only the example-server and example-worker binaries.

// +heroku install example.com/example-server example.com/example-worker

Contributing

Issues and pull requests are welcome. See our contributing guidelines if you would like to help.