Go Registry

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 n' paste snippets (with your namespace/repo pre-configured).

In the following examples:

Upload a Package

🚧

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

To upload, you need to generate a module first. While we expect the tooling in this area to improve over time, currently the process is a manual one and can be a little tricky.

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:

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

mkdir -p github.com/sirupsen/[email protected]
git clone [email protected]:sirupsen/logrus.git github.com/sirupsen/[email protected]
cd github.com/sirupsen/[email protected]
git checkout v1.4.2

Next (and finally) we need to clean up and pack the module. We only want to include folders with files in them, so we'll use find:

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

📘

Please see Russ Cox's Go Modules overview for full information on building your own 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.0.0.zip

📘

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 Website

Please see Upload a Package for details of how to upload via the Website UI.

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). We'll supplement these with more detailed guidance later but otherwise, just ask - we're here to help!

Download a Package

Setup

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.

📘

Cloudsmith Go repositories don't (currently) proxy upstream sources, and so can only serve modules which have been explicitly pushed. If you require the ability to pull modules from public/upstream sources then you must use Go 1.13 or greater to avail of the fallback repository support.

Public Repositories

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

Linux / Mac

export GOPROXY=https://dl.cloudsmith.io/public/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

Windows (cmd)

set GOPROXY=https://dl.cloudsmith.io/public/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

Windows (Powershell)

$env:GOPROXY=https://dl.cloudsmith.io/public/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

Private Repositories

📘

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication.

The setup method will differ depending on what authentication type you choose to use.

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and 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

export GOPROXY=https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

export GOPROXY=https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

export GOPROXY=https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

export GOPROXY=https://token:[email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

Windows (cmd)

set GOPROXY=https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

set GOPROXY=https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

set GOPROXY=https://USERNAME:API [email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

set GOPROXY=https://token:[email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

Windows (Powershell)

$env:GOPROXY=https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

$env:GOPROXY=https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

$env:GOPROXY=https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

$env:GOPROXY=https://token:[email protected]/basic/OWNER/REPOSITORY/go/,https://proxy.golang.org,direct

📘

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.

It is recommended to use the environment variable GONOSUMDB=https://cloudsmith.io/ to skip verification for your Cloudsmith repositories, or alternatively (but less secure), use the environment variable GOSUMDB=off to turn off the verification completely.

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

Supported
Please see our Security Scanning documentation for further information.

Upstream Proxying / Caching

Not Supported

Troubleshooting

Please see the Troubleshooting page for further help and information.