This page explains how to manage packaged Go modules stored in Artifact Registry.
Before you begin
- If the target repository does not exist, create a new repository. Choose Go as the repository format.
- Verify that you have the required permissions for the repository.
- (Optional) Configure defaults for gcloud commands.
- Install Go 1.15 or later.
Install the package-go-module gcloud CLI add-on:
gcloud components install package-go-module
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
whereX
is the major version,Y
is the minor version, andZ
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.
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
If your module doesn't have a
go.mod
file yet, change directories into your module's folder and rungo mod init
to create ago.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.
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 modulev0.1.0
is the version stored in Artifact Registry
Include the module path as normal in the
import
section of yourmain.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() { ... }
Run
go mod tidy
to download dependencies:go mod tidy
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:
Console
Open the Repositories page in the Google Cloud console.
In the repository list, click the appropriate repository.
The Packages page lists the packages in the repository.
Select the package that you want to delete.
Click DELETE.
In the confirmation dialog box, click DELETE.
gcloud
Run the following command:
gcloud artifacts packages delete PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] [--async]
Where
- PACKAGE is the name of the package in the repository.
- REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
- LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
--async
Return immediately, without waiting for the operation in progress to complete.
To delete versions of a package:
Console
Open the Repositories page in the Google Cloud console.
In the repository list, click the appropriate repository.
The Packages page lists the packages in the repository.
Click a package to view versions of that package.
Select versions that you want to delete.
Click DELETE.
In the confirmation dialog box, click DELETE.
gcloud
Run the following command:
gcloud artifacts versions delete VERSION \
--package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] \
[--async]
Where
- PACKAGE is the name of the package in the repository.
- REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
- LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
--async
returns immediately, without waiting for the operation in progress to complete.
What's next
- Try the Go Quickstart.
- Download individual files associated with a module or version without using Go commands.