{"id":13478887,"url":"https://github.com/heroku/heroku-buildpack-go","last_synced_at":"2026-04-10T00:09:27.304Z","repository":{"id":1781825,"uuid":"2705156","full_name":"heroku/heroku-buildpack-go","owner":"heroku","description":"Heroku's classic buildpack for Go applications.","archived":false,"fork":false,"pushed_at":"2025-03-04T21:17:28.000Z","size":21936,"stargazers_count":794,"open_issues_count":19,"forks_count":511,"subscribers_count":92,"default_branch":"main","last_synced_at":"2025-03-04T21:32:38.451Z","etag":null,"topics":["buildpack","go","golang","heroku","heroku-languages"],"latest_commit_sha":null,"homepage":"https://devcenter.heroku.com/categories/go-support","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heroku.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-11-03T21:03:58.000Z","updated_at":"2025-03-04T21:16:05.000Z","dependencies_parsed_at":"2024-06-18T18:14:41.855Z","dependency_job_id":"ea675264-b2fc-4c08-ac39-118f2fec25dd","html_url":"https://github.com/heroku/heroku-buildpack-go","commit_stats":{"total_commits":763,"total_committers":80,"mean_commits":9.5375,"dds":0.692005242463958,"last_synced_commit":"ca29e177f1fdc8fffaaeb875bfab0f1ff2fd858c"},"previous_names":["kr/heroku-buildpack-go"],"tags_count":184,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fheroku-buildpack-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fheroku-buildpack-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fheroku-buildpack-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fheroku-buildpack-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heroku","download_url":"https://codeload.github.com/heroku/heroku-buildpack-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245809770,"owners_count":20676048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buildpack","go","golang","heroku","heroku-languages"],"created_at":"2024-07-31T16:02:05.208Z","updated_at":"2025-12-17T10:25:07.843Z","avatar_url":"https://github.com/heroku.png","language":"Shell","funding_links":[],"categories":["Shell","[Heroku Buildpacks](https://devcenter.heroku.com/)"],"sub_categories":["Provides buildpacks for:"],"readme":"# Heroku Buildpack for Go\n\n[![CI](https://github.com/heroku/heroku-buildpack-go/actions/workflows/ci.yml/badge.svg)](https://github.com/heroku/heroku-buildpack-go/actions/workflows/ci.yml)\n\n![Heroku Buildpack for Go](https://raw.githubusercontent.com/heroku/buildpacks/refs/heads/main/assets/images/buildpack-banner-go.png)\n\nThis is the official [Heroku buildpack][buildpack] for [Go][go].\n\n## Getting Started\n\nFollow the guide at\n\u003chttps://devcenter.heroku.com/articles/getting-started-with-go\u003e\n\nThere's also a hello world sample app at\n\u003chttps://github.com/heroku/go-getting-started\u003e\n\n## Example\n\n```console\n$ ls -A1\n.git\nvendor\nProcfile\nweb.go\n\n$ heroku create\nCreating polar-waters-4785...\n...\n\n$ git push heroku main\n...\n-----\u003e Go app detected\n-----\u003e Installing go1.11... done\n-----\u003e Running: go install -tags heroku .\n-----\u003e Discovering process types\n       Procfile declares types -\u003e web\n\n-----\u003e Compressing... done, 1.6MB\n-----\u003e Launching... done, v4\n       https://polar-waters-4785.herokuapp.com/ deployed to Heroku\n```\n\nThis buildpack will detect your repository as Go if you are using either:\n\n- [go modules][gomodules]\n- [dep][dep]\n- [govendor][govendor]\n- [glide][glide]\n- [GB][gb]\n- [Godep][godep]\n\nThis buildpack adds a `heroku` [build constraint][build-constraint], to enable\nheroku-specific code. See the [App Engine build constraints\narticle][app-engine-build-constraints] for more info.\n\n## Go Module Specifics\n\nWhen using go modules, this buildpack will search the code base for `main`\npackages, ignoring any in `vendor/`, and will automatically compile those\npackages. If this isn't what you want you can specify specific package spec(s)\nvia the `go.mod` file's `// +heroku install` directive (see below).\n\nThe `go.mod` file allows for arbitrary comments. This buildpack utilizes [build\nconstraint](https://golang.org/pkg/go/build/#hdr-Build_Constraints) style\ncomments to track Heroku build specific configuration which is encoded in the\nfollowing way:\n\n- `// +heroku goVersion \u003cversion\u003e`: the major version of go you would like\n  Heroku to use when compiling your code. If not specified this defaults to the\n  buildpack's [DefaultVersion]. Specifying a version \u003c go1.11 will cause a build\n  error because modules are not supported by older versions of go.\n\n  Example: `// +heroku goVersion go1.11`\n\n- `// +heroku install \u003cpackagespec\u003e[ \u003cpackagespec\u003e]`: a space seperated list of\n  the packages you want to install. If not specified, the buildpack defaults to\n  detecting the `main` packages in the code base. Generally speaking this should\n  be sufficient for most users. If this isn't what you want you can instruct the\n  buildpack to only build certain packages via this option. Other common choices\n  are: `./cmd/...` (all packages and sub packages in the `cmd` directory) and\n  `./...` (all packages and sub packages of the current directory). The exact\n  choice depends on the layout of your repository though.\n\n  Example: `// +heroku install ./cmd/... ./special`\n\nIf a top level `vendor` directory exists and the `go.sum` file has a size\ngreater than zero, `go install` is invoked with `-mod=vendor`, causing the build\nto skip downloading and checking of dependencies. This results in only the\ndependencies from the top level `vendor` directory being used.\n\n### Pre/Post Compile Hooks\n\nIf the file `bin/go-pre-compile` or `bin/go-post-compile` exists and is\nexecutable then it will be executed either before compilation (go-pre-compile)\nof the repo, or after compilation (go-post-compile).\n\nThese hooks can be used to install additional tools, such as `github.com/golang-migrate/migrate`:\n\n```bash\n#!/bin/bash\nset -e\n\ngo install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.15.1\n```\n\nBecause the buildpack installs compiled executables to `bin`, the\n`go-post-compile` hook can be written in go if it's installed by the specified\n`\u003cpackagespec\u003e` (see above).\n\nExample:\n\n```console\n$ cat go.mod\n// +heroku install ./cmd/...\n$ ls -F cmd\nclient/ go-post-compile/ server/\n```\n\n## dep specifics\n\nThe `Gopkg.toml` file allows for arbitrary, tool specific fields. This buildpack\nutilizes this feature to track build specific configuration which are encoded in\nthe following way:\n\n- `metadata.heroku['root-package']` (String): the root package name of the\n  packages you are pushing to Heroku.You can find this locally with `go list -e\n  .`. There is no default for this and it must be specified.\n\n- `metadata.heroku['go-version']` (String): the major version of go you would\n  like Heroku to use when compiling your code. If not specified this defaults to\n  the buildpack's [DefaultVersion]. Exact versions (ex `go1.9.4`) can also be\n  specified if needed, but is not generally recommended. Since Go doesn't\n  release `.0` versions, specifying a `.0` version will pin your code to the\n  initial release of the given major version (ex `go1.10.0` == `go1.10` w/o auto\n  updating to `go1.10.1` when it becomes available).\n\n- `metadata.heroku['install']` (Array of Strings): a list of the packages you\n  want to install. If not specified, this defaults to `[\".\"]`. Other common\n  choices are: `[\"./cmd/...\"]` (all packages and sub packages in the `cmd`\n  directory) and `[\"./...\"]` (all packages and sub packages of the current\n  directory). The exact choice depends on the layout of your repository though.\n  Please note that `./...`, for versions of go \u003c 1.9, includes any packages in\n  your `vendor` directory.\n\n- `metadata.heroku['ensure']` (String): if this is set to `false` then `dep\n  ensure` is not run.\n\n- `metadata.heroku['additional-tools']` (Array of Strings): a list of additional\n  tools that the buildpack is aware of that you want it to install. If the tool\n  has multiple versions an optional `@\u003cversion\u003e` suffix can be specified to\n  select that specific version of the tool. Otherwise the buildpack's default\n  version is chosen. Currently the only supported tool is\n  `github.com/golang-migrate/migrate` at `v3.4.0` (also the default version).\n\n```toml\n[metadata.heroku]\n  root-package = \"github.com/heroku/fixture\"\n  go-version = \"go1.8.3\"\n  install = [ \"./cmd/...\", \"./foo\" ]\n  ensure = \"false\"\n  additional-tools = [\"github.com/golang-migrate/migrate\"]\n...\n```\n\n## govendor specifics\n\nThe [vendor.json][vendor.json] spec that govendor follows for its metadata\nfile allows for arbitrary, tool specific fields. This buildpack uses this\nfeature to track build specific bits. These bits are encoded in the following\ntop level json keys:\n\n- `rootPath` (String): the root package name of the packages you are pushing to\n  Heroku. You can find this locally with `go list -e .`. There is no default for\n  this and it must be specified. Recent versions of govendor automatically fill\n  in this field for you. You can re-run `govendor init` after upgrading to have\n  this field filled in automatically, or it will be filled the next time you use\n   govendor to modify a dependency.\n\n- `heroku.goVersion` (String): the major version of go you would like Heroku to\n  use when compiling your code. If not specified this defaults to the\n  buildpack's [DefaultVersion]. Exact versions (ex `go1.9.4`) can also be\n  specified if needed, but is not generally recommended. Since Go doesn't\n  release `.0` versions, specifying a `.0` version will pin your code to the\n  initial release of the given major version (ex `go1.10.0` == `go1.10` w/o auto\n  updating to `go1.10.1` when it becomes available).\n\n- `heroku.install` (Array of Strings): a list of the packages you want to install.\n  If not specified, this defaults to `[\".\"]`. Other common choices are:\n  `[\"./cmd/...\"]` (all packages and sub packages in the `cmd` directory) and\n  `[\"./...\"]` (all packages and sub packages of the current directory). The exact\n   choice depends on the layout of your repository though. Please note that `./...`\n   includes any packages in your `vendor` directory.\n\n- `heroku.additionalTools` (Array of Strings): a list of additional tools that\n  the buildpack is aware of that you want it to install. If the tool has\n  multiple versions an optional `@\u003cversion\u003e` suffix can be specified to select\n  that specific version of the tool. Otherwise the buildpack's default version\n  is chosen. Currently the only supported tool is `github.com/golang-migrate/migrate` at\n  `v3.4.0` (also the default version).\n\nExample with everything, for a project using `go1.9`, located at\n`$GOPATH/src/github.com/heroku/go-getting-started` and requiring a single package\nspec of `./...` to install.\n\n```json\n{\n    ...\n    \"rootPath\": \"github.com/heroku/go-getting-started\",\n    \"heroku\": {\n        \"install\" : [ \"./...\" ],\n        \"goVersion\": \"go1.9\"\n         },\n    ...\n}\n```\n\nA tool like [jq] or a text editor can be used to inject these variables into\n`vendor/vendor.json`.\n\n## glide specifics\n\nThe `glide.yaml` and `glide.lock` files do not allow for arbitrary metadata, so\nthe buildpack relies solely on the glide command and environment variables to\ncontrol the build process.\n\nThe base package name is determined by running `glide name`.\n\nThe Go version used to compile code defaults to the buildpack's\n[DefaultVersion]. This can be overridden by the `$GOVERSION` environment\nvariable. Setting `$GOVERSION` to a major version will result in the buildpack\nusing the latest released minor version in that series. Setting `$GOVERSION` to\na specific minor Go version will pin Go to that version. Since Go doesn't\nrelease `.0` versions, specifying a `.0` version will pin your code to the\ninitial release of the given major version (ex `go1.10.0` == `go1.10` w/o auto\nupdating to `go1.10.1` when it becomes available).\n\nExamples:\n\n```console\nheroku config:set GOVERSION=go1.9   # Will use go1.9.X, Where X is that latest minor release in the 1.9 series\nheroku config:set GOVERSION=go1.7.5 # Pins to go1.7.5\n```\n\n`glide install` will be run to ensure that all dependencies are properly\ninstalled. If you need the buildpack to skip the `glide install` you can set\n`$GLIDE_SKIP_INSTALL` to `true`. Example:\n\n```console\nheroku config:set GLIDE_SKIP_INSTALL=true\ngit push heroku main\n```\n\nInstallation defaults to `.`. This can be overridden by setting the\n`$GO_INSTALL_PACKAGE_SPEC` environment variable to the package spec you want the\ngo tool chain to install. Example:\n\n```console\nheroku config:set GO_INSTALL_PACKAGE_SPEC=./...\ngit push heroku main\n```\n\n## Usage with other vendoring systems\n\nIf your vendor system of choice is not listed here or your project only uses\npackages in the standard library, create `vendor/vendor.json` with the\nfollowing contents, adjusted as needed for your project's root path.\n\n```json\n{\n    \"comment\": \"For other heroku options see: https://devcenter.heroku.com/articles/go-support\",\n    \"rootPath\": \"github.com/yourOrg/yourRepo\",\n    \"heroku\": {\n        \"sync\": false\n    }\n}\n```\n\n## Default Procfile\n\nIf there is no Procfile in the base directory of the code being built and the\nbuildpack can figure out the name of the base package (also known as the\nmodule), then a default Procfile is created that includes a `web` process type\nthat runs the resulting executable from compiling the base package.\n\nFor example, if the package name was `github.com/heroku/example`, this buildpack\nwould create a Procfile that looks like this:\n\n```sh\n$ cat Procfile\nweb: example\n```\n\nThis is useful when the base package is also the only main package to build.\n\nIf you have adopted the `cmd/\u003cexecutable name\u003e` structure this won't work and\nyou will need to create a [Procfile].\n\nNote: This buildpack should be able to figure out the name of the base package\nin all cases, except when gb is being used.\n\n## Private Git Repos\n\nThe buildpack installs a custom git credential handler. Any tool that shells out to git (most do) should be able to transparently use this feature. Note: It has only been tested with Github repos over https using personal access tokens.\n\nThe custom git credential handler searches the application's config vars for vars that follow the following pattern: `GO_GIT_CRED__\u003cPROTOCOL\u003e__\u003cHOSTNAME\u003e`. Any periods (`.`) in the `HOSTNAME` must be replaces with double underscores (`__`).\n\nThe value of a matching var will be used as the username. If the value contains a \":\", the value will be split on the \":\" and the left side will be used as the username and the right side used as the password. When no password is present, `x-oauth-basic` is used.\n\nThe following example will cause git to use the `FakePersonalAccessTokenHere` as the username when authenticating to `github.com` via `https`:\n\n```console\nheroku config:set GO_GIT_CRED__HTTPS__GITHUB__COM=FakePersonalAccessTokenHere\n```\n\n## Hacking on this Buildpack\n\nTo change this buildpack, fork it on GitHub \u0026 push changes to your fork. Ensure\nthat tests have been added to `test/run.sh` and any corresponding fixtures to\n`test/fixtures/\u003cfixture name\u003e`.\n\n### Tests\n\n[Make], [jq] \u0026 [docker] are required to run tests.\n\n```console\nmake test\n```\n\nRun a specific test in `test/run.sh`:\n\n```console\nmake BASH_COMMAND='test/run.sh -- testGBVendor' test\n```\n\n### Compiling a fixture locally\n\n[Make] \u0026 [docker] are required to compile a fixture.\n\n```console\nmake FIXTURE=\u003cfixture name\u003e compile\n```\n\nYou will then be dropped into a bash prompt in the container that the fixture\nwas compiled in.\n\n## Using with cgo\n\nThe buildpack supports building with C dependencies via [cgo][cgo]. You can set\nconfig vars to specify CGO flags to specify paths for vendored dependencies. The\nliteral text of `${build_dir}` will be replaced with the directory the build is\nhappening in. For example, if you added C headers to an `includes/` directory,\nadd the following config to your app: `heroku config:set CGO_CFLAGS='-I${\nbuild_dir}/includes'`. Note the usage of `''` to ensure they are not converted to\nlocal environment variables.\n\n## Using a development version of Go\n\nThe buildpack can install and use any specific commit of the Go compiler when\nthe specified go version is `devel-\u003cshort sha\u003e`. The version can be set either\nvia the appropriate vendoring tools config file or via the `$GOVERSION`\nenvironment variable. The specific sha is downloaded from Github w/o git\nhistory. Builds may fail if GitHub is down, but the compiled go version is\ncached.\n\nWhen this is used the buildpack also downloads and installs the buildpack's\ncurrent default Go version for use in bootstrapping the compiler.\n\nBuild tests are NOT RUN. Go compilation failures will fail a build.\n\nNo official support is provided for unreleased versions of Go.\n\n## Passing a symbol (and optional string) to the linker\n\nThis buildpack supports the go [linker's][go-linker] ability (`-X symbol value`)\nto set the value of a string at link time. This can be done by setting\n`GO_LINKER_SYMBOL` and `GO_LINKER_VALUE` in the application's config before\npushing code. If `GO_LINKER_SYMBOL` is set, but `GO_LINKER_VALUE` isn't set then\n`GO_LINKER_VALUE` defaults to [`$SOURCE_VERSION`][source-version].\n\nThis can be used to embed the commit sha, or other build specific data directly\ninto the compiled executable.\n\n## Testpack\n\nThis buildpack supports the [testpack] API used by [Heroku CI][herokuci].\n\n### Golanglint-ci\n\nIf the source code contains a golanglint-ci configuration file in the root of\nthe source code (one of `/.golangci.yml`, `/.golangci.toml`, or\n`/.golangci.json`) then golanci-lint is run at the start of the test phase.\n\nUse one of those configuration files to configure the golanglint-ci run.\n\n[app-engine-build-constraints]: http://blog.golang.org/2013/01/the-app-engine-sdk-and-workspaces-gopath.html\n[build-constraint]: http://golang.org/pkg/go/build/\n[buildpack]: http://devcenter.heroku.com/articles/buildpacks\n[cgo]: http://golang.org/cmd/cgo/\n[curl]: https://curl.haxx.se/\n[DefaultVersion]: https://github.com/heroku/heroku-buildpack-go/blob/main/data.json#L4\n[dep]: https://github.com/golang/dep\n[docker]: https://www.docker.com/\n[gb]: https://getgb.io/\n[glide]: https://github.com/Masterminds/glide\n[go-linker]: https://golang.org/cmd/ld/\n[go]: http://golang.org/\n[godep]: https://github.com/tools/godep\n[gomodules]: https://github.com/golang/go/wiki/Modules\n[gopgsqldriver]: https://github.com/jbarham/gopgsqldriver\n[govendor]: https://github.com/kardianos/govendor\n[herokuci]: https://devcenter.heroku.com/articles/heroku-ci\n[jq]: https://github.com/stedolan/jq\n[LastPassCLI]: https://github.com/lastpass/lastpass-cli\n[make]: https://www.gnu.org/software/make/\n[Procfile]: https://devcenter.heroku.com/articles/procfile\n[quickstart]: http://mmcgrana.github.com/2012/09/getting-started-with-go-on-heroku.html\n[s3cmd]: https://s3tools.org/s3cmd\n[shasum]: https://ss64.com/osx/shasum.html\n[source-version]: https://devcenter.heroku.com/articles/buildpack-api#bin-compile\n[testpack]: https://devcenter.heroku.com/articles/testpack-api\n[toolbelt]: https://devcenter.heroku.com/articles/heroku-cli\n[vendor.json]: https://github.com/kardianos/vendor-spec\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheroku%2Fheroku-buildpack-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheroku%2Fheroku-buildpack-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheroku%2Fheroku-buildpack-go/lists"}