oras

FIPS 140-3Developer tools

ORAS (OCI Registry As Storage) is a command-line tool for managing OCI artifacts in registries. It enables developers to push, pull, copy, and discover various content types beyond container images.

Quick Start

Pull the latest version of this image from the Ghost registry. Pulling requires authentication — generate a token and run docker login first (see Authentication below).

Authentication

The Ghost catalog is public to browse, but pulling images requires an account. Generate a pull token below (or from your Account → Tokens page) — you'll get a ready-to-paste docker login command, then docker pull works.

The username is generated automatically (it looks like robot$<project>+<auto-id>, not the name you typed) and is included in the docker login command above. The secret is shown only once when you create the token.

Verify Signature

All Ghost images are signed with cosign. Verifying the signature before deployment ensures the image has not been tampered with.

Install cosign via brew install cosign or download from the Sigstore releases page.

Using This Image

Reference this image in your Dockerfile as a base layer:

FIPS 140-3 Compliance

This is a vendor-built FIPS-enabled image: its cryptography runs on FIPS 140-3 validated modules configured by the upstream vendor. You can inspect the image metadata:

Standard	FIPS 140-3
Crypto module	Vendor-configured validated modules
Cryptography	Validated modules only
Use case	Government, regulated industries, compliance workloads

Additional Notes

How to use this image

All examples in this guide use the public image. If you’ve mirrored the repository for your own use (for example, to your Docker Hub namespace), update your commands to reference the mirrored image instead of the public one.

For example:

Public image: registry.ghost-prod.alphabravo.io/ghost-base/<repository>:<tag>
Mirrored image: <your-namespace>/dhi-<repository>:<tag>

For the examples, you must first use docker login registry.ghost-prod.alphabravo.io to authenticate to the registry to pull the images.

This guide provides practical examples for using the ORAS Ghost hardened image to manage OCI artifacts in registries.

Running ORAS Commands

Run the following command and replace <tag> with the image variant you want to run.

# Check ORAS version
docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> version

# Get help for ORAS commands
docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> --help

Authentication

For operations requiring authentication, mount your Docker configuration:

# Using Docker credentials
docker run --rm -v ~/.docker:/home/nonroot/.docker:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> version

# Using specific credential file
docker run --rm \
  -v /path/to/config.json:/home/nonroot/.docker/config.json:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> version

# Create a sample file
echo "Hello, ORAS!" > hello.txt

# Push the file to a registry
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  -v "$(pwd)":/workspace:ro \
  -w /workspace \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> push \
    registry.example.com/myrepo/hello:latest hello.txt

# Push multiple files with media types
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  -v "$(pwd)":/workspace:ro \
  -w /workspace \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> push \
    registry.example.com/myrepo/config:v1.0 \
    config.yaml:application/yaml \
    docs.md:text/markdown

# Push with custom annotations
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  -v "$(pwd)":/workspace:ro \
  -w /workspace \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> push \
    registry.example.com/myrepo/artifact:latest \
    --annotation "version=1.0" \
    --annotation "environment=production" \
    artifact.tar.gz

# Pull all files from an artifact
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  -v "$(pwd)":/workspace \
  -w /workspace \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> pull \
    registry.example.com/myrepo/hello:latest

# Pull only specific files
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  -v "$(pwd)":/workspace \
  -w /workspace \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> pull \
    registry.example.com/myrepo/config:v1.0 \
    --include "*.yaml"

# Copy artifact from one registry to another
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> copy \
    source-registry.com/myrepo/artifact:v1.0 \
    dest-registry.com/myrepo/artifact:v1.0

# Copy and retag
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> copy \
    registry.example.com/myrepo/app:v1.0 \
    registry.example.com/myrepo/app:latest

# List all tags in a repository
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> repo tags \
    registry.example.com/myrepo/artifact

# Discover artifacts attached to an image
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> discover \
    registry.example.com/myrepo/app:latest

# Show the manifest of an artifact
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> manifest fetch \
    registry.example.com/myrepo/artifact:latest

# Package and push Helm chart
helm package mychart/
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  -v "$(pwd)":/workspace:ro \
  -w /workspace \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> push \
    registry.example.com/myrepo/charts/mychart:1.0.0 \
    mychart-1.0.0.tgz:application/vnd.cncf.helm.chart.content.v1.tar+gzip

# Pull Helm chart
docker run --rm \
  -v ~/.docker:/home/nonroot/.docker:ro \
  -v "$(pwd)":/workspace \
  -w /workspace \
  registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> pull \
    registry.example.com/myrepo/charts/mychart:1.0.0

name: Push Artifact with ORAS
on: [push]

jobs:
  push-artifact:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Login to registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Push artifact
        run: |
          docker run --rm \
            -v ~/.docker:/home/nonroot/.docker:ro \
            -v "${{ github.workspace }}":/workspace:ro \
            -w /workspace \
            registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag> push \
              ghcr.io/${{ github.repository }}/config:${{ github.sha }} \
              config.yaml:application/yaml \
              --annotation "git.sha=${{ github.sha }}" \
              --annotation "git.ref=${{ github.ref }}"

push-artifact:
  image: registry.ghost-prod.alphabravo.io/ghost-base/oras:<tag>
  before_script:
    - echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER \
        --password-stdin $CI_REGISTRY
  script:
    - oras push $CI_REGISTRY_IMAGE/config:$CI_COMMIT_SHA
        config.yaml:application/yaml
        --annotation "git.sha=$CI_COMMIT_SHA"
        --annotation "git.ref=$CI_COMMIT_REF_NAME"

oras

oras

Quick Start

Authentication

Verify Signature

Using This Image

FIPS 140-3 Compliance

Additional Notes

How to use this image

Running ORAS Commands

Authentication

Pushing Artifacts

Push a Single File

Push Multiple Files

Push with Annotations

Pulling Artifacts

Pull to Current Directory

Pull Specific Files

Copying Artifacts

Copy Between Registries

Copy with Different Tag

Discovery and Inspection

List Repository Tags

Discover Related Artifacts

Show Artifact Manifest

Working with Helm Charts

Push Helm Chart as OCI Artifact

Pull Helm Chart

CI/CD Integration

GitHub Actions Example

GitLab CI Example

Best Practices

Troubleshooting

Common Issues