### Install ORAS and Chain Commands in CI/CD

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Use the ORAS GitHub Actions Setup action to install ORAS and chain multiple commands in a shell script for CI/CD workflows. This example pulls multiple files and processes the first one.

```yaml
jobs:
  example-job:
    steps:
      - uses: oras-project/setup-oras@v1
      - run: |
          PATH=`oras pull $REGISTRY/$REPO:$TAG --format go-template='{{(first .files).path}}'`
          cat $PATH
```

--------------------------------

### Backup CLI Output

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore.md

Example console output after successfully backing up repository tags.

```console
## <progress_bar>
Found 2 tag(s) in registry-a.k8s.io/kube-apiserver: v1, v2

✓ Pulled  application/vnd.oci.image.config.v1+json                                                               2.26/2.26 KB  100.00%  447ms
  └─ sha256:45a5868eb9f1dfbce42513000964664014789a43310865b0c8461e773e9972b9
✓ Pulled  application/vnd.oci.image.layer.v1.tar+gzip                                                            25.6/25.6 MB  100.00%     4s
  └─ sha256:149362fdfa6e6a5d9f009b896da3be3172c395ba2287b57d4969f3f46e573055
✓ Pulled  application/vnd.cncf.notary.signature                                                                 1.85/1.85 MB  100.00%  898ms
  └─ sha256:9b666bc868511a0f2d33a738a9ff0bd54eb750a72a832e8b59085d22bbdbaac2
✔ Pulled tag v1 and 1 referrer(s)


✓ Pulled  application/vnd.oci.image.config.v1+json                                                               2.24/2.24 KB  100.00%  353ms
  └─ sha256:f9248aac10f2f82e0970222e36cc7b71215b88e974e001282e5cd89797a82218
✓ Pulled  application/vnd.oci.image.layer.v1.tar+gzip                                                            28.3/28.3 MB  100.00%     3s
  └─ sha256:b08e2ff4391ef70ca747960a731d1f21a75febbd86edc403cd1514a099615808
✓ Pulled  application/vnd.cncf.notary.signature                                                                 1.85/1.85 MB  100.00%  890ms
  └─ sha256:854ad9e87ce93dae54ae1699837b2c812d2f373c3fb62625ea6992efa8f023c4
✔ Pulled tag v2 and 1 referrer(s)

## <status output>
Pulled tag v1 and 1 referrer(s)
Pulled tag v2 and 1 referrer(s)
Exporting to backup.tar
Exported to backup.tar (58.8 MB)
Successfully backed up 2 tag(s) from registry-a.k8s.io/kube-apiserver in 5s.
```

--------------------------------

### ORAS Discover Command and Output Sample

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Example command to trigger JSON output and the corresponding JSON response structure.

```bash
oras discover localhost:5000/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01 --format json
```

```json
{
  "reference": "localhost:5000/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01",
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "digest": "sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01",
  "size": 1788,
  "referrers": [
    {
      "reference": "localhost:5000/kubernetes/kubectl@sha256:325129be79f416fe11a9ec44233cfa57f5d89434e6d37170f97e48f7904983e3",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:325129be79f416fe11a9ec44233cfa57f5d89434e6d37170f97e48f7904983e3",
      "size": 788,
      "annotations": {
        "org.opencontainers.image.created": "2024-03-15T22:49:10Z",
        "vnd.oci.artifact.lifecycle.end-of-life.date": "2024-03-15"
      },
      "artifactType": "application/vnd.oci.artifact.lifecycle",
      "referrers": [
        {
          "reference": "localhost:5000/kubernetes/kubectl@sha256:f520330e9f43c05859c532e67a25c9c765b144782ae7b872656192c27fd4e2dd",
          "mediaType": "application/vnd.oci.image.manifest.v1+json",
          "digest": "sha256:f520330e9f43c05859c532e67a25c9c765b144782ae7b872656192c27fd4e2dd",
          "size": 1080,
          "annotations": {
            "io.cncf.notary.x509chain.thumbprint#S256": "[430ecf0685f8018443f8418f5d7134b146f28862116114925713635d5703fb69,9b1894f223d934cbd6575af3c6e1f6096b9221a7da132185f5a5cdc92235b5dc,23ffe2b8bdb9a1711515d4cffda04bc7f793d513c76c243f1020507d8669b7db]",
            "org.opencontainers.image.created": "2024-03-15T22:54:42Z"
          },
          "artifactType": "application/vnd.cncf.notary.signature"
        }
      ]
    },
    {
      "reference": "localhost:5000/kubernetes/kubectl@sha256:a811606b09341bab4bbc0a4deb2c0cb709ec9702635cbe2d36b77d58359ec046"
```

