v2.5.0

Tip

Upgrade to v2.5.0 for optimal performance when compiled with Go 1.22 or later.

Warning

v2.5.0 does not compile with Go 1.20.x or earlier.

New Features

• Upgrade to image-spec v1.1.0 and distributio-spec v1.1.0
  • Introduce oras.PackManifestVersion1_1 for packing OCI Image Manifest defined in image-spec v1.1.0

Deprecation

• oras.PackManifestVersion1_1_RC4 is deprecated and not recommended for future use. Use oras.PackManifestVersion1_1 instead.

Bug Fixes

• Fix #698: registry.ParseReference returns false positive when registry is empty
• Fix #727: Subsequent calls to credentials.DynamicStore.Put will not set the detected credential store after the first failed attempt
• Fix #730: file.Store has race conditions when restoring content with the same name

Other Changes

• Update the Go support window to [1.21, 1.22]
• Update unit tests and examples
• Improve performance

Detailed Commits

• build(deps): bump github.com/opencontainers/image-spec from 1.1.0-rc6 to 1.1.0 by @dependabot in #708
• feat: upgrade to distribution-spec v1.1.0 by @wangxiaoxuan273 in #720
• build: bump go version by @dextrot in #715
• test: add a new case for UnwrapNopCloser by @shizhMSFT in #725
• perf: use new built-in methods introduced before go 1.22 by @shizhMSFT in #726
• fix: check empty registry name by @shizhMSFT in #729
• fix(DynamicStore): retry setCredsStore on next PUT by @shizhMSFT in #728
• fix(file.Store): fix race condition on restoring the same named content by @shizhMSFT in #731

New Contributors

• @dextrot made their first contribution in #715

Full Changelog: v2.4.0...v2.5.0

v2.4.0

Breaking Changes

• Upgrade to image-spec v1.1.0-rc6 and distribution-spec v1.1.0-rc4
  • Validate the Content-type header of the response when accessing the Referrers API
  • When pushing manifests with a subject field, if the OCI-Subject header is not set in the response, the registry is considered as not supporting the Referrers API

Warning

There are no API changes in oras-go.
However, when pushing and deleting manifests with a subject field, as well as querying the Referrers API, registries that implement older versions of distribution-spec may be considered as not supporting the Referrers API. In such cases, the Referrers tag schema will be used instead.

Known compatible registries:

• Zot v2.0.0-rc5 and later versions
• Harbor v2.10.0 and later versions

New Features

• Move package credentials from github.com/oras-project/oras-credentials-go to oras.land/oras-go/v2/registry/remote/credentials, which supports reading, saving, and removing credentials from Docker configuration files and external credential stores that follow the Docker credential helper protocol
• Support deletion and garbage collection in oci package
• Add registry.Referrers for listing referrers on any ReadOnlyGraphStorage
• Introduce SkipNode for CopyGraphOptions.PreCopy to signal oras.CopyGraph to stop copying a node
• Introduce SkipUnpack option on file.Store to skip unpacking compressed directories

Performance Improvements

• Improve authorization token caching
  • Support per-host scope hints, fixing #581
  • Introduce auth.NewSingleContextCache that creates a host-based cache for optimizing the auth flow for non-compliant registries
• Optimize Copy efficiency
  • Add MountFrom and OnMounted to oras.CopyGraphOptions to support mounting on copy

Bug Fixes

• Fix #692: index or manifest list without the OPTIONAL field platform cause panic (#695)

Other Changes

• Improve error messages and examples
• Include changes in v2.3.1

Detailed Commits

