Last updated January 26, 2022

This guide outlines how to fully utilize Heroku’s support for specifying dependencies for your Go application with godep.

Godep is a tool that vendors your application’s dependencies into its source repository thereby enabling repeatable builds and reducing external build dependencies.

Using godep

Install/update godep:

$ go get -u github.com/tools/godep

To have godep determine, save and rewrite your application’s dependencies, navigate to your application’s directory within $GOPATH and run the following command:

$ godep save ./...

This will have the following effects:

1. A Godeps/Godeps.json file will be created that contains the JSON representation of the application’s dependencies, the packages that we’re working on (the package spec) and the version of Go you are using locally.
2. Each dependency will be copied into a subdirectory of vendor/.

These changes need to be committed to your application’s git repository like so:

$ git add -A .
$ git commit -m "Vendoring dependencies"

The Godeps/Godeps.json file is used by Heroku’s Go buildpack to determine the version of Go to use when compiling the application. Because of this you should run godep save ./... on your application even if it doesn’t have any external dependencies.

Adding new dependencies

1. go get the new dependency.
2. Edit your application’s source code to import the new dependency.
3. Run godep save ./... to update Godeps/Godeps.json and copy the dependencies source to vendor/.

Updating an existing dependency

1. go get -u <dependency>.
2. godep update <dependency>.
3. Inspect the changes with git diff (or similar).
4. Commit the changes with git add -A .; git commit -m "Update <dependency>".

Changing the version of Go used to build your application

The major version of the Go toolchain is recorded in the Godeps/Godeps.json file in the GoVersion key and begins with go.

{
  "ImportPath": "github.com/heroku/go-getting-started",
  "GoVersion": "go1.6",
...
}

You can change the version in one of two ways:

1. Installing and using a new major go version locally and then running godep update -goversion. This adjusts Godeps/Godeps.json files based on the version of go you are using.

2. Manually changing the value of GoVersion in Godeps/Godeps.json to a valid major Go version (see go version).

Then committing the changes and pushing the app to Heroku will recompile the application with the current version of the newly specified major go version.

Specifying a specific minor version of Go

Godep records only the major version of the go toolchain (eg: go1.6 instead of go1.6.2). One each push Heroku will use the latest supported minor version of the toolchain to compile your application. This is our recommended setup. If however, you require a specific minor revision, this can be accomplished by specifying the full minor version in the GoVersion field of the Godeps/Godeps.json file.

Using a development version of Go

If you require a development version of Go, you can set the GoVersion field of the Godeps/Godeps.json file to devel-<short sha>. The <short-sha> should be replaced with the short git sha of the commit Heroku should use. On the next push, Heroku will retrieve that revision of Go from Github and compile it, using that version to build your application.

Migrating from Godep workspace to go1.6 with a vendor/ directory

• Make sure you are using go1.6 (go version).
• Make sure you have the latest godep (go get -u github.com/tools/godep)
• godep restore, to ensure the project’s dependencies are “restored” to your $GOPATH.
• If you are using rewrites run godep save -r=false <pkg spec> to remove them.
• rm -rf Godeps to remove old dependency info.
• godep save <pkg spec> to re-save the deps to vendor/.
• git add -A; git commit -am "Upgrade to go1.6" to commit the changes to the repo.
• git push heroku master to deploy using go1.6 and a vendor/ directory.

If you run into any problems please file a support ticket. Output from the above steps would be most helpful when troubleshooting.