--------------------------------

### View Backup Progress Reporting

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Example output showing progress organized by repository during a multi-repository backup operation.

```console
Backing up 3 repositories...

[1/3] docker.io/library/busybox
  ✓ 1.36.1 (3/3 artifacts, 4.2 MB)
  Repository complete: 3 artifacts, 4.2 MB

[2/3] docker.io/library/alpine
  ✓ 3.19.0 (3/3 artifacts, 7.8 MB)
  Repository complete: 3 artifacts, 7.8 MB

[3/3] docker.io/library/nginx
  ✓ 1.25-alpine (4/4 artifacts, 30.8 MB)
  Repository complete: 4 artifacts, 30.8 MB

Exported to base-images.tar (42.8 MB)
Successfully backed up 3 repositories with 3 tags in 52s
```

--------------------------------

### Handle Backup Errors

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Example of error reporting and recovery suggestions when a repository backup fails.

```console
Error: Failed to backup docker.io/library/postgres
  Reason: Authentication failed
  
Partial backup created: 2 of 3 repositories backed up successfully
  ✓ docker.io/library/busybox (1 tag)
  ✓ docker.io/library/alpine (1 tag)
  ✗ docker.io/library/postgres (authentication required)

Recommendations:
  1. Check credentials for docker.io
  2. Use --username and --password to provide authentication
```

--------------------------------

### Push artifact and attach SBOM using shell variables

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

This example demonstrates chaining ORAS commands in a Unix shell script. It captures the artifact reference from `oras push` into a variable and then uses it with `oras attach` to attach an SBOM. Finally, it uses `notation sign` on the SBOM reference. The `--format go-template='{{.reference}}'` option is used to extract only the artifact reference.

```bash
REFERENCE_A=$(oras push $REGISTRY/$REPO:$TAG hello.txt --format go-template='{{.reference}}')
REFERENCE_B=$(oras attach --artifact-type sbom/example $REFERENCE_A sbom.spdx --format go-template='{{.reference}}') 
notation sign $REFERENCE_B
```

--------------------------------

### Push artifact and attach SBOM using PowerShell

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

This example shows how to chain ORAS commands in Windows PowerShell. It uses `ConvertFrom-Json` to parse the JSON output from `oras push` and `oras attach` to extract the artifact reference. The `--format json --no-tty` options are used to ensure JSON output suitable for parsing.

```powershell
$A=oras push $REGISTRY/$REPO:$TAG hello.txt --format json --no-tty | ConvertFrom-Json
$B=oras attach --artifact-type sbom/example $A.reference sbom.spdx --format json --no-tty | ConvertFrom-Json
notation sign $B.reference
```

--------------------------------

### GET /oras discover (JSON Output)

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Describes the structure of the JSON output returned when executing the discover command with the --format json flag.

```APIDOC
## GET /oras discover

### Description
Returns a recursive JSON object representing the subject image and all associated referrers' manifests.

### Response
#### Success Response (200)
- **reference** (string) - Full reference by digest of the subject image
- **mediaType** (string) - Media type of the subject image
- **digest** (string) - Digest of the subject image
- **size** (integer) - Size of the subject image in bytes
- **referrers** (array) - List of referrers' manifests
  - **reference** (string) - Full reference by digest of the referrer
  - **mediaType** (string) - Media type of the referrer
  - **digest** (string) - Digest of the referrer
  - **size** (integer) - Referrer file size in bytes
  - **artifactType** (string) - Artifact type of the referrer
  - **annotations** (object) - Arbitrary metadata in a referrer
  - **referrers** (array) - List of nested referrers' manifests

#### Response Example
{
  "reference": "localhost:5000/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01",
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "digest": "sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01",
  "size": 1788,
  "referrers": [
    {
      "reference": "localhost:5000/kubernetes/kubectl@sha256:325129be79f416fe11a9ec44233cfa57f5d89434e6d37170f97e48f7904983e3",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:325129be79f416fe11a9ec44233cfa57f5d89434e6d37170f97e48f7904983e3",
      "size": 788,
      "annotations": {
        "org.opencontainers.image.created": "2024-03-15T22:49:10Z"
      },
      "artifactType": "application/vnd.oci.artifact.lifecycle"
    }
  ]
}
```

--------------------------------

### Fetch manifest with output file and template

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Saves the manifest to a file while printing a specific field to the console using a Go template.