• feat: merge package credentials back from oras-credentials-go by @Wwwsylvia in #589
• feat: Add 'MemoryStore' by @uanid in #602
• refactor: make credentials.NewMemoryStore return an interface by @Wwwsylvia in #605
• feat: support per-host scope hints by @Wwwsylvia in #604
• feat: support deletion for memory resolver by @wangxiaoxuan273 in #607
• feat: support deletion for OCI storage by @wangxiaoxuan273 in #608
• fix: package credentials to support legacy auth keys in docker config by @Wwwsylvia in #617
• feat: support deletion for memory graph by @wangxiaoxuan273 in #606
• fix: error handling when delete non-existent target by @wangxiaoxuan273 in #627
• chore: add reference details to errors by @sajayantony in #628
• feat: minimal change to support cross-repo blob mounting by @ktarplee in #631
• build(deps): bump golang.org/x/sync from 0.4.0 to 0.5.0 by @dependabot in #637
• feat: extend oci.Store with Delete() by @wangxiaoxuan273 in #614
• fix: rename ErrSkipDesc to SkipNode by @wangxiaoxuan273 in #643
• fix: check content-type when using referrers API by @ktarplee in #635
• build(deps): bump actions/setup-go from 4 to 5 by @dependabot in #655
• build(deps): bump github/codeql-action from 2 to 3 by @dependabot in #658
• feat: add Untag() to *oci.Store by @eiffel-fl in #647
• feat: Referrers support for content.ReadOnlyGraphStorage by @wangxiaoxuan273 in #659
• feat: GC on oci.Store.Delete by @wangxiaoxuan273 in #653
• feat: add a host-based auth cache as a fallback by @ktarplee in #651
• build: increase code coverage threshold to 75% by @wangxiaoxuan273 in #666
• build(deps): bump golang.org/x/sync from 0.5.0 to 0.6.0 by @dependabot in #669
• feat: add MountFrom and OnMounted to CopyGraphOptions by @ktarplee in #665
• docs: add example to parse reference with digest by @shizhMSFT in #675
• feat: Public GC function of oci.Store by @wangxiaoxuan273 in #656
• feat: error type for not finding basic auth creds and export config path by @qweeah in #674
• build(deps): bump github.com/opencontainers/image-spec from 1.1.0-rc5 to 1.1.0-rc.6 by @dependabot in #681
• build(deps): use image-spec v1.1.0-rc6 instead of rc.6 by @Wwwsylvia in #687
• feat: allow skip unpack on push to file store by @wangxiaoxuan273 in #679
• feat: mark untagged manifests as garbage during GC and delete by @wangxiaoxuan273 in #680
• refactor: upgrade to distribution-spec v1.1.0-rc4 by @Wwwsylvia in #690
• fix: fix the potential panic error if there is no platform in the index or manifest list by @lizMSFT in #695
• refactor: remove AutoRemoveReferrers flag by @wangxiaoxuan273 in #683

New Contributors

• @uanid made their first contribution in #602
• @eiffel-fl made their first contribution in #647

Full Changelog: v2.3.0...v2.4.0

v1.2.5

Important

