An exactly tagged oras build empties its own version metadata
OCI registry client - managing content like artifacts, images, packages
At a glance
- What is it?
- oras is a Go client for OCI registries that ships as a single binary with container images, release archives and a Snap package. The Makefile injects version information into the binary at link time and then clears it again on exactly tagged builds, the YAML library it depends on is a release candidate, and the page documents no Linux install command at all.
- Who is it for?
- oras suits a team that stores artifacts in an OCI registry and wants one small client for pushing, pulling and copying them, and that can live with a container or a Snap as the install shape. Before adopting it, read the tag table rather than assuming `:latest` means newest, because rolling tags only ever move forward and prereleases never move them at all.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- oras-project/oras2,512 ★ · +58
| Repository | 2026-09-30 | 2026-11-21 |
|---|---|---|
| oras-project/oras | 2.5k | 2.5k |
58 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Five tag shapes, and rolling tags that never move backwards
The container image section is the most precise part of the page. Release images are published for multiple architectures to GitHub Container Registry under `oras-project/oras`, and each release gets five tags with distinct meanings. `:main` tracks the latest merge on the default branch. `:vX.Y.Z` is the immutable tag for a specific release. `:vX.Y` tracks the latest stable patch inside one minor line, `:vX` tracks the latest stable release inside one major line, and `:latest` tracks the highest stable release across all major versions. Then there is a paragraph about what does not happen. Prereleases never move rolling tags, and a maintenance branch release only moves the rolling tags for its own minor and major lines, and only when it is newer than the tag already in that line. The stated purpose is to keep `:latest` and the bounded tags from moving backwards after a backport, which means a user pinning a rolling tag gets a version that only ever climbs.
The link time flags clear the version they just set on a tagged build
Version information is compiled into the binary rather than read at run time, through a block of linker flags:
LDFLAGS = -w
ifdef VERSION
LDFLAGS += -X $(PROJECT_PKG)/internal/version.BuildMetadata=$(VERSION)
endif
ifneq ($(GIT_TAG),)
LDFLAGS += -X $(PROJECT_PKG)/internal/version.BuildMetadata=
endif
LDFLAGS += -X $(PROJECT_PKG)/internal/version.GitCommit=${GIT_COMMIT}
LDFLAGS += -X $(PROJECT_PKG)/internal/version.GitTreeState=${GIT_DIRTY}The first conditional appends a value to `internal/version.BuildMetadata` when a VERSION variable is defined. The second appends the same variable with an empty value whenever the tree sits exactly on a tag, since GIT_TAG comes from `git describe --tags --abbrev=0 --exact-match`. The flags are appended in order, so a build that defines VERSION and is also exactly on a tag ends up passing the same symbol twice, the second time empty. The commit hash and the tree state survive either way: the commit comes from `git rev-parse HEAD` and the tree state is the word dirty or clean from `git status --porcelain`, which is the piece that tells a user whether the binary they are running matches a released tree.
Thirteen release artifacts, including loong64 and riscv64
The release list is a single variable, and it is longer than a typical client needs:
checksums.txt darwin_amd64.tar.gz darwin_arm64.tar.gz linux_amd64.tar.gz linux_arm64.tar.gz linux_armv7.tar.gz linux_s390x.tar.gz linux_ppc64le.tar.gz linux_riscv64.tar.gz linux_loong64.tar.gz windows_amd64.zip windows_arm64.zip freebsd_amd64.tar.gzThat is five architectures on Linux including armv7, s390x, ppc64le, riscv64 and loong64, two on macOS, two zips on Windows and one FreeBSD tarball, plus a checksums file. Windows ships as zip while everything else is a gzipped tarball, which is why the container build names its target with the platform turned into a suffix. Host detection for a plain build is done with `uname -o` and `uname -m` mapped to two words, Darwin becoming mac and anything else becoming linux, and arm64 becoming arm64 with everything else becoming amd64. The default goal runs lint, then test, then the host build, so an unsupported uname does not fail loudly, it just quietly produces a linux/amd64 binary.
The YAML library in the dependency list is a release candidate
The module declares `go 1.26.7` and depends on `go.yaml.in/yaml/v4 v4.0.0-rc.6`, a release candidate of a new major version, as a direct requirement rather than something held back. The rest of the direct set is ordinary for a registry client: the OpenAPI digest and image specification libraries, cobra and pflag for the command line, logrus for logging, and `golang.org/x/term` for terminal handling. Two entries are worth a second look. `github.com/morikuni/aec` is an ANSI escape code library, which is how the binary colours its output, and `github.com/Masterminds/sprig/v3` is a template function library, so the shipped binary carries a template engine whether or not the command you run needs one. The module path is the vanity import `oras.land/oras`, and the sibling library `oras.land/oras-go/v2` is a direct dependency too, so the client and the library it drives share a domain rather than living in the same repository path.
The container names a Makefile target from the target platform
The container build is a cross compilation driven by one variable:
FROM --platform=$BUILDPLATFORM docker.io/library/golang:1.27.1-alpine as builder
ARG TARGETPLATFORM
RUN apk add git make
RUN make "build-$(echo $TARGETPLATFORM | tr / -)"
RUN mv ${ORASPKG}/bin/${TARGETPLATFORM}/oras /go/bin/orasThe platform string arrives as build arguments, the slashes are turned into dashes to form a Makefile target name, and the produced binary is moved out of the platform specific output directory. Both base images are pinned to exact versions, the builder to a Go 1.27.1 Alpine tag and the runtime to Alpine 3.24.2, and the runtime stage adds ca-certificates, creates a `/workspace` directory, sets it as the working directory and points the entrypoint at the binary. The builder's Go line is ahead of the module's declared floor of 1.26.7, which is the safe direction, but it does mean the container is not pinned to the minimum the code claims to need.
The page documents no Linux install command
What the page offers for getting the binary is a documentation link and a container registry. There is no package manager line, no download command and no checksum instruction anywhere in it, which is a real gap for anyone arriving from a search that asks how to install it on Linux. Everything else is in the tree instead. `snapcraft.yaml` is a Snap package definition, which is a Linux distribution channel the page never mentions. `.goreleaser.yml` is the release tool's configuration, matching the thirteen artifacts in the Makefile. `copyright.tmpl` is a licence header template, which is how the Apache header in the Dockerfile and the Makefile gets stamped into source files rather than typed by hand. `KEYS` sits at the root as a keyring, which is what signed release artifacts are verified against, and there is no note about it on the page either. `.golangci.yml` is the lint configuration for the Go code.
Two ownership files and one adopted code of conduct
The governance surface at the root is duplicated in a way that has a reason. There is a `CODEOWNERS` file for GitHub's review assignment and an `OWNERS.md` in the Kubernetes format, each with `MAINTAINERS.md` beside it, so the project answers to both review systems rather than one. `SECURITY.md` covers vulnerability reporting and `CONTRIBUTING.md` the contribution process, while the page itself sends contributors to two guides hosted on the project site, one for the development environment and one for contributing. The code of conduct is not written here: the project states it has adopted the CNCF Code of Conduct and points at its own `CODE_OF_CONDUCT.md` for details, which is the one piece of process on the page that names an external parent document. The directory layout follows the same shape as the binary, with `cmd/` for the entry point, `internal/` for everything the linker flags write into, `docs/` for the site content and `test/` for the suite.
Editorial conclusion
oras suits a team that stores artifacts in an OCI registry and wants one small client for pushing, pulling and copying them, and that can live with a container or a Snap as the install shape. Before adopting it, read the tag table rather than assuming `:latest` means newest, because rolling tags only ever move forward and prereleases never move them at all. Check the dependency list before building from source, since a YAML library is pinned at a release candidate, and if you cut your own releases read the link time flags, because a build made exactly on a tag ends up with empty build metadata. It is a client for a registry protocol, not a registry, so it is only half of what a distribution pipeline needs.
Frequently asked questions
How to install oras in Linux?
The page carries no package manager or download command for Linux. It points at the documentation at oras.land/cli, publishes multi architecture container images to GitHub Container Registry, and the repository contains a snapcraft.yaml for a Snap package; the Makefile builds thirteen release archives including several Linux architectures.
What does oras stand for?
The repository never expands the acronym anywhere in its text or metadata. The description calls it an OCI registry client for managing content such as artifacts, images and packages, and the Go module path is the vanity import `oras.land/oras`.
What are the oras container image tags?
Five shapes, all on ghcr.io. `:main` tracks the latest merge on the default branch, `:vX.Y.Z` is immutable for one release, `:vX.Y` tracks the latest stable patch in a minor line, `:vX` the latest stable release in a major line, and `:latest` the highest stable release across all majors. Prereleases never move a rolling tag, and backports only move tags within their own lines so nothing moves backwards.
What Go version does oras need?
The module declares `go 1.26.7`, and the container build stage is pinned to a Go 1.27.1 Alpine tag. The module path is the vanity import `oras.land/oras`, and it depends on the sibling library `oras.land/oras-go/v2` directly.
How does oras put version information into its binary?
At link time, with linker flags writing into `internal/version`. The commit hash and a dirty or clean tree state always go in, and a VERSION variable is written into BuildMetadata, except that the same flag is appended with an empty value when the tree is exactly on a tag, so a tagged build made with VERSION defined ends up with empty build metadata.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/oras-project-oras)Star history chart for your README
[](https://hysenlabs.com/projects/oras-project-oras)Was this useful?