GitHub - step-security-bot/oras-java: ORAS Java SKD

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 for version 0.2.x are published on GitHub Maven packages. SNAPSHOT for version 0.3.x and above are published on Maven Central at: https://central.sonatype.com/repository/maven-snapshots/

Releases are published on Maven Central since version 0.2.x.

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)

Then on your pom.xml

<repositories>
    <repository>
        <id>central-snapshots</id>
        <name>ORAS Maven Central SNAPSHOTS</name>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
</repositories>

Examples

Authentication

Using default existing login existing credentials (e.g. ~/.docker/config.json) or $XDG_RUNTIME_DIR/containers/auth.json (no support for repository prefix yet)

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

Using username and password

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

Registries configuration

Since version 0.4.0 ORAS Java SDK partially support the registries.conf (https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)

For example

# Use registry for unqualified images
short-name-mode = "enforcing" # Default if not set. Unsafe if `disabled` and multiple unqualified-search-registries are set
unqualified-search-registries = ["docker.io"]

# Rewrite a location with prefix
[[registry]]
prefix = "docker.io/bitnami"
location = "docker.io/bitnamilegacy"

# Block a registry/repository via prefix
[[registry]]
prefix = "gcr.io"
blocked = true

# Set registry unsecure
[[registry]]
location = "localhost:5000"
insecure = true

Push an Artifact

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

Pull an Artifact

Registry registry = 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.