oras

ExampleAttachBlobToRemoteRepository gives an example of attaching a blob to an existing artifact in a remote repository. The blob is packed as a manifest whose subject is the existing artifact.

package main

import (
	"context"
	"fmt"

	v1 "github.com/opencontainers/image-spec/specs-go/v1"
	oras "github.com/oras-project/oras-go/v3"
	"github.com/oras-project/oras-go/v3/registry/remote"
	"github.com/oras-project/oras-go/v3/registry/remote/auth"
	"github.com/oras-project/oras-go/v3/registry/remote/retry"
)

func main() {
	// 0. Connect to a remote repository with basic authentication
	registry := "myregistry.example.com"
	repository := "myrepo"
	repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", registry, repository))
	if err != nil {
		panic(err)
	}
	// Note: The below code can be omitted if authentication is not required.
	repo.Client = &auth.Client{
		Client: retry.DefaultClient,
		Cache:  auth.NewCache(),
		Credential: auth.StaticCredential(registry, auth.Credential{
			Username: "username",
			Password: "password",
		}),
	}

	// 1. Resolve the subject descriptor
	ctx := context.Background()
	subjectDescriptor, err := repo.Resolve(ctx, "sha256:f3a0356fe9f82b925c2f15106d3932252f36c1c56fd35be6c369d274f433d177")
	if err != nil {
		panic(err)
	}

	// 2. Prepare the blob to be attached
	blob := []byte("example blob")

	// 3. Push the blob to the repository
	blobDescriptor, err := oras.PushBytes(ctx, repo, v1.MediaTypeImageLayer, blob)
	if err != nil {
		panic(err)
	}
	fmt.Println("pushed the blob to the repository")

	// 4. Pack the blob as a manifest with version v1.1 and push it to the repository
	packOpts := oras.PackManifestOptions{
		Layers:  []v1.Descriptor{blobDescriptor},
		Subject: &subjectDescriptor,
	}
	artifactType := "application/vnd.example+type"
	referrerDescriptor, err := oras.PackManifest(ctx, repo, oras.PackManifestVersion1_1, artifactType, packOpts)
	if err != nil {
		panic(err)
	}
	fmt.Printf("attached %s to %s\n", referrerDescriptor.Digest, subjectDescriptor.Digest)
}

ExampleCopyArtifactFromRepository gives an example of copying an artifact from a remote repository into memory.

// 0. Connect to a remote repository
repositoryName := "source"
src, err := remote.NewRepository(fmt.Sprintf("%s/%s", remoteHost, repositoryName))
if err != nil {
	panic(err)
}

// 1. Create a memory store
dst := memory.New()
ctx := context.Background()

// 2. Resolve the descriptor of the artifact from the digest
exampleDigest := "sha256:70c29a81e235dda5c2cebb8ec06eafd3cca346cbd91f15ac74cefd98681c5b3d"
descriptor, err := src.Resolve(ctx, exampleDigest)
if err != nil {
	panic(err)
}

// 3. Copy the artifact from the remote repository
err = oras.CopyGraph(ctx, src, dst, descriptor, oras.DefaultCopyGraphOptions)
if err != nil {
	panic(err)
}

// 4. Verify that the artifact manifest described by the descriptor exists in dst
contentExists, err := dst.Exists(ctx, descriptor)
if err != nil {
	panic(err)
}
fmt.Println(contentExists)

Output:

true

ExampleExtendedCopyArtifactAndReferrersFromRepository gives an example of copying an artifact along with its referrers from a remote repository into memory.

// 0. Connect to a remote repository
repositoryName := "source"
src, err := remote.NewRepository(fmt.Sprintf("%s/%s", remoteHost, repositoryName))
if err != nil {
	panic(err)
}

// 1. Create a memory store
dst := memory.New()
ctx := context.Background()

// 2. Copy the artifact and its referrers from the remote repository
tagName := "latest"
// ExtendedCopy will copy the artifact tagged by "latest" along with all of its
// referrers from src to dst.
desc, err := oras.ExtendedCopy(ctx, src, tagName, dst, tagName, oras.DefaultExtendedCopyOptions)
if err != nil {
	panic(err)
}

fmt.Println(desc.Digest)

Output:

sha256:f396bc4d300934a39ca28ab0d5ac8a3573336d7d63c654d783a68cd1e2057662

ExampleExtendedCopyArtifactAndReferrersToRepository is an example of pushing an artifact and its referrer to a remote repository.

