Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Language Support
  • Go
  • Heroku Go Support

Heroku Go Support

English — 日本語に切り替える

Last updated January 26, 2022

Table of Contents

  • Supported Dependency/Vendor Managers
  • Go versions
  • Passing a symbol (and optional string) to the linker
  • Other build time behavior
  • Runtime behavior
  • Static Assets & Files
  • Default web process type
  • Add-ons
  • Vendor directory support
  • Vendoring additional main packages
  • Going further

This document describes the general behavior of Heroku as it relates to the recognition and execution of Go applications. For a more detailed explanation of how to deploy an application, see Getting Started with Go on Heroku.

Users who have previously set up applications to use the the community buildpack will want to run heroku buildpacks:clear for each of their Go applications. Pushes after that will use the current release of the Go buildpack, cached by the build system, speeding up deploys.

Supported Dependency/Vendor Managers

The currently supported dependency/vendor managers are:

  1. godep
  2. govendor
  3. gb
  4. dep (community supported*)

Activation

The Heroku Go buildpack is used when an application meets one of the following requirements:

  1. has a Godeps/Godeps.json file, identifying the application as being managed by godep;
  2. has a vendor/vendor.json file, identifying the application as being managed by govendor;
  3. has a src directory, which has sub directories, contains one or more .go files, identifying the application as being managed by gb.

When a deployed application is recognized as a Go application, Heroku responds with -----> Go app detected, like so:

$ git push heroku master
...
remote: -----> Go app detected
...

We do basic structural validation of the various metadata files (Godeps.json, vendor.json, etc) before attempting to use them. If there is an error it will be displayed like so:

$ git push heroku master
...
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Go app detected
remote: -----> Checking Godeps/Godeps.json file.
remote: parse error: Expected value before ',' at line 4, column 15
remote:  !     Bad Godeps/Godeps.json file
remote:
remote:  !     Push rejected, failed to compile Go app
...

Go versions

Heroku makes a number of different versions of the Go toolchain available. The currently supported versions listed here. Any version is available for use, but support is generally only provided for the latest current minor release of the last 2 major versions.

The major release identifier is used to represent the latest release in that series. Example: go1.9 will expand to the latest go 1.9 release that Heroku supports at the time the code was built, go1.9, go1.9.1, go1.9.2, etc.

If you need to select a specific minor revision (e.x. go1.8.7) for any reason you will need to hand edit the appropriate metadata file or set the $GOVERSION environment variable, depending on the dependency manager you use:

  1. godep
  2. govendor
  3. gb
  4. dep (community supported*)

In the rare case that you need to pin to the first release (go doesn’t have .0 releases) of a major version add a .0 to the version identifier. Example: go1.9.0 will pin an app’s go version to go1.9.

Passing a symbol (and optional string) to the linker

Heroku supports the Go linker’s ability (-X symbol value) to set the value of a string at link time. This can be done by setting $GO_LINKER_SYMBOL and $GO_LINKER_VALUE in the application’s config before pushing code. If $GO_LINKER_SYMBOL is set, but $GO_LINKER_VALUE isn’t set then $GO_LINKER_VALUE defaults to $SOURCE_VERSION.

This can be used to embed the commit SHA, or other build specific data directly into the compiled executable.

Other build time behavior

