This page describes adding, viewing, and deleting Java packages.
If you want to use sbt as a build tool for Scala and Java instead of using Maven or Gradle, there is a community-created sbt plugin available. This documentation does not describe configuration or usage of Scala clients.
Before you begin
- If the target repository does not exist, create a new repository.
- Verify that you have the required permissions for the repository.
- Verify that you have configured authentication. If you are using an access token, make sure that you refresh the token before connecting to the repository.
- (Optional) Configure defaults for gcloud commands.
Required roles
To get the permissions that you need to manage packages, ask your administrator to grant you the following IAM roles on the repository:
-
View packages or files in packages:
Artifact Registry Reader (
roles/artifactregistry.reader
) -
Download or install packages:
Artifact Registry Reader (
roles/artifactregistry.reader
) -
Add packages to a repository:
Artifact Registry Writer (
roles/artifactregistry.writer
) -
Delete packages:
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.
Adding packages
Repository modes: Standard
To add packages to the repository:
Maven
Use mvn deploy
and mvn release
to add packages to the repository.
To successfully deploy a Maven project that references a parent, the project must include the Artifact Registry Wagon provider in a core extensions file as described in the authentication instructions.
Use mvn deploy:deploy-file
to upload artifacts that were built outside of
Maven.
For example, this example command deploys example/external.jar
and its project
file example/pom.xml
to the repository
us-central1-maven.pkg.dev/my-project/my-repo
mvn deploy:deploy-file \
-Durl=artifactregistry://us-central1-maven.pkg.dev/my-project/my-repo \
-DpomFile=example/pom.xml -Dfile=example/external.jar
To configure integration with Cloud Build, see Integrating with Cloud Build.
Gradle
To successfully publish to the repository, your build.gradle
file must include
a publications section that defines files to upload.
Use the gradle publish
command to upload a package to the repository.
Viewing packages and versions
Repository modes: standard, remote
To view packages and package versions using the Google Cloud console
or gcloud
:
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 the package.
gcloud
To list packages in a repository, run the following command:
gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]
Where
- 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.
To view versions of a package, run the following command:
gcloud artifacts versions list --package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION]
Where
- PACKAGE is the ID of the package or fully qualified identifier for the package.
- 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.
For remote repositories, the returned list should include all direct and transitive dependencies.
Listing files
Repository modes: standard, remote
You can list files in a repository, files in all versions of a specified package, or files in a specific version of a package.
For all the following commands, you can set a maximum number of files to return
by adding the --limit
flag to the command.
To list all files in the default project, repository, and location when the default values are configured:
gcloud artifacts files list
To list files in a specified project, repository, and location, run the command:
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION
To list files for all versions of a specific package:
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION \
--package=PACKAGE
To list files for a specific package version:
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION \
--package=PACKAGE \
--version=VERSION
Replace the following values:
LOCATION
: the regional or multi-regional location of the repository.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (`:`), see Domain-scoped projects.REPOSITORY
: the name of the repository where the image is stored.PACKAGE
: the name of the package.VERSION
: the version of the package.
Examples
Consider the following package information:
- Project:
my-project
- Repository:
my-repo
- Repository location:
us-west1
- Package:
my-app
The following command lists all files in the repository my-repo
in the
location us-west1
within the default project:
gcloud artifacts files list \
--location=us-west1 \
--repository=my-repo
1.0
of the package.
gcloud artifacts files list \
--project=my-project \
--location=us-west1 \
--repository=my-repo \
--package=my-app \
--version=1.0
Downloading packages
Repository modes: standard, remote, virtual
To download an artifact as a part of your build, you declare the artifact as a dependency.
Maven
Declare the packages you want to download in the project
pom.xml
file. The following example declares version 1.0 of the packageartifact
as a dependency.<dependencies> <dependency> <groupId>group</groupId> <artifactId>artifact</artifactId> <version>1.0</version> </dependency> </dependencies>
To learn more about Maven dependencies, see the Maven introduction to dependencies and dependency reference.
Build the Java project.
mvn compile
Gradle
Declare the packages you want to download in the project
build.gradle
file. The following example declares version 1.0 of the packageartifact
as an external compile dependency.To learn more about Gradle dependencies, see the Gradle documentation.
dependencies { compile group: 'group', name: 'artifact', version: '1.0' }
Build the Java project.
gradle build
For standard repositories, you download a package directly from the repository.
For a remote repository, you download a cached copy of the package and its dependencies. If a cached copy does not exist, the remote repository downloads the package from the upstream source and caches it before serving it to you. You can verify that the remote repository retrieved the packages from the upstream source by viewing the list of packages in the repository.
For a virtual repository, Artifact Registry searches upstream repositories for the requested package.
- Upstream remote repositories will download and cache the requested package if a cached copy does not exist. Virtual repositories only serve requested packages, they do not store them.
- If you request a version that is available in more than one upstream repository, Artifact Registry chooses an upstream repository to use based on the priority settings configured for the virtual repository.
For example, consider a virtual repository with the following priority settings for upstream repositories:
main-repo
: Priority set to100
secondary-repo1
: Priority set to80
.secondary-repo2
: Priority set to80
.test-repo
: Priority set to20
.
main-repo
has the highest priority value, so the virtual repository
always searches it first.
Both secondary-repo1
and secondary-repo2
have priority set to 80
. If a
requested package is not available in main-repo
, Artifact Registry
searches these repositories next. Since they both have the same priority value,
Artifact Registry can choose to serve a package from either repository
if the version is available in both of them.
test-repo
has is lowest priority value and will serve a stored artifact if
none of the other upstream repositories has it.
Deleting packages and versions
Repository modes: standard, remote
You can delete a package and all its versions, or delete a specific version.
- Once you delete a package, you cannot undo the action.
- For remote repositories, only the cached copy of the package is deleted. The upstream source is unaffected. If you delete a cached package, Artifact Registry will download and cache it again the next time the repository receives a request for the same package version.
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
- Learn about managing Node.js packages
- Learn about managing Python packages
- Learn about managing container images
- Download individual files within a package