types.AuthConfig is moved to registry.AuthConfig in docker/docker v25.0.0. Although there is no public API change on oras-go side, it may still break users if they are using oras-go v1 along with old versions of docker/docker (see #678).

What's Changed

• build(deps): bump golang.org/x/crypto from 0.13.0 to 0.14.0 by @dependabot in #613
• build(deps): bump golang.org/x/sync from 0.3.0 to 0.4.0 by @dependabot in #612
• build(deps): bump github.com/docker/distribution from 2.8.2+incompatible to 2.8.3+incompatible by @dependabot in #610
• build(deps): bump github.com/docker/docker from 24.0.6+incompatible to 24.0.7+incompatible by @dependabot in #630
• build(deps): bump github.com/docker/cli from 24.0.6+incompatible to 24.0.7+incompatible by @dependabot in #629
• build(deps): bump github.com/spf13/cobra from 1.7.0 to 1.8.0 by @dependabot in #638
• build(deps): bump golang.org/x/sync from 0.4.0 to 0.5.0 by @dependabot in #639
• build(deps): bump golang.org/x/crypto from 0.14.0 to 0.15.0 by @dependabot in #642
• build(deps): bump golang.org/x/crypto from 0.15.0 to 0.16.0 by @dependabot in #649
• build(deps): bump golang.org/x/crypto from 0.16.0 to 0.17.0 by @dependabot in #660
• build(deps): bump golang.org/x/sync from 0.5.0 to 0.6.0 by @dependabot in #668
• build(deps): bump golang.org/x/crypto from 0.17.0 to 0.18.0 by @dependabot in #673
• build(deps): bump github.com/docker/go-connections from 0.4.0 to 0.5.0 by @dependabot in #672
• fix: get rid of deprecated types.AuthConfig by @ilya-lesikov in #678
• build(deps): bump github.com/opencontainers/image-spec from 1.1.0-rc5 to 1.1.0-rc6 by @Wwwsylvia in #686
• build(deps): bump github.com/docker/cli from 24.0.7+incompatible to 25.0.0+incompatible by @dependabot in #688
• build(deps): bump github.com/docker/docker from 24.0.7+incompatible to 25.0.0+incompatible by @dependabot in #689
• build(deps): bump github.com/docker/docker from 25.0.0+incompatible to 25.0.1+incompatible by @dependabot in #693
• build(deps): bump github.com/docker/cli from 25.0.0+incompatible to 25.0.1+incompatible by @dependabot in #694

New Contributors

• @ilya-lesikov made their first contribution in #678

Full Changelog: v1.2.4...v1.2.5

v2.3.1

Bug Fixes

• Fix #592: Referrers tag index is not updated when all referrers are removed and GC is skipped
• Fix #600: sibling() is copying a sync.Mutex
• Fix #552: OnCopySkipped is called unexpectedly on root node when using oras.Copy

Other Changes

• Update the Go support window to [1.20, 1.21] (#587)
• Upgrade image-spec to v1.1.0-rc5 (#615)
• Backport #618: Optimize the authentication workflow for Repository.Manifests().Delete() (#623)

Detailed Commits

• Add SECURITY.md file by @TerryHowe in #579
• build(deps): bump actions/checkout from 3 to 4 by @dependabot in #585
• build: bump go version by @Wwwsylvia in #587
• fix: push an empty index when deleting the last referrer with SkipReferrersGC by @Wwwsylvia in #593
• fix: Avoid a copy of sync.Mutex in Repository by @ktarplee in #603
• fix: correctly handle OnCopySkipped by @Wwwsylvia in #609
• build(deps): bump golang.org/x/sync from 0.3.0 to 0.4.0 by @dependabot in #611
• build: bump github.com/opencontainers/image-spec to v1.1.0-rc5 by @Wwwsylvia in #615
• perf: reduce auth request count for manifest delete by @Wwwsylvia in #618

New Contributors

• @ktarplee made their first contribution in #603

Full Changelog: v2.3.0...v2.3.1

v1.2.4

Warning

registry.Service has been changed from an interface to a struct in docker/docker v24.0.2. While this change does not affect the public API of oras-go v1, it may cause issues for users who are using oras-go v1 along with older versions of docker/docker (see #527).

What's Changed

• build(deps): bump github.com/docker/cli from 23.0.1+incompatible to 23.0.2+incompatible by @dependabot in #474
• build(deps): bump github.com/docker/docker from 23.0.1+incompatible to 23.0.2+incompatible by @dependabot in #473
• build(deps): bump golang.org/x/crypto from 0.7.0 to 0.8.0 by @dependabot in #480
• build(deps): bump github.com/docker/docker from 23.0.2+incompatible to 23.0.3+incompatible by @dependabot in #478
• build(deps): bump github.com/docker/cli from 23.0.2+incompatible to 23.0.3+incompatible by @dependabot in #477
• build(deps): bump github.com/spf13/cobra from 1.6.1 to 1.7.0 by @dependabot in #475
• build(deps): bump github.com/docker/cli from 23.0.3+incompatible to 23.0.5+incompatible by @dependabot in #488
• build(deps): bump github.com/docker/docker from 23.0.3+incompatible to 23.0.5+incompatible by @dependabot in #489
• build(deps): bump golang.org/x/sync from 0.1.0 to 0.2.0 by @dependabot in #499
• build(deps): bump github.com/docker/docker from 23.0.5+incompatible to 23.0.6+incompatible by @dependabot in #501
• build(deps): bump golang.org/x/crypto from 0.8.0 to 0.9.0 by @dependabot in #503
• build(deps): bump github.com/containerd/containerd from 1.7.0 to 1.7.1 by @dependabot in #505
• build(deps): bump github.com/docker/distribution from 2.8.1+incompatible to 2.8.2+incompatible by @dependabot in #506
• build(deps): bump github.com/docker/cli from 23.0.5+incompatible to 23.0.6+incompatible by @dependabot in #502
• build(deps): bump github.com/sirupsen/logrus from 1.9.0 to 1.9.2 by @dependabot in #509
• build(deps): bump github.com/docker/cli from 23.0.6+incompatible to 24.0.2+incompatible by @dependabot in #516
• build(deps): bump github.com/stretchr/testify from 1.8.2 to 1.8.3 by @dependabot in #511
• build(deps): bump github.com/stretchr/testify from 1.8.3 to 1.8.4 by @dependabot in #518
• build(deps): bump golang.org/x/crypto from 0.9.0 to 0.10.0 by @dependabot in #523
• build(deps): bump github.com/sirupsen/logrus from 1.9.2 to 1.9.3 by @dependabot in #521
• build(deps): bump golang.org/x/sync from 0.2.0 to 0.3.0 by @dependabot in #525
• build(deps): bump github.com/containerd/containerd from 1.7.1 to 1.7.2 by @dependabot in #522
• deps: update docker/docker to v24.0.2 (v1) by @dtrudg in #527
• build(deps): bump github.com/opencontainers/image-spec from 1.1.0-rc2.0.20221005185240-3a7f492d3f1b to 1.1.0-rc4 by @dependabot in #529
• build(deps): bump golang.org/x/crypto from 0.10.0 to 0.11.0 by @dependabot in #544
• build(deps): bump github.com/docker/docker from 24.0.2+incompatible to 24.0.3+incompatible by @dependabot in #546
• build(deps): bump github.com/docker/cli from 24.0.2+incompatible to 24.0.4+incompatible by @dependabot in #547
• build(deps): bump github.com/docker/docker from 24.0.3+incompatible to 24.0.4+incompatible by @dependabot in #549
• build(deps): bump github.com/docker/docker from 24.0.4+incompatible to 24.0.5+incompatible by @dependabot in #555
• build(deps): bump github.com/docker/cli from 24.0.4+incompatible to 24.0.5+incompatible by @dependabot in #556
• build(deps): bump github.com/containerd/containerd from 1.7.2 to 1.7.3 by @dependabot in #559
• build(deps): bump golang.org/x/crypto from 0.11.0 to 0.12.0 by @dependabot in #567
• build(deps): bump github.com/containerd/containerd from 1.7.3 to 1.7.4 by @dependabot in #575
• build(deps): bump github.com/containerd/containerd from 1.7.4 to 1.7.5 by @dependabot in #578
• build(deps): bump golang.org/x/crypto from 0.12.0 to 0.13.0 by @dependabot in #588
• build(deps): bump github.com/docker/cli from 24.0.5+incompatible to 24.0.6+incompatible by @dependabot in #590
• build(deps): bump github.com/docker/docker from 24.0.5+incompatible to 24.0.6+incompatible by @dependabot in #591
• build(deps): bump github.com/containerd/containerd from 1.7.5 to 1.7.6 by @dependabot in #595
• build(deps): bump github.com/opencontainers/image-spec from 1.1.0-rc4 to 1.1.0-rc5 by @dependabot in #596

New Contributors

• @dtrudg made their first contribution in #527

Full Changelog: v1.2.3...v1.2.4

v2.3.0

New Features

• Conform to image-spec v1.1.0-rc4 and distribution-spec v1.1.0-rc3, while remaining compatible with image-spec v1.1.0-rc2 and distribution-spec v1.1.0-rc1 (see #494 for more details)
  • Support handling Image Index with a subject
  • Add oras.PackManifest that supports packing Image Manifest version 1.0 and version 1.1.0-rc4, as well as media type validation
  • Add Repository.HandleWarning that can be used to handle warnings returned by the remote registry
  • Update the implementation of Referrers API to support the "OCI-Filters-Applied" response header
  • Update the implementation of pushing manifests with subject to support the "OCI-Subject" response header
• Add Repository.SkipReferrersGC that allows skipping deleting dangling referrers index when referrers tag schema is utilized

Deprecation

• oras.Pack is deprecated and not recommended for future use. Use oras.PackManifest instead.

Other Changes

• Improve documentation and examples

Detailed Commits

• feat: add option to skip referrers GC by @qweeah in #515
• feat: support Image Index with a subject by @Wwwsylvia in #548
• feat: add a PackOption to support packing image manifests that conform to image-spec v1.1.0-rc4 by @Wwwsylvia in #550
• feat: update Referrers API for distribution-spec v1.1.0-rc3 by @Wwwsylvia in #553
• feat: update the implementation of pushing manifest for distribution-spec v1.1.0-rc3 by @Wwwsylvia in #557
• feat: update the implementation of deleting manifest for distribution-spec v1.1.0-rc3 by @Wwwsylvia in #558
• docs: update links by @Wwwsylvia in #563
• feat: report warnings by @Wwwsylvia in #560
• docs: add e2e examples for oras-go by @wangxiaoxuan273 in #561
• docs: display larger example by @wangxiaoxuan273 in #564
• fix: pack should not set artifactType when config is specified by @Wwwsylvia in #565
• build(deps): bump apache/skywalking-eyes from 0.4.0 to 0.5.0 by @dependabot in #569
• refactor: add PackManifest and deprecate Pack by @Wwwsylvia in #570
• refactor: refactor unexported pack methods by @Wwwsylvia in #573
• feat: validate input media type for oras.PackManifest by @Wwwsylvia in #574

Full Changelog: v2.2.1...v2.3.0

v2.2.1

Bug Fixes

• Fix the bug where the "blobs" directory was not being ensured during the initialization of oci.Store (#520)

Other Changes

• Improve error messages
• Upgrade image-spec to v1.1.0-rc4 to mitigate the missing annotation keys issue

Note: oras-go remains on distribution-spec v1.1.0-rc1 and has not implemented v1.1.0-rc2 yet.

Detailed Commits

• build(deps): bump golang.org/x/sync from 0.2.0 to 0.3.0 by @dependabot in #524
• fix(oci): create blobs dir and define blobs dir name constant by @sparr in #520
• fix: improve errors for ReadAll and loadIndexfile by @sparr in #526
• refactor: upgrade go mod to image-spec v1.1.0-rc4 and fix the missing types by @Wwwsylvia in #536
• chore: enable workflows for release branches by @Wwwsylvia in #537

New Contributors

• @sparr made their first contribution in #520

Full Changelog: v2.2.0...v2.2.1

v2.2.0

New Features

• Support mounting a blob from one repository to another in the same remote registry

Bug Fixes

• Fix #484: auth.StaticCredential does not properly handle docker.io

Detailed Commits

• build(deps): bump golang.org/x/sync from 0.1.0 to 0.2.0 by @dependabot in #498
• feat(registry/remote): implement Mount by @rogpeppe in #500
• fix: add special handling for "docker.io" in StaticCredential() by @Wwwsylvia in #504

New Contributors

• @rogpeppe made their first contribution in #500

Full Changelog: v2.1.0...v2.2.0

v2.1.0

New Features

• Introduce remote.ReferrersError in case there is an error in updating the referrers index when the referrers tag schema is applied
  • Here is an example to ignore referrer index deletion error during push a referrer manifest.

Other Changes

• oci.Store.Resolve() and oci.ReadOnlyStore.Resolve() return the original descriptor in the index.json file if tag is queried
• Upgrade image-spec to v1.1.0-rc.3 to mitigate the missing symbol issue (#495)

Note oras-go remains on distribution-spec v1.1.0-rc1 and has not implemented v1.1.0-rc.2 yet.

Detailed Commits

• build(deps): bump actions/setup-go from 3 to 4 by @dependabot in #464
• chore: add .cover to ignore by @TerryHowe in #463
• fix: OCI store resolve returns full descriptor by @oanatmaria in #468
• feat: add type for failure during deleting dangling referrer index by @qweeah in #482
• doc: fix broken links for ORAS logo and oras-go doc by @FeynmanZhou in #490
• build: upgrade image-spec to v1.1.0-rc.3 by @shizhMSFT in #496

Full Changelog: v2.0.2...v2.1.0

v2.0.2

Bug Fixes

• Fix #461: Untagged manifests might be accidentally removed from the index.json file in OCI layouts

Other Changes

• Improve repository governance

Detailed Commits

• chore: update owners by @shizhMSFT in #459
• fix: refactor tagging implementation for OCI Store by @Wwwsylvia in #462

Full Changelog: v2.0.1...v2.0.2