```console
$ oras manifest fetch $REGISTRY/$REPO:$TAG --output sample-manifest --format go-template='{{.content.config.mediaType}}'
application/vnd.oci.empty.v1+json
```

--------------------------------

### Promote Artifacts Across Environments

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Backup specific versions from a staging environment to promote them to production.

```bash
# Backup specific versions from staging
oras backup --output staging-promotion.tar \
  --include-referrers \
  staging.mycompany.com/apps/frontend:v2.0 \
  staging.mycompany.com/apps/backend:v2.0 \
  staging.mycompany.com/apps/cache:v2.0
```

--------------------------------

### Prepare E2E Environment

Source: https://github.com/oras-project/oras/blob/main/test/e2e/README.md

Initialize the E2E test environment using the provided preparation script.

```shell
REPO_ROOT=$(git rev-parse --show-toplevel) # REPO_ROOT is root folder of oras CLI code
$REPO_ROOT/test/e2e/scripts/prepare.sh $REPO_ROOT
```

--------------------------------

### Referrer Tree Output with Depth Limit

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Example output of `oras discover` with the `--depth 3` flag, showing the referrer tree limited to three levels.

```console
localhost:5000/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01
├── application/vnd.oci.artifact.lifecycle
│   └── sha256:325129be79f416fe11a9ec44233cfa57f5d89434e6d37170f97e48f7904983e3
│       └── application/vnd.cncf.notary.signature
│           └── sha256:f520330e9f43c05859c532e67a25c9c765b144782ae7b872656192c27fd4e2dd
│               └── vnd/test-annotations
│                   └── sha256:d2cb66a53e4d77488df1f15701554ebb11ffa1cf6eb90f79afa33d3b172f11d2
└── application/vnd.in-toto+json
    └── sha256:a811606b09341bab4bbc0a4deb2c0cb709ec9702635cbe2d36b77d58359ec046
        └── application/vnd.cncf.notary.signature
            └── sha256:04723fd7d00df77c6f226b907667396554bf9418dc48a7a04feb5ff24aa0b9ec
                └── vnd/test-annotations
                    └── sha256:d2cb66a53e4d77488df1f15701554ebb11ffa1cf6eb90f79afa33d3b172f11d2
```

--------------------------------

### Pull Artifact with JSON Output

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Use `oras pull` with `--format json` to get detailed descriptor metadata for downloaded files in JSON format. This is useful for inspecting artifact layers.

```bash
oras pull $REGISTRY/$REPO:$TAG --artifact-type example/sbom sbom.spdx  --artifact-type example/vul-scan vul-scan.json --format json
```

--------------------------------

### Show Manifest Details

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Fetches and displays the manifest for a specific tag in the backup.

```bash
oras manifest fetch --oci-layout-path base-images.tar docker.io/library/busybox:1.36.1
```

--------------------------------

### List All Repositories in JSON Format

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

List all repositories in a registry using `oras repo ls` with the `--format json` flag. The output includes the registry name and a list of repositories.

```console
$ oras repo ls localhost:5000 --format json
{
  "registry": "localhost:5000",
  "repositories": [
    "dev/foo",
    "dev/bar",
    "test/foo"
  ]
}
```

--------------------------------

### Configure GOPATH for E2E

Source: https://github.com/oras-project/oras/blob/main/test/e2e/README.md

Add the Go binary directory to the system PATH if ginkgo is not found.

```shell
PATH+=:$(go env GOPATH)/bin
```

--------------------------------

### Display ORAS version and environment details

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/diagnose-experience.md

Run the version command to output OS, architecture, and build information for debugging purposes.

```bash
$ oras version

ORAS Version:    1.2.0+Homebrew
Go version:      go1.22.3
OS/Arch:         linux/amd64
Git commit:      xxxxxxxxxxxx
Git tree state:  clean
```

--------------------------------

### Create multi-arch image index from local and registry sources

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/multi-arch-image-mgmt.md

Creates a multi-arch image index by combining architecture-specific images that may be sourced from both local OCI layouts and a registry. It's recommended that all variants reside in the same repository for registry compatibility.

```console
$ oras manifest index create example:v1 v1-linux-amd64 v1-linux-arm64 --oci-layout
Fetching  v1-linux-amd64 
Fetched   sha256:42c524c48e0672568dbd2842d3a0cb34a415347145ee9fe1c8abaf65e7455b46 v1-linux-amd64 
Fetching  v1-linux-arm64
Fetched   sha256:965945e1a08031a63d5970c1da7c39af231c36e4c0a5a3cc276d02a3e06513ee v1-linux-arm64 
Packed    edb5bc1f0b5c application/vnd.oci.image.index.v1+json
Pushed    [oci-layout] example:v1
Digest: sha256:edb5bc1f0b5c21e9321b34e50c92beae739250fb88409056e8719d9759f6b5b4
```

