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>

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)

Registry registry = Registry.Builder.builder().defaults().build();

Using username and password

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

Push an Artifact

Path artifact = Path.of("my-file.txt");
Registry registry = Registry.Builder.builder().insecure().build();
Manifest manifest = registry.pushArtifact(ContainerRef.parse("localhost:5000/hello:v1"), artifact);

Pull an Artifact

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

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.