Skip to content

Go Modules Integration

OrbitRepos acts as a high-performance Go Module Proxy, implementing the GOPROXY protocol. It allows you to host private Go modules and cache public ones from proxy.golang.org, providing a reliable and reproducible build environment for your Go projects.

Overview

OrbitRepos simplifies Go dependency management by providing:

  • Hosted Repositories: Private storage for your internal Go modules.
  • Proxy Repositories: A caching proxy for public Go modules.
  • Group Repositories: A single GOPROXY endpoint for both internal and external modules.

The Go handler implements the standard @v API and is accessible at /go/{repoName}/.

Prerequisites

Before you begin, ensure you have:

  • OrbitRepos instance running (see the Quick Start).
  • Go 1.13+ installed on your system.
  • Basic understanding of Go modules (go.mod).
  • An API Token or user credentials if your repository requires authentication.

Create a Repository

Create a Go repository via the OrbitRepos Web UI or API:

  1. Navigate to Repositories and click Create Repository.
  2. Select Go as the format.
  3. Choose a Type (hosted, proxy, or group).
  4. Enter a Name (e.g., go-modules).
  5. If creating a proxy, set the Remote URL to https://proxy.golang.org.
  6. Click Create.

Push / Publish Artifacts

Unlike other package managers, Go modules are typically "published" by making them available to the proxy. OrbitRepos supports direct upload of module versions.

Uploading a Module

You can upload a zipped module version using curl or a management script:

# Example: Uploading my-module v1.0.0
curl -u admin:admin --upload-file my-module-v1.0.0.zip \
  http://localhost:8080/go/go-internal/github.com/myuser/my-module/@v/v1.0.0.zip

Module Versioning

Ensure you follow semantic versioning. OrbitRepos requires the .info, .mod, and .zip files for a complete version, which it can often generate or extract during upload.

Pull / Install Artifacts

To use OrbitRepos as your Go proxy, set the GOPROXY environment variable.

Configure GOPROXY

Set the environment variable in your shell or CI/CD environment:

export GOPROXY=http://localhost:8080/go/go-modules/,direct

The ,direct suffix tells Go to fall back to direct version control access if the module is not found in the proxy.

Authentication

If your OrbitRepos instance requires authentication, you can include credentials in the URL:

export GOPROXY=http://admin:your-api-token@localhost:8080/go/go-modules/,direct

Alternatively, use the .netrc file:

machine localhost
  login admin
  password your-api-token

Install a module

Once GOPROXY is set, go get and go build will automatically use OrbitRepos:

go get github.com/myuser/my-module@v1.0.0

Proxy Setup

A Go proxy repository caches public modules to ensure your builds remain reproducible even if the original repository is deleted or the public proxy is down.

  1. Create a proxy repository named go-proxy.
  2. Set the Remote URL to https://proxy.golang.org.
  3. Set GOPROXY=http://localhost:8080/go/go-proxy/,direct.

OrbitRepos will cache modules locally upon the first request.

Private Modules

Use the GONOPROXY or GOPRIVATE environment variables for modules that should never be fetched via a proxy (e.g., internal Git servers not yet integrated into OrbitRepos).

Troubleshooting

Module Not Found (404)

Verify the module path and version. Ensure the repository name in the GOPROXY URL matches the one created in OrbitRepos.

Authentication Errors

If using a .netrc file, ensure the permissions are correct (600) and the hostname matches exactly. If using credentials in the URL, ensure special characters are URL-encoded.

Checksum Failures

Go verifies module integrity using GOSUMDB. If you are hosting private modules, you may need to set GONOSUMDB for your private module paths: export GONOSUMDB=github.com/myuser/*

Timeout during go get

Large modules or slow upstream connections might cause timeouts. Ensure OrbitRepos has sufficient resources and check the ORBITREPO_STORAGE_TYPE performance.