--------------------------------

### Backup Image with Referrers

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore.md

Create a snapshot of an image and its associated referrers for offline transfer.

```bash
oras backup registry-a.k8s.io/kube-apiserver:v1 --include-referrers --output airgap-snapshot.tar
```

--------------------------------

### Fetch manifest with custom Go template

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Uses a Go template to filter and format specific metadata fields.

```bash
oras manifest fetch $REGISTRY/$REPO:$TAG --format go-template --template '{{ toPrettyJson .content.config }}'
```

```json
{
  "digest": "sha256:b6f50765242581c887ff1acc2511fa2d885c52d8fb3ac8c4bba131fd86567f2e",
  "mediaType": "application/vnd.docker.container.image.v1+json",
  "size": 3362
}
```

--------------------------------

### Fetch manifest with JSON formatting

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Prints the artifact metadata in a prettified JSON format.

```bash
oras manifest fetch $REGISTRY/$REPO:$TAG --format json
```

```json
{
  "reference": " $REGISTRY/$REPO@sha256:8be4c36a29979c72fdd225654498791fb381a7dd8332ade1981274a16220fe1c",
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:8be4c36a29979c72fdd225654498791fb381a7dd8332ade1981274a16220fe1c",
  "artifactType": "application/vnd.unknown.artifact.v1",
  "content": {
    "config": {
      "mediaType": "application/vnd.oci.empty.v1+json",
      "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "size": 2
    },
    "layers": [
      {
        "mediaType": "application/vnd.oci.image.layer.v1.tar",
        "digest": "sha256:6cb759c4296e67e35b0367f3c0f51dfdb776a0c99a45f39d0476e43d82696d65",
        "size": 14477,
        "annotations": {
          "org.opencontainers.image.title": "sbom.spdx"
        }
      },
      {
        "mediaType": "application/vnd.oci.image.layer.v1.tar",
        "digest": "sha256:54c0e84503c8790e03afe34bfc05a5ce45c933430cfd9c5f8a99d2c89f1f1b69",
        "size": 6639,
        "annotations": {
          "org.opencontainers.image.title": "scan-test-verify-image.json"
        }
      }
    ],
    "annotations": {
      "org.opencontainers.image.created": "2023-12-15T09:41:54Z"
    }
  }
}
```

--------------------------------

### List Repositories in Backup

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Lists repositories contained within an OCI Image Layout backup, optionally filtered by namespace.

```bash
oras repo ls --oci-layout-path base-images.tar
```

```bash
oras repo ls --oci-layout-path base-images.tar docker.io/library
```

--------------------------------

### View artifact command usage

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/multi-arch-image-mgmt.md

Displays the usage and aliases for the manifest fetch command.

```bash
Usage:
  oras manifest fetch [flags] <name>{:<tag>|@<digest>}

Aliases:
  fetch, get, show
```

--------------------------------

### Create multi-arch image index from registry

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/multi-arch-image-mgmt.md

Creates a multi-arch image index by combining two architecture-specific images stored in a registry. The resulting image index is then pushed to the specified registry.

```console
$ oras manifest index create localhost:5000/example:v1 v1-linux-amd64 v1-linux-arm64
Fetching  v1-linux-amd64 
Fetched   sha256:42c524c48e0672568dbd2842d3a0cb34a415347145ee9fe1c8abaf65e7455b46 v1-linux-amd64 
Fetching  v1-linux-arm64
Fetched   sha256:965945e1a08031a63d5970c1da7c39af231c36e4c0a5a3cc276d02a3e06513ee v1-linux-arm64 
Packed    edb5bc1f0b5c application/vnd.oci.image.index.v1+json
Pushed    localhost:5000/example:v1
Digest: sha256:edb5bc1f0b5c21e9321b34e50c92beae739250fb88409056e8719d9759f6b5b4
```

--------------------------------

### Export and Import Images with Docker

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-scenarios.md

Demonstrates the traditional workflow for moving images between isolated environments using tar archives.

