{"id":21133408,"url":"https://github.com/purpleclay/go-overlay","last_synced_at":"2026-04-15T18:01:28.184Z","repository":{"id":214429414,"uuid":"734968101","full_name":"purpleclay/go-overlay","owner":"purpleclay","description":"Nix overlay for Go development. Pure, reproducible, auto-updated. 100+ Go Toolchains from 1.17. Go tools pinned to your toolchain. Build your Go applications with ease!","archived":false,"fork":false,"pushed_at":"2026-04-11T10:28:23.000Z","size":4615,"stargazers_count":21,"open_issues_count":7,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-11T11:28:11.935Z","etag":null,"topics":["go","golang","govulncheck","nix","nix-flakes","nix-overlay","tools"],"latest_commit_sha":null,"homepage":"","language":"Nix","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/purpleclay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-23T07:27:59.000Z","updated_at":"2026-04-11T10:28:28.000Z","dependencies_parsed_at":"2026-01-23T08:12:52.955Z","dependency_job_id":null,"html_url":"https://github.com/purpleclay/go-overlay","commit_stats":null,"previous_names":["purpleclay/go-overlay"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/purpleclay/go-overlay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleclay%2Fgo-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleclay%2Fgo-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleclay%2Fgo-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleclay%2Fgo-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/purpleclay","download_url":"https://codeload.github.com/purpleclay/go-overlay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleclay%2Fgo-overlay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31853279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["go","golang","govulncheck","nix","nix-flakes","nix-overlay","tools"],"created_at":"2024-11-20T06:08:26.867Z","updated_at":"2026-04-15T18:01:28.138Z","avatar_url":"https://github.com/purpleclay.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/purpleclay/go-overlay/raw/main/docs/static/go-overlay.png\" alt=\"go-overlay logo\" width=\"220px\" /\u003e\n  \u003ch1\u003ego-overlay\u003c/h1\u003e\n  \u003cp\u003eA complete Go development environment for Nix.\u003cbr\u003eToolchains, tools, and builders — pure, reproducible, and auto-updated.\u003c/p\u003e\n  \u003cimg alt=\"Nix\" src=\"https://img.shields.io/badge/Nix-5277C3?logo=nixos\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Go\" src=\"https://img.shields.io/badge/Go-00ADD8?logo=go\u0026logoColor=white\" /\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"MIT\" src=\"https://img.shields.io/badge/MIT-gray?logo=github\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/purpleclay/go-overlay/actions/workflows/go-update.yml\"\u003e\u003cimg alt=\"Go Update\" src=\"https://github.com/purpleclay/go-overlay/actions/workflows/go-update.yml/badge.svg\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n- **100+ Go versions** — from 1.17 to latest, including release candidates, \u003cu\u003eupdated within 4 hours\u003c/u\u003e of a new release on [go.dev](https://go.dev/dl/).\n- **No stale `vendorHash`** — dependencies are pinned per-module with NAR hashes. Change a dep, re-run `govendor`. No hash archaeology.\n- **Workspace support** — build multi-module `go.work` monorepos reproducibly. Neither `buildGoModule` nor gomod2nix can do this.\n- **Go tools pinned to your toolchain** — govulncheck, gopls, golangci-lint, and more, \u003cu\u003eupdated within 6 hours\u003c/u\u003e of release and version-locked to your selected Go version with a clear error if incompatible.\n- **Private modules** — standard Go authentication via `.netrc`, no custom infrastructure required.\n\n## Getting Started\n\n### Try Go without installing anything\n\n```bash\nnix run github:purpleclay/go-overlay -- version\n# go version go1.26.2 linux/amd64\n```\n\n### Create a new project\n\nThe template bootstraps a new project with a dev shell, builder, and drift detection pre-configured:\n\n```bash\nnix flake new -t github:purpleclay/go-overlay my-app\ncd my-app \u0026\u0026 nix develop\n```\n\n### Onboard an existing project\n\n#### 1. Add the flake input\n\nAdd go-overlay to your `flake.nix` inputs and apply the overlay:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    flake-utils.url = \"github:numtide/flake-utils\";\n    go-overlay.url = \"github:purpleclay/go-overlay\";\n  };\n\n  outputs = { nixpkgs, flake-utils, go-overlay, ... }:\n    flake-utils.lib.eachDefaultSystem (system:\n      let\n        pkgs = import nixpkgs {\n          inherit system;\n          overlays = [ go-overlay.overlays.default ];\n        };\n      in { ... }\n    );\n}\n```\n\n\u003e [!TIP]\n\u003e Not using flakes? See the [traditional Nix installation guide](docs/reference.md#traditional-nix-installation).\n\n#### 2. Add govendor to your dev shell\n\n`govendor` generates and maintains the dependency manifest used during builds:\n\n```nix\ndevShells.default = pkgs.mkShell {\n  buildInputs = [\n    go-overlay.packages.${system}.govendor\n  ];\n};\n```\n\n#### 3. Generate and commit the manifest\n\n```bash\ngovendor\n```\n\nThis creates a `govendor.toml` with NAR hashes for all dependencies. Commit it to your repository.\n\n\u003e [!IMPORTANT]\n\u003e Re-run `govendor` whenever you add, remove, or upgrade a dependency. Use `govendor --check` in CI to catch drift before it reaches production.\n\n#### 4. Build\n\nCreate a `default.nix` file to define your package:\n\n```nix\n{ pkgs, go }:\npkgs.buildGoApplication {\n  inherit go;\n  pname = \"my-app\";\n  version = \"0.1.0\";\n  src = ./.;\n  modules = ./govendor.toml;\n}\n```\n\nThen wire it into your `flake.nix` outputs:\n\n```nix\nlet\n  go = pkgs.go-bin.fromGoMod ./go.mod;\nin {\n  packages.default = pkgs.callPackage ./default.nix { inherit go; };\n}\n```\n\n\u003e [!TIP]\n\u003e `fromGoMod` auto-selects the Go version from your `go.mod`. For other version selection options, see the [reference guide](docs/reference.md#selecting-a-go-version).\n\nAnd then build it:\n\n```bash\nnix build\n```\n\nThat's it. No stale `vendorHash` to fix after every dependency change. 👋\n\n## Examples\n\nNot sure how to configure a specific feature? Each example is a self-contained, buildable project — find the pattern you need and use it as a starting point.\n\n| Example                                                      | Features                                               |\n| :----------------------------------------------------------- | :----------------------------------------------------- |\n| [hello-world](examples/hello-world/)                         | stdlib-only, no manifest                               |\n| [http-chi-server](examples/http-chi-server/)                 | External deps, `modules`                               |\n| [cobra-cli](examples/cobra-cli/)                             | `ldflags`, `subPackages`, `doCheck`, version injection |\n| [cross-compile](examples/cross-compile/)                     | `GOOS`, `GOARCH`, `CGO_ENABLED`                        |\n| [build-tags](examples/build-tags/)                           | `tags` parameter                                       |\n| [local-replaces](examples/local-replaces/)                   | Local replace directives, `localReplaces`              |\n| [oapi-codegen](examples/oapi-codegen/)                       | `tool` directive, `preBuild` code generation           |\n| [sqlc-codegen](examples/sqlc-codegen/)                       | `nativeBuildInputs`, `preBuild` code generation        |\n| [vendored](examples/vendored/)                               | Committed `vendor/` directory                          |\n| [go-workspace](examples/go-workspace/)                       | `buildGoWorkspace`, `go.work`, `subPackages`           |\n| [go-workspace-inferred](examples/go-workspace-inferred/)     | `buildGoWorkspace`, inferred `go.work`                 |\n| [go-workspace-vendored](examples/go-workspace-vendored/)     | `buildGoWorkspace`, committed `vendor/`                |\n| [wasm-build](examples/wasm-build/)                           | `mkVendorEnv` + `stdenv.mkDerivation`                  |\n| [nixpkgs-build-go-module](examples/nixpkgs-build-go-module/) | `buildGoModule.override` with go-overlay toolchain     |\n\nBuild or run any example directly:\n\n```bash\n# pattern: nix build .#example-\u003cname\u003e\nnix build .#example-cobra-cli\nnix run .#example-cobra-cli\n```\n\n## Go Tools\n\nEvery Go toolchain derivation includes version-locked tools — `gopls`, `golangci-lint`, `govulncheck`, `delve`, and more — pinned to your selected Go version and updated within 6 hours of a new release.\n\nAdd them all to your dev shell with a single attribute:\n\n```nix\nlet\n  go = pkgs.go-bin.fromGoMod ./go.mod;\nin {\n  devShells.default = pkgs.mkShell {\n    buildInputs = [\n      go.withDefaultTools\n    ];\n  };\n}\n```\n\nFor selecting specific tools or pinning versions, see the [Go Tools reference](docs/reference.md#go-tools).\n\n## Detecting Drift with Git Hooks\n\nUse [cachix/git-hooks.nix](https://github.com/cachix/git-hooks.nix) to check for manifest drift on commit:\n\n```nix\nlet\n  pre-commit-check = git-hooks.lib.${system}.run {\n    src = ./.;\n    hooks.govendor = {\n      enable = true;\n      name = \"govendor\";\n      entry = \"${go-overlay.packages.${system}.govendor}/bin/govendor --check\";\n      files = \"(^|/)go\\\\.(mod|work)$\";\n      pass_filenames = true;\n    };\n  };\nin {\n  devShells.default = pkgs.mkShell {\n    inherit (pre-commit-check) shellHook;\n    buildInputs = pre-commit-check.enabledPackages;\n  };\n}\n```\n\n## Private Go Modules\n\nPrivate modules require two things: bypassing the public proxy, and credentials to authenticate with the private host. Set `GOPRIVATE` to route around the proxy and `netrcFile` to provide credentials:\n\n\u003e [!TIP]\n\u003e `GOPRIVATE` implicitly sets `GONOPROXY` and `GONOSUMDB` — you only need to set all three explicitly if you require different values for each.\n\n```nix\n{ pkgs, go }:\npkgs.buildGoApplication {\n  inherit go;\n  pname = \"myapp\";\n  version = \"1.0.0\";\n  src = ./.;\n  modules = ./govendor.toml;\n  netrcFile = \"${builtins.getEnv \"HOME\"}/.netrc\";\n  GOPRIVATE = \"\u003cyour-private-host\u003e/*\";\n}\n```\n\n\u003e [!NOTE]\n\u003e `builtins.getEnv \"HOME\"` reads the host environment to locate `~/.netrc` — this is why `--impure` is required. The file contents are read at eval time and passed into the build sandbox. Credentials are not stored in the repo. If you prefer to keep a `.netrc` inside the source root, consider encrypting it with [git-crypt](https://github.com/AGWA/git-crypt) or [sops-nix](https://github.com/Mic92/sops-nix).\n\n```bash\nnix build --impure\n```\n\n\u003e [!CAUTION]\n\u003e The `.netrc` contents are embedded in the derivation, which is stored in the Nix store. The Nix store is world-readable by default.\n\n## Further Reading\n\n- [reference.md](docs/reference.md) — Full option tables for all builder functions, library functions, and traditional Nix installation.\n- [govendor-toml-v2.md](docs/govendor-toml-v2.md) — `govendor.toml` schema reference.\n- [migrating.md](docs/migrating.md) — Migration guides from gomod2nix and buildGoModule.\n\n---\n\n\u003csub\u003eThe go-overlay logo was generated using Google Gemini. The Go gopher was originally designed by \u003ca href=\"https://reneefrench.blogspot.com/\"\u003eRenee French\u003c/a\u003e and is licensed under \u003ca href=\"https://creativecommons.org/licenses/by/4.0/\"\u003eCC BY 4.0\u003c/a\u003e. The \u003ca href=\"https://github.com/NixOS/nixos-artwork\"\u003eNix snowflake\u003c/a\u003e is a trademark of the NixOS Foundation. This project is not affiliated with the Go project, the NixOS Foundation, or Google.\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpurpleclay%2Fgo-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpurpleclay%2Fgo-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpurpleclay%2Fgo-overlay/lists"}