v2.0.0

Brand New V2 Library

What's New

In version v2, ORAS Go library has been completely refreshed with:

• More unified interfaces
• Notably fewer dependencies
• Higher test coverage
• Better documentation
• Balanced security and performance

Besides, ORAS Go v2 is now a registry client conforming image-spec v1.1.0-rc.2 and distribution-spec v1.1.0-rc1.

In ORAS Go v2, artifacts are modeled as Directed Acyclic Graphs (DAGs) stored in Content-Addressable Storages (CASs). Copying artifacts across repositories or generic targets is implemented as copying single-rooted DAGs across CASs. By extending the copy operation, ORAS Go v2 further supports copying underlying DAGs identified by a specific node. For instance, copying a signed artifact with its signatures across repositories.

Documentation and examples are available at pkg.go.dev.

Deprecation

Docker based key management is no longer supported. Credentials are required to be supplied to auth.Client for authentication. Related discussion can be found at #413.

Migration From v1

See MIGRATION_GUIDE.md.

What's Changed Since RC.6

New Features

• Implement registry.TagLister for package content/oci
• Add package registry/remote/retry which provides a default http client with automatic retries

Bug Fixes

• fix #395: oras.Tag() and oras.TagN() should return a descriptor
• fix #402: file.Store fails to extract folder containing symbolic links
• fix #404: oci.Store and file.Store should record an absolute path instead of a relative path for root

Deprecation

• BREAKING CHANGE: Interface registry.ReferrerFinder is renamed to registry.ReferrerLister
• BREAKING CHANGE: Remove file.PackFiles()

Other Changes

• BREAKING CHANGE: oras.Tag() and oras.TagsN() return a descriptor
• BREAKING CHANGE: file.New(), file.NewWithFallbackLimit() and file.NewWithFallbackStorage() return an error
• BREAKING CHANGE: oci.NewStorage() returns an error
• BREAKING CHANGE: auth.DefaultClient uses retry.DefaultClient instead of http.DefaultClient
• Improve the performance of oras.ExtendedCopy()
• Improve documentation
• Improve error messages

Detailed Commits

• fix: add error detail to resolve failure by @qweeah in #390
• fix!: Tag() and TagN() return a descriptor by @shizhMSFT in #396
• feat!: implement Tags for package content/oci by @shizhMSFT in #394
• refactor: optimize performance for Extended Copy by @Wwwsylvia in #397
• remove!: Remove file.PackFiles() and add an example instead by @Wwwsylvia in #400
• doc: Remove main from the godoc URLs in README by @Wwwsylvia in #403
• build: add dependabot for v1 branch, add GitHub Actions by @lucacome in #399
• fix!: fix error when extracting folder containing symbolic links by @Wwwsylvia in #411
• fix!: use absolute path for OCI root by @Wwwsylvia in #412
• test: improve the symlink unit tests for file store by @Wwwsylvia in #414
• feat!: retryable http client by @souleb in #398
• doc: Update README and clean up godoc comments by @Wwwsylvia in #418

Full Changelog: v2.0.0-rc.6...v2.0.0