```console
# Build image in development
docker build -t myapp:v1 .

# Export to a tar file
docker save myapp:v1 -o myapp.tar

# Manually transfer the tar file to test or production environment (e.g., via secure file transfer)

# Load image in the target environment
docker load -i myapp.tar

# Tag and push to the target environment registry
docker tag myapp:v1 registry.test.example.com/myapp:v1
docker push registry.test.example.com/myapp:v1
```

--------------------------------

### Perform Multi-Registry Backups

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Use separate backup commands for different registries to manage authentication and organization effectively.

```bash
# Backup from Docker Hub
oras backup --output docker-hub-backup.tar \
  docker.io/library/nginx:1.25-alpine \
  docker.io/library/redis:7.2-alpine

# Backup from private registry with authentication
oras backup --output private-backup.tar \
  --username admin --password-stdin \
  registry.mycompany.com/app/frontend \
  registry.mycompany.com/app/backend
```

--------------------------------

### List Repository Tags

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Lists all tags available for a specific repository within the backup.

```bash
oras repo tags --oci-layout-path base-images.tar docker.io/library/busybox
```

--------------------------------

### Backup with full reference

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Use the --full-reference flag to store the complete reference path during a single-repository backup.

```bash
oras backup --output backup.tar --full-reference docker.io/library/alpine:latest
```

--------------------------------

### Multi-Repository Backup Syntax

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Use this syntax to backup artifacts from multiple repositories in the same registry into a single OCI layout. Ensure all repository references are from the same registry.

```bash
oras backup [flags] --output <path> <registry>/<repo1>[:<tags>] <registry>/<repo2>[:<tags>] ...
```

--------------------------------

### Create multi-arch image index in OCI layout with annotations

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/multi-arch-image-mgmt.md

Combines two architecture-specific images into an image index within a local OCI image layout. This command also allows adding custom annotations to the image index.

```console
$ oras manifest index create layout-dir:v1 v1-linux-amd64 v1-linux-arm64 --oci-layout --annotation "com.example.key=value" 
Fetching  v1-linux-amd64 
Fetched   sha256:42c524c48e0672568dbd2842d3a0cb34a415347145ee9fe1c8abaf65e7455b46 v1-linux-amd64 
Fetching  v1-linux-arm64
Fetched   sha256:965945e1a08031a63d5970c1da7c39af231c36e4c0a5a3cc276d02a3e06513ee v1-linux-arm64 
Packed    edb5bc1f0b5c application/vnd.oci.image.index.v1+json
Pushed    [oci-layout] layout-dir:v1
Digest: sha256:edb5bc1f0b5c21e9321b34e50c92beae739250fb88409056e8719d9759f6b5b4
```

--------------------------------

### View generated manifest file

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Displays the contents of the manifest file generated by the fetch command.

```console
$ cat sample-manifest
{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","artifactType":"application/vnd.unknown.artifact.v1","config":{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:6cb759c4296e67e35b0367f3c0f51dfdb776a0c99a45f39d0476e43d82696d65","size":14477,"annotations":{"org.opencontainers.image.title":"sbom.spdx"}},{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:54c0e84503c8790e03afe34bfc05a5ce45c933430cfd9c5f8a99d2c89f1f1b69","size":6639,"annotations":{"org.opencontainers.image.title":"scan-test-verify-image.json"}}],"annotations":{"org.opencontainers.image.created":"2023-12-15T09:41:54Z"}}
```

--------------------------------

### Run E2E Tests

Source: https://github.com/oras-project/oras/blob/main/test/e2e/README.md

Execute the full E2E test suite from the project root.

```shell
make teste2e
```

--------------------------------

### Migrate Repositories Between Registries

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Perform a two-step migration by backing up from a source registry and restoring to a destination registry.

```bash
# Step 1: Backup from Docker Hub
oras backup --output migration.tar \
  --include-referrers \
  docker.io/library/busybox:1.36.1 \
  docker.io/library/alpine:3.19.0

# Step 2: Restore to private registry
oras restore --input migration.tar \
  registry.mycompany.com/base-images
```

--------------------------------

### Create Multi-Platform Artifacts

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/multi-arch-image-mgmt.md

Various commands for creating multi-platform indexes using tags, digests, annotations, and custom artifact types.

