Last updated June 23, 2020

This guide outlines how to fully use Heroku’s support for deploying Go applications that use dep to manage the vendoring of dependencies.

The dep README covers the most common usage of the tool. We’ll cover the most common activities below.

Build configuration

When pushing code that uses dep, Heroku will use several entries in the Gopkg.toml file created by dep to configure your build. These entries are:

• metadata.heroku['root-package'] (String): the root package name of the packages you are pushing to Heroku.You can find this locally with go list -e .. There is no default for this and it must be specified.

• metadata.heroku['go-version'] (String): the major version of go you would like Heroku to use when compiling your code: if not specified defaults to the most recent supported version of Go.

• metadata.heroku['install'] (Array of Strings): a list of the packages you want to install. If not specified, this defaults to ["."]. Other common choices are: ["./cmd/..."] (all packages and sub packages in the cmd directory) and ["./..."] (all packages and sub packages of the current directory). The exact choice depends on the layout of your repository though. Please note that ./..., for versions of go < 1.9, includes any packages in your vendor directory.

• metadata.heroku['ensure'] (String): if this is set to false then dep ensure is not run.

• metadata.heroku['additional-tools'] (Array of Strings): a list of additional tools that the buildpack is aware of that you want it to install. If the tool has multiple versions an optional @<version> suffix can be specified to select that specific version of the tool. Otherwise the buildpack’s default version is chosen. Currently the only supported tool is github.com/mattes/migrate at v3.0.0 (also the default version).

Here is an example of these fields for a project using go1.8.3, located on your local machine at $GOPATH/src/github.com/heroku/go-getting-started and requiring a single package spec of ./... to install.

[metadata.heroku]
  root-package = "github.com/heroku/go-getting-started"
  go-version = "1.8.3"
  install = [ "./..." ]
...

You will need to use a text editor to edit the Gopkg.toml file to configure, at least, the metadata.heroku['root-package'] entry.

Ignored vendor/ sub directories

Heroku runs dep ensure before running go install whenever dep is detected. This is done to ensure that all dependencies specified in Gopkg.lock are installed in your application’s vendor/ directory. This allows you to not have to check in the contents of vendor/.

If you do check in the contents of vendor/, dep ensure is effectively a no-op if it’s hash of the contents of vendor/ match the inputs-digest from Gopkg.lock.

Install or update dep

Please see dep’s setup instructions.

Getting started

1. dep init
2. Inspect the changes with git diff and git status.
3. You likely want to remove the backup of your old vendor folder, which has been renamed to _vendor-<TIMESTAMP>. But it may be useful to review this beforehand.
4. Commit the changes with git add -A vendor Gopkg.toml Gopkg.lock; git commit -am "Switch to Dep"ou l

Adding dependencies

1. dep ensure -add <package name>
2. Edit and save your code so that it uses the new dependency.
3. Inspect the changes with git diff (or similar).
4. Commit the changes with git add -A vendor Gopkg.toml Gopkg.lock; git commit -am "Add dependency <package>"

If you need to change the version, branch or revision of your dependency you will need to modify the entries added to Gopkg.toml and then rundep ensure. Details of the Gopkg.toml file can be found here.

Dependency status

$ dep status
PROJECT                              CONSTRAINT  VERSION        REVISION  LATEST   PKGS USED
github.com/gin-contrib/sse           *           branch master  22d885f   22d885f  1
github.com/gin-gonic/gin             ^1.2.0      v1.2           d459835   d459835  3
github.com/golang/protobuf           *           branch master  130e6b0   130e6b0  1
github.com/mattn/go-isatty           *           v0.0.2         fc9e8d8   0360b2a  1
github.com/ugorji/go                 *           branch master  54210f4   54210f4  1
golang.org/x/sys                     *           branch master  429f518   314a259  1
gopkg.in/go-playground/validator.v8  *           v8.18.2        5f1438d   5f1438d  1
gopkg.in/yaml.v2                     *           branch v2      eb3733d   eb3733d  1```

This shows the different packages in use for the current project. See the output of `dep status --help` for a full description of the status command.

## Updating an existing dependency within existing contraints.

1. `dep ensure -update <package>`
1. Inspect the changes with `git diff` (or similar).
1. Commit the changes with `git add -A vendor Gopkg.toml Gopkg.lock; git commit -m "Update <dependency>"`.

## Removing unused dependencies

1. Remove the imports and all usage from your code.
1. Remove any `[[constraint]]` rules from `Gopkg.toml`.
1. Run `dep ensure`.
1. Commit the changes with `git add -A vendor Gopkg.toml Gopkg.lock; git commit -m "Remove unused dependency <dep>"`.