Go Registry

Cloudsmith provides public & private registries for Go.

Go, also known as Golang, is an open source programming language designed at Google.

For more information on Go, please see:

• Go: The official website for Go language
• Go Packages: Officially supported Go packages
• GoDoc: Documentation/search for Community Go packages

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy and paste snippets (with your namespace/repo/rsa-key pre-configured).

In the following examples:

Upload a Package

Note

Raw GO binaries are not supported and need to be uploaded as a RAW package format instead.

To upload, you need to generate a go module first. You can build a module with standard command-line tooling like zip and git. To illustrate the process we'll use logrus as an example:

1. First, we'll create the correct directory structure and check out the version of logrus we want to pack (v1.4.2):

mkdir -p github.com/sirupsen/logrus@v1.4.2
git clone git@github.com:sirupsen/logrus.git github.com/sirupsen/logrus@v1.4.2
cd github.com/sirupsen/logrus@v1.4.2
git checkout v1.4.2

2. Finally, clean up and pack the module. Use find to include only folders with files in them:

rm -rf .git/
cd ../../../
find -type f | while read f; do zip v1.4.2.zip "$f"; done

Now, we have a go module ready to be uploaded to a Cloudsmith repository.

Note

For a full overview on building your own modules, please refer to Russ Cox's Go Modules.

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload a Go module via the Cloudsmith CLI is:

cloudsmith push go OWNER/REPOSITORY PACKAGE_NAME.zip

Example:

cloudsmith push go org/repo v1.4.2.zip

Note

Older Go projects may not be in the Go Modules format, and you may experience an error when pushing these to Cloudsmith. You can add module support using go mod init and go mod tidy, then commit the new go.mod and go.sum files and add a new tag.

Upload via Cloudsmith web app

Please see Upload a Package for details of how to upload via the Cloudsmith web app.

Example Project

For examples of what your project should look like for packaging and publishing/uploading, please have a look at our examples repository (on GitHub).

Download a Package

Setup

Configure a new Upstream

Note

Go upstreams are still in Early Access. Contact us to enable it for your organization.

Cloudsmith supports https://proxy.golang.org as an upstream. This allows you to proxy and cache modules not yet in your repository through Cloudsmith for your Golang projects.

To enable it for your repository, browse to your repository overview page and click in the Upstreams tab. Then, click on + Add Upstream Proxy and then choose the Go format Upstream.

In the Upstream creation menu, define a name your Upstream and in the Proxy URL field insert https://proxy.golang.org. Click on + Create Upstream Proxy and the upstream shoud become immediately available.

Before you can install modules from your Cloudsmith repository, you'll need to configure your environment for access. The configuration is defined using the GOPROXY environment variable as explained below.

Public Repositories

To define the GOPROXY environment variable for a public Cloudsmith repository:

Warning

Cloudsmith provides a dedicated endpoint for Go artifacts: https://golang.cloudsmith.io. This endpoint supports native Golang Upstreams so you can access modules from https://proxy.golang.org.

While the legacy endpoint (https://dl.cloudsmith.io) is still maintained, we recommend to use the new one.

Note

GOPROXY allows the concatenation of multiple servers separated by commas. For example, for GOPROXY=https://dl.cloudsmith.io/public/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct, all requests not satisfied by the first server will fallback the the next one (https://proxy.golang.org).

Linux / Mac

export GOPROXY=https://golang.cloudsmith.io/OWNER/REPOSITORY/

Windows (cmd)

set GOPROXY=https://golang.cloudsmith.io/OWNER/REPOSITORY/

Windows (Powershell)

$env:GOPROXY=https://golang.cloudsmith.io/OWNER/REPOSITORY/

Private Repositories

Private Cloudsmith repositories require authentication. GOPROXY protocol only supports authentication via HTTP Basic Authentication: <USERNAME>/<PASSWORD>. It you want to authenticate via Entitlement Token, use the literal string token in the user field: token:<TOKEN>.

Secrets management

Entitlement Tokens, User Credentials, and API-Keys should be treated as secrets. You should ensure that you do not commit them in configurations files along with source code, or expose them in any logs.

To define the GOPROXY environment variable for a private Cloudsmith repository:

Linux / Mac

# HTTP Basic Auth (with Entitlement Token)
export GOPROXY=https://token:TOKEN@golang.cloudsmith.io/OWNER/REPOSITORY/

# HTTP Basic Auth (API-Key)
export GOPROXY=https://USERNAME:API-KEY@golang.cloudsmith.io/OWNER/REPOSITORY/

Windows (cmd)

# HTTP Basic Auth (with Entitlement Token)
set GOPROXY=https://token:TOKEN@golang.cloudsmith.io/OWNER/REPOSITORY/

# HTTP Basic Auth (API-Key)
set GOPROXY=https://USERNAME:API-KEY@golang.cloudsmith.io/OWNER/REPOSITORY/

Windows (Powershell)

# HTTP Basic Auth (with Entitlement Token)
$env:GOPROXY=https://token:TOKEN@golang.cloudsmith.io/OWNER/REPOSITORY/

# HTTP Basic Auth (API-Key)
$env:GOPROXY=https://USERNAME:API-KEY@golang.cloudsmith.io/OWNER/REPOSITORY/

About Go modules authentication

The Go sumdb cannot record the hash value of a private repository and this will cause the local Go command to fail the verification after downloading. You can see more details running the go mod download with the -x option.

It is recommended to use the environment variable GONOSUMDB and set its value to cloudsmith.io. This will skip verification for modules in your Cloudsmith repositories with a module name beginning with cloudsmith.io. Verification is performed against the global checksum database sum.golang.org (this service provides an auditable checksum database service used by the go command to authenticate modules).

GONOSUMDB should be a list of module path prefixes, like for example: GONOSUMDB=demo-docs/awesome-repo,cloudsmith-test/acme2.

While verifying the checksum of downloaded go modules is a critical step, there's general agreement against having separate checksum databases (for example, having a Cloudsmith checksum database). See for example: https://github.com/golang/go/issues/44936 and https://github.com/gomods/athens/issues/1572.

Installing a Package

You can install the latest version of a package with:

go get PACKAGE_NAME

Or install a specific version of a package with:

go get PACKAGE_NAME@PACKAGE_VERSION

Security Scanning

Cloudsmith supports security scanning for Go modules. Please see our Security Scanning documentation for further information about this capability.

Troubleshooting

Please see the Troubleshooting page for further help and information.