```bash
# Create an index from source manifests tagged 'linux-amd64' and 'linux-arm64', and push without tagging:
oras manifest index create localhost:5000/hello linux-amd64 linux-arm64

# Create an index from source manifests tagged 'linux-amd64' and 'linux-arm64', and push with the tag 'v1':
oras manifest index create localhost:5000/hello:v1 linux-amd64 linux-arm64

# Create an index from source manifests using both tags and digests, and push with tag 'v1':
oras manifest index create localhost:5000/hello:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9

# Create an index and push it with multiple tags:
oras manifest index create localhost:5000/hello:tag1,tag2,tag3 linux-amd64 linux-arm64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9

# Create and push an index with annotations:
oras manifest index create localhost:5000/hello:v1 linux-amd64 --annotation "key=val"

# Create an index with a specified artifact type:
oras manifest index create --artifact-type="application/vnd.example+type" localhost:5000/hello linux-amd64

# Create an index and push to an OCI image layout folder 'layout-dir' and tag with 'v1':
oras manifest index create layout-dir:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9 --oci-layout

# Create an index and save it locally to index.json, auto push will be disabled:
oras manifest index create --output index.json localhost:5000/hello linux-amd64 linux-arm64

# Create an index and output the index to stdout, auto push will be disabled:
oras manifest index create localhost:5000/hello linux-arm64 --output - --pretty
```

--------------------------------

### Backup Multiple Repositories

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Backs up multiple utility images from a registry into a single tar file, including referrers.

```bash
oras backup --output base-images.tar \
  --include-referrers \
  docker.io/library/busybox:1.36.1 \
  docker.io/library/alpine:3.19.0 \
  docker.io/library/nginx:1.25-alpine
```

--------------------------------

### Restore Image from Backup

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore.md

Restore an image and its referrers from a local tarball to a target registry.

```console
oras restore registry-b.k8s.io/kube-apiserver:v1 --input airgap-snapshot.tar
```

--------------------------------

### Direct Restore to Target Registry

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Restores all backed-up repositories to a target registry, preserving original repository paths. Use this for a straightforward full restore.

```bash
oras restore --input base-images.tar registry.mycompany.com
```

```console
Loaded backup archive: base-images.tar (42.8 MB)
Found 3 repository(ies) with 3 tag(s):
  - docker.io/library/busybox: 1.36.1
  - docker.io/library/alpine: 3.19.0
  - docker.io/library/nginx: 1.25-alpine

Restoring to registry.mycompany.com...
✓ Pushed application/vnd.oci.image.layer.v1.tar+gzip                        2.11/2.11 MB 100.00%    4s
✓ Pushed application/vnd.oci.image.manifest.v1+json                           610/610  B 100.00%  52ms
Restored registry.mycompany.com/library/busybox:1.36.1 with 0 referrer(s)

✓ Pushed application/vnd.docker.image.rootfs.diff.tar.gzip                  3.19/3.19 MB 100.00%    6s
✓ Pushed application/vnd.docker.distribution.manifest.v2+json                 528/528  B 100.00%  48ms
Restored registry.mycompany.com/library/alpine:3.19.0 with 0 referrer(s)

✓ Pushed application/vnd.docker.image.rootfs.diff.tar.gzip                  9.56/9.56 MB 100.00%   14s
✓ Pushed application/vnd.docker.distribution.manifest.v2+json                 1.5/1.5 KB 100.00%  51ms
Restored registry.mycompany.com/library/nginx:1.25-alpine with 0 referrer(s)

Successfully restored 3 tag(s) from 3 repository(ies) to registry.mycompany.com in 28s.
```

--------------------------------

### List Repository Tags

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore.md

Retrieve all tags associated with a specific repository.

```console
$ oras repo tags registry-b.k8s.io/kube-apiserver
v1
v2
```

--------------------------------

### Repository Consolidation

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Backs up multiple legacy repositories and restores them into a unified structure using mapping rules.

```bash
# Backup scattered repositories
oras backup --output legacy-apps.tar \
  legacy-registry.mycompany.com/team-a/app-1 \
  legacy-registry.mycompany.com/team-b/app-2 \
  legacy-registry.mycompany.com/team-c/app-3 \
  legacy-registry.mycompany.com/shared/utils

# Restore to unified structure
oras restore --input legacy-apps.tar --rules consolidation-rules.json
```

```jsonc
{
  "mappings": [
    {
      "source": "legacy-registry.mycompany.com/team-a/app-1",
      "target": "registry.mycompany.com/services/app-1"
    },
    {
      "source": "legacy-registry.mycompany.com/team-b/app-2",
      "target": "registry.mycompany.com/services/app-2"
    },
    {
      "source": "legacy-registry.mycompany.com/team-c/app-3",
      "target": "registry.mycompany.com/services/app-3"
    },
    {
      "source": "legacy-registry.mycompany.com/shared/utils",
      "target": "registry.mycompany.com/libs/common"
    }
  ]
}
```

