ORAS Java

Warning

The Oras Java SDK is currently in alpha state.

It's configuration and APIs might change in future releases

OCI Registry as Storage enables libraries to push OCI Artifacts to OCI Conformant registries. This is a Java SDK for Java developers to empower them to do this in their applications.

Consuming SDK

SNAPSHOT version are published on GitHub Maven packages. Releases are published on Maven Central

Javadoc is published from main branch into: https://oras-project.github.io/oras-java/

<dependency>
<groupId>land.oras</groupId>
<artifactId>oras-java-sdk</artifactId>
<version>VERSION_HERE</version>
</dependency>

Quarkus

Quarkus users can use the extension quarkus-oras to use the SDK in their applications.

Follow the Quarkus ORAS documentation to get started with Quarkus.

Only for SNAPSHOTS (only for testing)

GitHub requires authentication to download packages. You can use a personal access token to authenticate with GitHub Packages. To authenticate with GitHub Packages, you need to update your ~/.m2/settings.xml file to include your personal access token.

<server>
<id>oras-java</id>
<username>YOUR_USERNAME</username>
<password>YOUR_ACCESS_TOKEN_WITH_PACKAGE_READ_SCOPE</password>
</server>

Then on your pom.xml

<repositories>
<repository>
<id>oras-java</id>
<url>https://maven.pkg.github.com/oras-project/oras-java</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>

Examples

Authentication

Using default existing login existing credentials (e.g. ~/.docker/config.json)

Registryregistry = Registry.builder().defaults().build();

Using username and password

Registryregistry = Registry.builder().defaults("username", "password").build();

Push an Artifact

LocalPathartifact = LocalPath.of("my-file.txt");
Registryregistry = Registry.builder().insecure().build();
Manifestmanifest = registry.pushArtifact(ContainerRef.parse("localhost:5000/hello:v1"), artifact);

Pull an Artifact

Registryregistry = Registry.builder().insecure().build();
registry.pullArtifact(ContainerRef.parse("localhost:5000/hello:v1"), Path.of("folder"), false);

Deploy SNAPSHOTS

SNAPSHOTS are automatically deployed when the main branch is updated. See the GitHub Actions for more details.

Perform release

• Ensure the draft release version correspond to the version on the pom.xml. Specially if changing the major or minor version. Patch releases are automatically updated.
• Run the release workflow

Code of Conduct

Please note that this project has adopted the CNCF Code of Conduct. Please follow it in all your interactions with the project members and users.

License

This code is licensed under the Apache 2.0 LICENSE.