Skip to content

README.md

Latest commit

 

History

History
87 lines (60 loc) · 3.64 KB

README.md

File metadata and controls

87 lines (60 loc) · 3.64 KB
Raw

setup-oras

banner

Setup ORAS CLI on GitHub Actions runners.

Quick Start

Setup the oras CLI of the default version:

steps:
  - uses: oras-project/setup-oras@v2
  - run: oras version

Advanced Usage

Install a specific version of the oras CLI by specifying the input version without the prefix v. Stable versions (not pre-release versions) are supported and can be found at oras releases.

For example, install oras version v1.0.0.

steps:
  - uses: oras-project/setup-oras@v2
    with:
      version: 1.0.0
  - run: oras version

You can also download oras CLI from any preferred trusted source, by specifying link of the source via url and the SHA256 checksum via checksum. This can be used to download a pre-release version or download from a proxy other than github.com.

For example, install oras version v1.2.0-beta.1.

steps:
  - uses: oras-project/setup-oras@v2
    with:
      url: https://github.com/oras-project/oras/releases/download/v1.2.0-beta.1/oras_1.2.0-beta.1_linux_amd64.tar.gz
      checksum: 37d86f848f7c7c471035cf8218f06372fd72a9fbdca1e10f509738e222b3b2be
  - run: oras version

Authentication

On github.com, the action uses github.token for the download. This gives a higher rate limit. On GitHub Enterprise Server, there is no default token. To use a different token, set token:

steps:
  - uses: oras-project/setup-oras@v2
    with:
      token: ${{ secrets.MY_GITHUB_TOKEN }}
  - run: oras version

The action sends the token only to github.com. It does not send the token to a custom url on a different host. To download without a token, set token to an empty string.

Pinning

Choose how to reference the action based on your update and reproducibility needs:

Reference Behavior
@v2 A mutable, floating tag that moves automatically to each new v2 release, making new ORAS CLI versions available without workflow changes.
@vX.Y.Z (for example, @v2.0.3) A full patch tag for an immutable release cannot be moved or deleted. This guarantee only applies to releases published after release immutability was enabled on 2026-10-17; v2.0.2 and earlier are not immutable.
@<full-commit-sha> A content-addressed reference to an exact commit, providing the strongest pin of these options. Full-length commit SHA pinning is recommended in the GitHub Actions security hardening guide.

To pin to a commit, replace <full-commit-sha> with the full commit SHA from the desired release in this repository and keep its version in a comment:

steps:
  - uses: oras-project/setup-oras@<full-commit-sha> # v2.0.3

Dependabot's github-actions ecosystem can update both SHA pins and their trailing version comments, so pinning to a SHA still allows automated update PRs. See Keeping your actions up to date with Dependabot.

Docs

Documentation for the ORAS CLI is located on the project website.

Code of Conduct

This project has adopted the CNCF Code of Conduct. See CODE_OF_CONDUCT.md for further details.