// 0. Assemble the referenced manifest in memory with tag "v1"
ctx := context.Background()
src := memory.New()
manifestDescriptor, err := oras.PackManifest(ctx, src, oras.PackManifestVersion1_1, "application/vnd.example+type", oras.PackManifestOptions{})
if err != nil {
	panic(err)
}
fmt.Println("created manifest: ", manifestDescriptor)

tag := "v1"
err = src.Tag(ctx, manifestDescriptor, tag)
if err != nil {
	panic(err)
}
fmt.Println("tagged manifest: ", manifestDescriptor.Digest)

// 1. Assemble the referrer manifest in memory
referrerPackOpts := oras.PackManifestOptions{
	Subject: &manifestDescriptor,
}
referrerDescriptor, err := oras.PackManifest(ctx, src, oras.PackManifestVersion1_1, "sbom/example", referrerPackOpts)
if err != nil {
	panic(err)
}
fmt.Println("created referrer: ", referrerDescriptor)

// 2. Connect to a remote repository with basic authentication
registry := "myregistry.example.com"
repository := "myrepo"
repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", registry, repository))
if err != nil {
	panic(err)
}
// Note: The below code can be omitted if authentication is not required.
repo.Client = &auth.Client{
	Client: retry.DefaultClient,
	Cache:  auth.NewCache(),
	Credential: auth.StaticCredential(registry, auth.Credential{
		Username: "username",
		Password: "password",
	}),
}

// 3. Push the manifest and its referrer to the remote repository
desc, err := oras.ExtendedCopy(ctx, src, tag, repo, "", oras.DefaultExtendedCopyOptions)
if err != nil {
	panic(err)
}
fmt.Println("pushed: ", desc.Digest)

ExamplePullFilesFromRemoteRepository gives an example of pulling files from a remote repository to the local file system.

package main

import (
	"context"
	"fmt"

	oras "github.com/oras-project/oras-go/v3"
	"github.com/oras-project/oras-go/v3/content/file"
	"github.com/oras-project/oras-go/v3/registry/remote"
	"github.com/oras-project/oras-go/v3/registry/remote/auth"
	"github.com/oras-project/oras-go/v3/registry/remote/retry"
)

func main() {
	// 0. Create a file store
	fs, err := file.New("/tmp/")
	if err != nil {
		panic(err)
	}
	defer fs.Close()

	// 1. Connect to a remote repository
	ctx := context.Background()
	reg := "myregistry.example.com"
	repo, err := remote.NewRepository(reg + "/myrepo")
	if err != nil {
		panic(err)
	}
	// Note: The below code can be omitted if authentication is not required
	repo.Client = &auth.Client{
		Client: retry.DefaultClient,
		Cache:  auth.NewCache(),
		Credential: auth.StaticCredential(reg, auth.Credential{
			Username: "username",
			Password: "password",
		}),
	}

	// 2. Copy from the remote repository to the file store
	tag := "latest"
	manifestDescriptor, err := oras.Copy(ctx, repo, tag, fs, tag, oras.DefaultCopyOptions)
	if err != nil {
		panic(err)
	}
	fmt.Println("manifest descriptor:", manifestDescriptor)
}

ExamplePullImageFromRemoteRepository gives an example of pulling an image from a remote repository to an OCI Image layout folder.

package main

import (
	"context"
	"fmt"

	oras "github.com/oras-project/oras-go/v3"
	"github.com/oras-project/oras-go/v3/content/oci"
	"github.com/oras-project/oras-go/v3/registry/remote"
	"github.com/oras-project/oras-go/v3/registry/remote/auth"
	"github.com/oras-project/oras-go/v3/registry/remote/retry"
)

func main() {
	// 0. Create an OCI layout store
	store, err := oci.New("/tmp/oci-layout-root")
	if err != nil {
		panic(err)
	}

	// 1. Connect to a remote repository
	ctx := context.Background()
	reg := "myregistry.example.com"
	repo, err := remote.NewRepository(reg + "/myrepo")
	if err != nil {
		panic(err)
	}
	// Note: The below code can be omitted if authentication is not required
	repo.Client = &auth.Client{
		Client: retry.DefaultClient,
		Cache:  auth.NewCache(),
		Credential: auth.StaticCredential(reg, auth.Credential{
			Username: "username",
			Password: "password",
		}),
	}

	// 2. Copy from the remote repository to the OCI layout store
	tag := "latest"
	manifestDescriptor, err := oras.Copy(ctx, repo, tag, store, tag, oras.DefaultCopyOptions)
	if err != nil {
		panic(err)
	}
	fmt.Println("manifest descriptor:", manifestDescriptor)
}

