Manage Go modules

This page explains how to manage packaged Go modules stored in Artifact Registry.

Before you begin

1. If the target repository does not exist, create a new repository. Choose Go as the repository format.
2. Verify that you have the required permissions for the repository.
3. (Optional) Configure defaults for gcloud commands.
4. Install Go 1.15 or later.

5. Install the package-go-module gcloud CLI add-on:

   gcloud components install package-go-module

6. Configure Go to authenticate with Artifact Registry.

Required Roles

To get the permissions that you need to manage modules, ask your administrator to grant you the following IAM roles on the repository:

• View modules: Artifact Registry Reader (roles/artifactregistry.reader)
• Download or install modules: Artifact Registry Reader (roles/artifactregistry.reader)
• Add modules to a repository: Artifact Registry Writer (roles/artifactregistry.writer)
• Delete modules: Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Upload a module

Repository modes: standard

To package and upload a module to your repository run the following command:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

Replace the following:

• PROJECT with your Google Cloud project ID.
• REPOSITORY with the name of the repository where the package is stored.
• LOCATION with the regional or multi-regional location of the repository.
• MODULE_PATH with the module path. For example: example.com/foo See the Go Modules Reference for more information.
• VERSION with the semantic version of the module in the form vX.Y.Z where X is the major version, Y is the minor version, and Z is the patch version.
• SOURCE_LOCATION with the path to the root directory of your Go module. If you omit the --source flag, the default is the current directory.

The module is uploaded to Artifact Registry.

For more information on creating Go modules, see this tutorial.

Upload a new module version

Repository modes: standard

To upload a new version of your module to the default project, repository and location when the default values are configured, run the following command with the new version number:

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

Replace VERSION with the version of your updated module. For example, to upload version 0.1.1 of a module with the path example.com/foo, run the following command:

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v0.1.1 \
      --source=SOURCE_LOCATION

To mark a module as a pre-release version, add a dash after the VERSION and append your module's pre-release identifiers:

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION-PRE_RELEASE_IDENTIFIERS \
      --source=SOURCE_LOCATION

Replace PRE_RELEASE_IDENTIFIERS with dot separated ASCII alphanumeric characters and hyphens. For example, to upload a pre-release of a module with the path example.com/foo module identified by alpha.x.12m.5, run the following command:

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v1.0.0-alpha.x.12m.5 \
      --source=SOURCE_LOCATION

Upload a new major version

Repository modes: standard

Major versions are not backwards compatible with previous versions. To prevent users from importing a breaking change, major versions after v1 must have different module paths than previous versions. Starting with v2, the major version is added to the end of the module path.

For example, the module path for v2.0.0 of example.com/foo would be example.com/foo/v2.

The recommended best practice is to develop major versions after v1 in separate directories named after their major version suffix.

To upload a new major version 2.0.0 of a module with the path example.com/foo to the default project, repository, and location when the default values are configured:

  gcloud artifacts go upload --module-path=example.com/foo/v2 --version=v2.0.0

List modules

Repository modes: standard

Run the following command to inspect an uploaded Go module in the default project, repository, and location when the default values are configured:

  gcloud artifacts packages list

The output will resemble the following:

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

View module version details

Repository modes: standard

Run the following command to view the versions of a module in the default project, repository, and location when the default values are configured:

  gcloud artifacts versions list --package=MODULE_PATH

The output will resemble the following:

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

Use a module as a dependency

Repository modes: standard

To import modules stored in Artifact Registry, you need to instruct Go to look for dependencies from Artifact Registry and bypass the checksum database. Follow the instructions to set up authentication and the Go environment in Set up authentication for Go.

1. If you are using short-lived credentials for authenticating to Artifact Registry, you will need to refresh your OAuth token by running the following command:

     GOPROXY=proxy.golang.org \
     go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@latest refresh
   

2. If your module doesn't have a go.mod file yet, change directories into your module's folder and run go mod init to create a go.mod file for your package.

     go mod init MODULE_PATH
   

   Replace MODULE_PATH with the module path for the module stored in Artifact Registry. See the Go Modules Reference for more information.

3. To require the version of your module stored in Artifact Registry, edit your go.mod file to resemble the following:

   
   module example.com/bar
   
   go 1.19
   
   require example.com/foo v0.1.0
   

   Replace the following:

   • example.com/foo is the module path of the required module
   • v0.1.0 is the version stored in Artifact Registry

4. Include the module path as normal in the import section of your main.go file.

   For example, to import a module with the path example.com/foo stored in Artifact Registry, your import section might resemble the following:

     
     package main
   
     import (
       foo "example.com/foo"
     )
   
     func main() {
   
       ...
   
     }
   
     
   

5. Run go mod tidy to download dependencies:

     go mod tidy
   

6. Run your module as normal:

     go run .
   

   The module stored in Artifact Registry is downloaded and used as a dependency.

Delete packaged Go modules

Repository modes: standard

You can delete a package and all its versions, or delete a specific version.

• Once you delete a package, you cannot undo the action.

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

To delete versions of a package:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

What's next

• Try the Go Quickstart.
• Download individual files associated with a module or version without using Go commands.