--------------------------------

### Disaster Recovery Workflow

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Automates daily backups and demonstrates restoration procedures including dry-run verification.

```bash
# Daily backup script for critical repositories
DATE=$(date +%Y%m%d)
oras backup --output /backups/critical-apps-$DATE.tar \
  --include-referrers \
  registry.mycompany.com/production/frontend \
  registry.mycompany.com/production/backend \
  registry.mycompany.com/production/database

# Retention: Keep last 7 days
find /backups -name "critical-apps-*.tar" -mtime +7 -delete

# After incident, restore specific version
oras restore --input /backups/critical-apps-20251120.tar \
  registry.mycompany.com/production \
  --dry-run  # Verify first

# Then actual restore
oras restore --input /backups/critical-apps-20251120.tar \
  registry.mycompany.com/production
```

--------------------------------

### Attach artifact with --distribution-spec v1.1-referrers-tag

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/compatibility-mode.md

Enable maximum backward compatibility by using the referrers tag schema.

```bash
oras attach localhost:5000/hello-world:v1 \
  --artifact-type sbom/example \
  --distribution-spec v1.1-referrers-tag \
  sbom.json
```

--------------------------------

### Attach artifact with --distribution-spec v1.1-referrers-api

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/compatibility-mode.md

Enforce strict compatibility by requiring OCI v1.1 compliance and Referrers API support.

```bash
oras attach localhost:5000/hello-world:v1 \
  --artifact-type sbom/example \
  --distribution-spec v1.1-referrers-api \
  sbom.json
```

--------------------------------

### Attach files with JSON output

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Attaches multiple files to an image and displays the referrer descriptor metadata in JSON format.

```bash
oras attach $REGISTRY/$REPO:$TAG --artifact-type example/report-and-sbom vul-report.json:example/vul-scan sbom.spdx:example/sbom --format json
```

```json
{
  "reference": "$REGISTRY/$REPO@sha256:0afd0f0c35f98dcb607de0051be7ebefd942eef1e3a6d26eefd1b2d80f2affbe",
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:0afd0f0c35f98dcb607de0051be7ebefd942eef1e3a6d26eefd1b2d80f2affbe",
  "size": 923,
  "annotations": {
    "org.opencontainers.image.created": "2023-12-15T08:59:21Z"
  },
  "artifactType": "example/report-and-sbom"
}
```

--------------------------------

### Restore CLI Command

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore.md

Command to restore images and referrer artifacts from a local backup file to a target registry.

```console
oras restore --input backup.tar registry-b.k8s.io/kube-apiserver
```

--------------------------------

### Restore with full reference auto-remap

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Demonstrates how oras restore automatically handles remapping when a full reference is present in the backup.

```bash
# Backup with full reference
oras backup --output backup.tar --full-reference docker.io/library/alpine:latest

# Restore to different registry (auto-remaps)
oras restore --input backup.tar registry.mycompany.com/alpine:latest
# Result: docker.io/library/alpine:latest → registry.mycompany.com/alpine:latest
```

--------------------------------

### oras manifest fetch (show)

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/multi-arch-image-mgmt.md

Fetches and displays an OCI image manifest or index.

```APIDOC
## oras manifest fetch (show)

### Description
Fetches and displays an OCI image manifest or index. The `show` alias is provided for intuitive viewing.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Usage
```bash
oras manifest fetch [flags] <name>{:<tag>|@<digest>}
```

### Aliases
- `fetch`
- `get`
- `show`

### Parameters

#### Path Parameters
- **name** (string) - Required - The name of the artifact.
- **tag** (string) - Optional - The tag of the artifact.
- **digest** (string) - Optional - The digest of the artifact.

### Request Body
Not applicable (CLI command)

### Response
Displays the content of the fetched manifest or index.
```

--------------------------------

### Repository Reference Format

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Specifies the format for referencing repositories and their tags during multi-repository backup. Tags can be a comma-separated list.

```bash
<registry>/<repository>[:<tag1>[,<tag2>...]]
```

--------------------------------

### Incorrect Image Backup and Restore Workflow

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-scenarios.md

Demonstrates an incorrect approach to backing up and restoring images using standard pull/push commands, which fails to preserve referrers and image structure.

```console
# Pull an image and save it locally as a tarball (incorrect usage)
oras pull foo.example.com/app/backend:v1.0.0 -o backend.tar

# Extract the tarball and modify it locally
tar -xf backend.tar

# Push the modified image back to the registry
oras push foo.example.com/app/backend:v1.0.1 ./extracted
```

