Activity

1. Jordan Borean (jborean93)

   added

   Needs-Triage

   on Feb 20, 2026
2. jborean93 commented on Feb 20, 2026

   

   Jordan Borean (jborean93)

   on Feb 20, 2026

   Author

   More actions

   This and the authentication issues are the only 2 blockers that stop PSResourceGet from installing packages from other OCI registries like GHCR. I've been tracking the progress and other general information around this at https://github.com/jborean93/PowerShell-PublishTest?tab=readme-ov-file#github-container-registry-oci.
3. jborean93 commented on Feb 22, 2026

   

   Jordan Borean (jborean93)

   on Feb 22, 2026

   Author

   More actions

   I've tried to write up more around the problem and the potential solutions for this issue. I'm happy to do the work it would just need a consensus on the way forward before I do so.

   OCI Registry Package Prefixes: Current Issues and Proposed Solutions

   Summary

   PSResourceGet cannot properly install packages with a prefix before the module name. This prefix may be required by the OCI registry (like GHCR) or just published with that prefix. This document outlines:

   • The Problem: Can find packages at ghcr.io/user/packagename but then tries to download from ghcr.io/packagename
   • Root Cause: OCI manifests store the module name without the namespace prefix, but PSResourceGet needs the full path for API operations
   • Current Workaround: MAR has a hardcoded psresource/ prefix, but this doesn't scale to other registries
   • Potential Solutions:
     • Parse prefix from requested package name Install-PSResource -Name ghuser/package (simplest UX wise)
     • Add -Prefix parameter to Register-PSResourceRepository (requires multiple repos per namespace)
     • Add -Prefix to other cmdlets like Install-PSResource rather than a per repository configuration

   Glossary

   OCI Registry Namespacing Concepts

   • Root Namespace - Packages directly under the registry (e.g., myacr.azurecr.io/packagename)

     • Some registries allow this (ACR)
     • Some registries prohibit this (GHCR)

   • Namespace/Prefix - Organizational grouping before the package name

     • Examples: ghcr.io/username/packagename, docker.io/organization/imagename
     • Acts as a scope or owner identifier
     • Required by GHCR and possibly others

   • Registry Path - The full path used in OCI API calls

     • Format: {namespace}/{packagename} or just {packagename} for root namespace
     • Example: In ghcr.io/ghuser/mymodule, the repository path is ghuser/mymodule

   • Module Name - The PowerShell module name from the manifest (.psd1)

     • Stored in OCI manifest under the nupkg layer annotation as org.opencontainers.image.title
     • Does NOT include namespace prefix
     • Example: MyModule (not ghuser/MyModule)
     • Dependencies will also not include any prefix

   Key Registries and Their Namespace Requirements

   Registry	Root Namespace Allowed?	Example Path
   MAR (Microsoft Artifact Registry)	✅ Yes (pwsh res under psresource/ by design)	mcr.microsoft.com/psresource/packagename
   ACR (Azure Container Registry)	✅ Yes (optional namespaces)	myregistry.azurecr.io/packagename or myregistry.azurecr.io/namespace/packagename
   GHCR (GitHub Container Registry)	❌ No - Requires user/org namespace	ghcr.io/username/packagename

   Current Behavior

   What Works Today

   Microsoft Artifact Registry (MAR):

   # PSResourceGet has hardcoded support for MAR's psresource/ prefix
   Install-PSResource -Name MyModule -Repository MAR
   # Internally translates to: mcr.microsoft.com/psresource/mymodule

   This works because:

   1. MAR always uses the psresource/ prefix for PowerShell resources
   2. Code specifically checks for MAR URI and prepends the prefix
   3. See PrependMARPrefix() in ContainerRegistryServerAPICalls.cs

   Azure Container Registry (ACR) with no prefix:

   Install-PSResource -Name MyModule -Repository MyACR
   # Interally translates to: myacr.azurecr.io/mymodule

   What Breaks

   GitHub Container Registry (GHCR):

   # Try to install (FAILS)
   Install-PSResource -Name 'ghuser/MyModule' -Repository GHCR
   
   # What happens internally:
   # 1. Find operation: GET ghcr.io/v2/ghuser/mymodule/tags/list ✅ Works
   # 2. Get manifest: GET ghcr.io/v2/ghuser/mymodule/manifests/1.0.0 ✅ Works
   # 3. Read manifest, extracts module name: "MyModule" (prefix stripped)
   # 4. Download blob: GET ghcr.io/v2/mymodule/blobs/sha256:... ❌ FAILS
   #    Should be: GET ghcr.io/v2/ghuser/mymodule/blobs/sha256:...

   Azure Container Registry (ACR) published under explicit prefix:

   Install-PSResource -Name testprefix/publishtest -Repository MyACR

   Same problem occurs where it can find the package tags and manifest but then strips off the package during the install stage.

   Root Cause Analysis

   The OCI Manifest Problem

   When PSResourceGet retrieves the OCI manifest, it extracts the module name from the org.opencontainers.image.title annotation:

   {
     "schemaVersion": 2,
     "layers": [{
       "digest": "sha256:abc123...",
       "annotations": {
         "org.opencontainers.image.title": "MyModule",
         "resourceType": "Nupkg"
       }
     }]
   }

   The Download Problem

   For subsequent operations (downloading blobs, pulling dependencies), PSResourceGet uses the module name from the manifest. But OCI API calls need the full repository path:

   # What PSResourceGet does:
   GET /v2/mymodule/blobs/sha256:abc123
   
   # What it should do:
   GET /v2/ghuser/mymodule/blobs/sha256:abc123
   

   The Dependency Problem

   Dependencies listed in the module manifest don't include namespace prefixes:

   # MyModule.psd1
   @{
       ModuleName = 'MyModule'
       RequiredModules = @('DependencyModule')  # No prefix!
   }

   When installing ghuser/MyModule, PSResourceGet needs to find ghuser/DependencyModule, but the dependency is just listed as DependencyModule.

   Proposed Solutions

   Solution 1: Parse Prefix from Package Name

   Concept: When a user provides a package name with a /, treat the prefix portion as a namespace to use for all operations.

   Implementation:

   Install-PSResource -Name 'ghuser/MyModule' -Repository GHCR
   
   # Internally:
   # 1. Parse: prefix = 'ghuser', moduleName = 'MyModule'
   # 2. Find: ghcr.io/ghuser/mymodule ✅
   # 3. Download: ghcr.io/ghuser/mymodule ✅
   # 4. Dependencies: ghcr.io/ghuser/{dependencyname} ✅

   Code changes:

   • Parse package name on entry to install/find operations
   • Store prefix in context passed through the operation
   • Prepend prefix to all OCI API calls (tags, manifests, blobs)
   • Prepend prefix when resolving dependencies

   Pros:

   • ✅ Minimal breaking changes
   • ✅ No new parameters required
   • ✅ Intuitive user experience (name matches registry path)
   • ✅ Works immediately without repository registration per namespace/prefix

   Cons:

   • ❌ Only works when user explicitly includes prefix in name
   • ❌ User must know the namespace structure
   • ❌ MAR still has the internal code to automatically add the psresource/ prefix

   Example usage:

   # Works - explicit prefix
   Install-PSResource -Name 'ghuser/MyModule' -Repository GHCR
   
   # Doesn't work - find without knowing prefix
   Find-PSResource -Name 'MyModule' -Repository GHCR
   # How does it know to look in ghuser/ vs other users?

   Solution 2: Repository-Level Prefix Configuration

   Concept: Add a -Prefix/-ResourcePrefix/-ModulePrefix parameter to Register-PSResourceRepository that gets prepended to all package operations.

   Implementation:

   # Register repository with prefix
   Register-PSResourceRepository -Name MyGHCR -Uri 'https://ghcr.io' -Prefix 'ghuser'
   
   # Use without specifying prefix in name
   Install-PSResource -Name MyModule -Repository MyGHCR
   # Internally uses: ghcr.io/ghuser/mymodule

   Code changes:

   • Add a Prefix property to PSRepositoryInfo
   • Update Register-PSResourceRepository to accept -Prefix parameter
   • Modify all OCI API calls to prepend prefix from repository info
   • Remove the MAR specific checks and just have the psresource prefix added as part of the repository registration
   • Obsoletes -ModulePrefix in Publish-PSResource as the prefix can be derived from the repo registration instead

   Pros:

   • ✅ Works for all operations (install, publish)
   • ✅ User doesn't need to specify prefix in package names during install
   • ✅ Explicit configuration - clear what namespace is being used
   • ✅ Supports both prefixed and non-prefixed registries
   • ✅ Removes hardcoding of MAR in ContainerRegistryServerAPICalls.cs and instead makes it a repository configuration

   Cons:

   • ❌ Requires separate repository registration for each namespace even if for the same registry
   • ❌ A disconnect between what people see the package name as online vs what they use with PSResourceGet
   • ❌ Find-PSResource uses the /v2/_catalog API which does not support server side filtering, it would have to filter it in the cmdlet
   • ❌ Still have an overlapping functionality of Publish-PSResource -ModulePrefix and repository prefix configuration

   Example usage:

   # Register for your namespace
   Register-PSResourceRepository -Name MyGHCR -Uri 'https://ghcr.io' -Prefix 'ghuser'
   
   # Register for organization namespace
   Register-PSResourceRepository -Name OrgGHCR -Uri 'https://ghcr.io' -Prefix 'myorg'
   
   # Clean usage - no prefix in names
   Install-PSResource -Name MyModule -Repository MyGHCR
   Publish-PSResource -Path ./MyModule -Repository MyGHCR

   Solution 3: Add -Prefix Parameter for Install-PSResource

   Concept: Keep -Name as the module name but add -Prefix parameter to specify a prefix on Install-PSResource

   Implementation:

   Install-PSResource -Name MyModule -Prefix ghuser -Repository GHCR
   # All operations will use the package `ghuser/mymodule`
   # Prefix will apply to any dependencies found for that module as well

   Code changes:

   • Add -Prefix parameter to Install-PSResource
   • Prepend prefix to the package name with prefix/packagename for any API requests

   Pros:

   • ✅ Automatic - works without extra configuration
   • ✅ Mirrors the existing -ModulePrefix exposed in Publish-PSResource
   • ✅ No extra parsing logic on the name
   • ✅ No repository re-registration needed

   Cons:

   • ❌ Messier to have the user split the prefix themselves
   • ❌ Still keeps the hardcoded internal logic for MAR to be auto prefixed

   Dependency Resolution Strategy

   None of these solutions support finding dependencies in other repositories. I don't think this should be solved as dependencies for a package should all be contained in the same registry/namespace.

   Migration Path for MAR

   Current hardcoded MAR behavior should be preserved for backwards compatibility but instead of the prefix work being done in ContainerRegistryServerAPICalls.cs the prefix could be applied using the same mechanisms proposed in the various solutions just in an automatic way. There would be no changes for the end user here just how it is dealt with internally.

   Comparison Matrix

   Feature	Solution 1: Parse Name	Solution 2: Repo Prefix	Solution 3: Prefix Parameter
   Backwards compatible	✅ Yes	✅ Yes	✅ Yes
   User complexity	🟢 Low	🟡 Medium	🟡 Medium
   Implementation complexity	🟢 Low	🟡 Medium	🟢 Low

   Recommended Solution

   I would recommend either option 1 so that the cmdlets favour less UX complexity with a slight tradeoff in code complexity. Option 3 as a second option if that trade off isn't desired.

   From an end user experience if they see a package in a repository as namespace/module then they would expect to be able to use that as the -Name rather than having to know that the prefix is some OCI specific configuration that needs to be handled separately.

   Example User Experience

   After implementation, users could work with GHCR or other OCI registry packages with a prefix like this:

   # One-time setup: Register GHCR
   Register-PSResourceRepository -Name GHCR -Uri 'https://ghcr.io' -ApiVersion ContainerRegistry
   
   # Publishing (prefix as parameter)
   Publish-PSResource -Path ./MyModule -Repository GHCR -ModulePrefix ghuser
   # Publishes to: ghcr.io/ghuser/mymodule
   
   # Installing (prefix in name)
   Install-PSResource -Name ghuser/MyModule -Repository GHCR
   # Installs from: ghcr.io/ghuser/mymodule
   
   # Finding packages in registry
   # /v2/_catalog doesn't allow filtering in the API so would have to be done
   # either in the cmdlet based on the results or with Where-Object
   Find-PSResource -Repository GHCR
   # Searches: ghcr.io/*
   # Would eventually return something with ghuser/mymodule
   
   # Dependencies resolved automatically
   # MyModule depends on DependencyModule
   Install-PSResource -Name ghuser/MyModule -Repository GHCR
   # Also installs: ghcr.io/ghuser/dependencymodule
4. Sydney Smith (SydneyhSmith)

   added

   Container-Galleries

   on Mar 2, 2026
5. SydneyhSmith commented on Aug 13, 2026

   

   Sydney Smith (SydneyhSmith)

   on Aug 13, 2026

   Collaborator

   More actions

   Thanks Jordan Borean (@jborean93) let's revisit this after the ORAS PR goes in