ExamplePullImageUsingDockerCredentials gives an example of pulling an image from a remote repository to an OCI Image layout folder using Docker credentials.

package main

import (
	"context"
	"fmt"

	oras "github.com/oras-project/oras-go/v3"
	"github.com/oras-project/oras-go/v3/content/oci"
	"github.com/oras-project/oras-go/v3/registry/remote"
	"github.com/oras-project/oras-go/v3/registry/remote/auth"
	"github.com/oras-project/oras-go/v3/registry/remote/credentials"
	"github.com/oras-project/oras-go/v3/registry/remote/retry"
)

func main() {
	// 0. Create an OCI layout store
	store, err := oci.New("/tmp/oci-layout-root")
	if err != nil {
		panic(err)
	}

	// 1. Connect to a remote repository
	ctx := context.Background()
	reg := "docker.io"
	repo, err := remote.NewRepository(reg + "/user/my-repo")
	if err != nil {
		panic(err)
	}

	// prepare authentication using Docker credentials
	storeOpts := credentials.StoreOptions{}
	credStore, err := credentials.NewStoreFromDocker(storeOpts)
	if err != nil {
		panic(err)
	}
	repo.Client = &auth.Client{
		Client:     retry.DefaultClient,
		Cache:      auth.NewCache(),
		Credential: credentials.Credential(credStore), // Use the credentials store
	}

	// 2. Copy from the remote repository to the OCI layout store
	tag := "latest"
	manifestDescriptor, err := oras.Copy(ctx, repo, tag, store, tag, oras.DefaultCopyOptions)
	if err != nil {
		panic(err)
	}

	fmt.Println("manifest pulled:", manifestDescriptor.Digest, manifestDescriptor.MediaType)
}

ExamplePushFilesToRemoteRepository gives an example of pushing local files to a remote repository.

package main

import (
	"context"
	"fmt"

	v1 "github.com/opencontainers/image-spec/specs-go/v1"
	oras "github.com/oras-project/oras-go/v3"
	"github.com/oras-project/oras-go/v3/content/file"
	"github.com/oras-project/oras-go/v3/registry/remote"
	"github.com/oras-project/oras-go/v3/registry/remote/auth"
	"github.com/oras-project/oras-go/v3/registry/remote/retry"
)

func main() {
	// 0. Create a file store
	fs, err := file.New("/tmp/")
	if err != nil {
		panic(err)
	}
	defer fs.Close()
	ctx := context.Background()

	// 1. Add files to the file store
	mediaType := "application/vnd.test.file"
	fileNames := []string{"/tmp/myfile"}
	fileDescriptors := make([]v1.Descriptor, 0, len(fileNames))
	for _, name := range fileNames {
		fileDescriptor, err := fs.Add(ctx, name, mediaType, "")
		if err != nil {
			panic(err)
		}
		fileDescriptors = append(fileDescriptors, fileDescriptor)
		fmt.Printf("file descriptor for %s: %v\n", name, fileDescriptor)
	}

	// 2. Pack the files and tag the packed manifest
	artifactType := "application/vnd.test.artifact"
	opts := oras.PackManifestOptions{
		Layers: fileDescriptors,
	}
	manifestDescriptor, err := oras.PackManifest(ctx, fs, oras.PackManifestVersion1_1, artifactType, opts)
	if err != nil {
		panic(err)
	}
	fmt.Println("manifest descriptor:", manifestDescriptor)

	tag := "latest"
	if err = fs.Tag(ctx, manifestDescriptor, tag); err != nil {
		panic(err)
	}

	// 3. Connect to a remote repository
	reg := "myregistry.example.com"
	repo, err := remote.NewRepository(reg + "/myrepo")
	if err != nil {
		panic(err)
	}
	// Note: The below code can be omitted if authentication is not required
	repo.Client = &auth.Client{
		Client: retry.DefaultClient,
		Cache:  auth.NewCache(),
		Credential: auth.StaticCredential(reg, auth.Credential{
			Username: "username",
			Password: "password",
		}),
	}

	// 4. Copy from the file store to the remote repository
	_, err = oras.Copy(ctx, fs, tag, repo, tag, oras.DefaultCopyOptions)
	if err != nil {
		panic(err)
	}
}