--------------------------------

### Push Folder with Custom Output Format

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

Use `oras push` with a Go template format string to extract specific fields like reference and media type when pushing a folder. This allows for targeted output for scripting.

```bash
oras push $REGISTRY/$REPO:$TAG sample-folder --format go-template='{{.reference}}, {{.mediaType}}'
```

--------------------------------

### Backward Compatibility Operations

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Standard single-repository backup and restore commands that remain unchanged.

```bash
# These continue to work exactly as before
oras backup --output backup.tar registry.com/repo:tag
oras restore --input backup.tar registry.com/repo:tag
oras backup --output backup.tar registry.com/repo
oras restore --input backup.tar registry.com/repo
```

--------------------------------

### Restore Multi-Repository Backups

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Syntax for restoring backups using direct, selective, or rule-based approaches.

```bash
oras restore [flags] --input <path> <target-registry>
```

```bash
oras restore [flags] --input <path> <target-repo1> <target-repo2> [<target-repo3>...]
```

```bash
oras restore [flags] --input <path> --rules <rules-file>
```

--------------------------------

### Create a multi-platform artifact

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/multi-arch-image-mgmt.md

Commands for creating a multi-platform artifact by generating an index manifest from source manifests. Supports pushing to a registry or saving to a local OCI layout.

```APIDOC
## oras manifest index create

### Description
Creates a multi-platform artifact by generating an index manifest from source manifests. This command can push the index to a registry or save it to a local OCI layout.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters
#### Path Parameters
- **target** (string) - Required - The target registry or OCI layout path (e.g., `localhost:5000/hello`, `layout-dir:v1`).
- **manifests** (string) - Required - One or more source manifests (tags or digests) to include in the index.

#### Query Parameters
None

#### Request Body
None

#### Options
- **--oci-layout** - Optional - Treat the target as an OCI image layout.
- **--artifact-type** (string) - Optional - Set the `artifactType` for the index manifest. If not provided, it may be inferred from child manifests or default to `application/vnd.oci.image.index.v1+json`.
- **--annotation** (string) - Optional - Add an annotation to the index manifest (key=val).
- **--output** (string) - Optional - Output the index manifest to a file or stdout. If specified, auto-push is disabled.
- **--pretty** - Optional - Pretty-print the output when using `--output -`.

### Request Example
```bash
# Create an index from source manifests tagged 'linux-amd64' and 'linux-arm64', and push without tagging:
oras manifest index create localhost:5000/hello linux-amd64 linux-arm64

# Create an index and push to an OCI image layout folder 'layout-dir' and tag with 'v1':
oras manifest index create layout-dir:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9 --oci-layout

# Create an index with a specified artifact type:
oras manifest index create --artifact-type="application/vnd.example+type" localhost:5000/hello linux-amd64
```

### Response
#### Success Response (200)
- **digest** (string) - The digest of the created index manifest.
- **tags** (array) - List of tags applied to the index manifest.

#### Response Example
```json
{
  "digest": "sha256:6a165dbdc7a24e677e7ec0748457604ba143ae74e5b27a19789b88b41bf49bb0",
  "tags": ["v1"]
}
```
```

--------------------------------

### Perform Dry-Run Restore

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/backup-restore-multi.md

Previews the restore operation without applying changes to the registry.

```bash
oras restore --input base-images.tar registry.mycompany.com --dry-run
```

--------------------------------

### List Repository Tags in JSON Format

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

List all available tags for a repository using `oras repo tags` with the `--format json` flag. The output is a JSON object containing a list of tags.

```console
$ oras repo tags localhost:5000/test --format json
{
  "tags": [
    "latest",
    "v1.0",
    "v1.1"
  ]
}
```

--------------------------------

### Pushed Folder Reference and Media Type

Source: https://github.com/oras-project/oras/blob/main/docs/proposals/formatted-output.md

The output from `oras push` with a Go template format string displays only the requested fields, such as the artifact's reference and media type, separated by a comma and space.

```console
$REGISTRY/$REPO@sha256:85438e6598bf35057962fff34399a362d469ca30a317939427fca6b7a289e70d, application/vnd.oci.image.manifest.v1+json
```

--------------------------------

### Debug E2E Specs via Go Test

Source: https://github.com/oras-project/oras/blob/main/test/e2e/README.md

Run specific test suites natively using the go test command for easier debugging.

```shell
go test oras.land/oras/test/e2e/suite/${suite_name}
```