From 665b1cb1058168d5e6655071f26896938679ee72 Mon Sep 17 00:00:00 2001
From: Valentin Delaye <jonesbusy@users.noreply.github.com>
Date: Wed, 18 Feb 2026 13:13:28 +0100
Subject: [PATCH] Add some documentation about registries.conf

Signed-off-by: Valentin Delaye <jonesbusy@users.noreply.github.com>
---
 README.md | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 53972f26..256ff5ff 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@ Then on your `pom.xml`
 
 ## Authentication
 
-Using default existing login existing credentials (e.g. `~/.docker/config.json`)
+Using default existing login existing credentials (e.g. `~/.docker/config.json`) or `$XDG_RUNTIME_DIR/containers/auth.json` (no support for repository prefix yet)
 
 ```java
 Registry registry = Registry.builder().defaults().build();
@@ -80,6 +80,33 @@ Using username and password
 Registry registry = Registry.builder().defaults("username", "password").build();
 ```
 
+## Registries configuration
+
+Since version `0.4.0` ORAS Java SDK partially support the `registries.conf` (https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)
+
+For example
+
+```toml
+# Use registry for unqualified images
+short-name-mode = "enforcing" # Default if not set. Unsafe if `disabled` and multiple unqualified-search-registries are set
+unqualified-search-registries = ["docker.io"]
+
+# Rewrite a location with prefix
+[[registry]]
+prefix = "docker.io/bitnami"
+location = "docker.io/bitnamilegacy"
+
+# Block a registry/repository via prefix
+[[registry]]
+prefix = "gcr.io"
+blocked = true
+
+# Set registry unsecure
+[[registry]]
+location = "localhost:5000"
+insecure = true
+```
+
 ### Push an Artifact
 
 ```java