Various aspects of the build can be controlled via several application config vars. Below is a list of the vars that are not covered elsewhere in this doc and what they control:

  • CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS and CGO_LDFLAGS: These are the standard CGO flags as described here.
  • GOPROXY, GOPRIVATE, and GONOPROXY: These and the standard environment variables that configure use of module proxies as described here.
  • GOVERSION: Provides an override to the go version to use.
  • GO_INSTALL_PACKAGE_SPEC: Overrides the package spec passed to go install with this value. This is useful when you have a large repo, but only want to compile a sub section of it.
  • GO_INSTALL_TOOLS_IN_IMAGE: When set to true, installs the go tool chain into the slug at $HOME/.heroku/go, set’s $GOROOT=$HOME/.heroku/go and includes $GOROOT/bin in your $PATH. Normally the go tools are not installed in the slug. This increases the slug size by about 81MB.
  • GO_SETUP_GOPATH_IN_IMAGE: When set to true $GOPATH=$HOME is set and user code is placed in the appropriate location inside of the $GOPATH (e.g. $GOPATH/src/github.com/heroku/go-getting-started). When the dyno starts the working directory will be set to root of the user code. Normally the buildpack keeps user code in $HOME. This is most useful when used in conjunction with GO_INSTALL_TOOLS_IN_IMAGE=true so that there is a fully functioning go workspace and tool chain inside of the dyno.

Each of the above config vars need to be set on an application before pushing code and code must be pushed after these config vars are set for them to take effect.

Runtime behavior

Starting with go1.5 and newer, the buildpack does not set any Go runtime environment variables. You can set these environment variables on your application’s config and the application will be restarted with them in place. For go1.4 and older a default $GOMAXPROCS will be set, depending on the size of your dyno. This can be overridden by using heroku config:set to set a value for GOMAXPROCS.

The runtime environment does not have a copy of the go tool chain or the compiled package files (*.a) as the build pack does not copy them into the slug.

Static Assets & Files

Anything included in your git repository is available at runtime and can be served from the local filesystem using Go’s http.FileServer or framework equivalent. Tools like go-assets, go-bindata & statik are not required.

Default web process type

No default web process type is defined for Go applications. See one of the Go tutorials for information on setting up your Procfile.

Add-ons

No add-ons are provisioned by default. If you need a SQL database for your app, add one explicitly:

$ heroku addons:create heroku-postgresql

Vendor directory support

Vendor directory support is the default for go1.6 and can be disabled by runningheroku config:set GO15VENDOREXPERIMENT=0. For go1.5 set GO15VENDOREXPERIMENT=1 to activate. Earlier versions of Go do not support the vendor/ directory.

Builds use the contents of the vendor/ directory when compiling as if they are in your $GOPATH. Current versions of godep support the vendor directory using the same environment variables locally. However when using godep to vendor your code you will need to be careful specifying the package path(s) because ./... matches all packages, including those in vendor/. Heroku suggests putting individual main packages for executables inside of subdirectories of the cmd directory like detailed in this blog post.

You can find more information about the vendor experiment here and here.

Vendoring additional main packages

Various vendoring tools can save additional packages beyond those in your local project into your project’s vendor directory. This is useful when you want to include, compile and install additional main packages. A common usage is to include a package like migrate to manage database migrations.

Godep

To have godep save additional packages, those packages must be installed in your $GOPATH and included on the command line every time godep save is run like so: godep save ./cmd/... github.com/golang-migrate/migrate. The resulting changes to Godeps/Godeps.json and either vendor/ or Godeps/_workspace need to be committed.

On the next push Heroku will then install both ./cmd/... and github.com/golang-migrate/migrate.

govendor

govendor can fetch and save additional packages beyond those in your local project directly into your vendor/ directory like so: govendor fetch github.com/golang-migrate/migrate.

Additionally, the heroku build configuration section of vendor.json needs to have the additional packages added to the heroku.install array like so:

  ...
  "heroku" : {
    ...
    "install": [
      "./cmd/...",
      "github.com/golang-migrate/migrate"
    ]
  },
  ...

The changes to vendor/* need to be committed. On the next push Heroku will then install both ./cmd/... and github.com/golang-migrate/migrate.

Going further

The Heroku Go buildpack is open source. For a better technical understanding of how the buildpack works, check out the source code at github.com/heroku/heroku-buildpack-go.


* dep support is provided by the community. To obtain support for a dep based build problem please file an issue against the Heroku Go Buildpack.

Keep reading

  • Go

Feedback

Log in to submit feedback.

Using WebSockets on Heroku with Go OAuth2 with Heroku & Go

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences