OCI registry support for Bicep extension publishing by willdavsmith · Pull Request #18956 · Azure/bicep

willdavsmith · 2026-02-05T21:07:59Z

OCI Registry Support for Bicep Extension Publishing

Description

Adds support for publishing and restoring Bicep modules and extensions to/from non-Azure OCI-compliant container registries (GHCR, Docker Hub, etc.).

Previously, publish, restore, and publish-extension only worked with Azure Container Registry (ACR) because the transport was hard-coded to the Azure SDK's ContainerRegistryContentClient. This change introduces an alternative transport built on ORAS (OCI Registry As Storage), so Bicep artifacts can be stored in any compliant registry.

Related to #4884.

User Experience

Feature flag

The feature is gated behind an experimental flag called ociEnabled. Any one of the following enables it:

CLI flag — pass --oci-enabled before the subcommand:

bicep --oci-enabled publish myModule.bicep \
  --target 'br:ghcr.io/myorg/bicep/modules/my-module:v1.0'

Environment variable — set BICEP_EXPERIMENTAL_OCI=1 (or true)

export BICEP_EXPERIMENTAL_OCI=1
bicep publish myModule.bicep --target 'br:ghcr.io/myorg/bicep/modules/my-module:v1.0'

bicepconfig.json:

{
  "experimentalFeaturesEnabled": {
    "ociEnabled": true
  }
}

Authentication

When the flag is enabled, Bicep authenticates to non-Azure registries using Docker credentials:

Docker credential helpers — reads ~/.docker/config.json and invokes the configured credsStore or per-registry credHelpers (e.g. docker-credential-desktop, docker-credential-ecr-login).
Static auth entries — falls back to base64-encoded username:password entries in the auths section of ~/.docker/config.json.

ACR (*.azurecr.io, mcr.microsoft.com) continues to use the existing Azure SDK auth path.

Example: publish a module to GHCR

# Log in to GHCR (one-time, stores creds in Docker config)
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Publish
bicep --oci-enabled publish ./main.bicep \
  --target 'br:ghcr.io/myorg/bicep/modules/network:v1.0'

# Reference in another file:
#   module vnet 'br:ghcr.io/myorg/bicep/modules/network:v1.0' = { ... }

# Restore
bicep --oci-enabled restore ./consumer.bicep

Example: publish an extension

bicep --oci-enabled publish-extension \
  --target 'br:myregistry.example.com/bicep/extensions/my-ext:v1.0' \
  --index-file ./out/index.json

New diagnostic: BCP440

Referencing a non-Azure registry without the flag produces:

BCP440: Using registry "ghcr.io" requires enabling EXPERIMENTAL feature "OciEnabled".

Design

Registry providers

A new IRegistryProvider interface lets different strategies handle different registry hosts:

IRegistryProvider
├── AcrRegistryProvider        (priority 100 — *.azurecr.io, mcr.microsoft.com)
└── GenericOciRegistryProvider (priority 0   — everything else)

RegistryProviderFactory resolves the provider for a given hostname. ACR always wins for Azure hosts; the ORAS-based provider is the fallback.

Transport abstraction

AzureContainerRegistryManager is now behind IOciRegistryTransport. A second implementation, OrasOciRegistryTransport, uses oras-dotnet to talk to generic registries. IOciRegistryTransportFactory picks the right one based on hostname.

Transport	Library	Handles
`AzureContainerRegistryManager`	Azure SDK	ACR
`OrasOciRegistryTransport`	oras-dotnet	Everything else

Session API

When ociEnabled is active, push/pull/resolve go through IRegistrySession instead of the transport directly:

PushAsync — pushes config, layers, and manifest
PullAsync — fetches manifest and layers
ResolveAsync — resolves a reference to manifest metadata (used by CheckArtifactExists)

Two implementations: AcrRegistrySession (wraps AzureContainerRegistryManager) and OrasRegistrySession (ORAS library).

Credential chain

CompositeCredentialChain
└── DockerCredentialSource
    └── DockerCredentialProvider
        ├── reads ~/.docker/config.json
        ├── invokes credsStore helpers (docker-credential-*)
        ├── invokes per-registry credHelpers
        └── falls back to static auth entries

DockerCredentialProvider implements the Docker credential helper protocol — sends the registry hostname to docker-credential-<helper> get via stdin, parses the JSON response. Supports username/password and identity token auth.

New dependency

Project reference to oras-dotnet for the generic OCI transport.

Registry routing

Registries are classified as Azure (ACR/MCR) or generic based on hostname. Hosts matching *.azurecr.io/.cn/.us/.de/.gov or mcr.microsoft.com route through the existing Azure SDK path (
AzureContainerRegistryManager). All other registries route through the new ORAS-based transport with Docker credential resolution. ACR registries behind custom domains will fall through to the generic path, which works via
Docker credential helpers (e.g. docker-credential-acr-env). A future improvement could use OCI auth challenge detection to automatically identify the backing provider regardless of hostname.

What's unchanged

ACR workflows — still use the Azure SDK path, no behavioral changes.
Module reference syntax — same br:registry/path:tag format for any registry.
Local artifact cache — non-Azure artifacts are cached the same way as ACR artifacts.

Checklist

I have read and adhere to the contribution guide.

Microsoft Reviewers: Open in CodeFlow

majastrz · 2026-02-18T21:39:59Z

Related to #4884

andyleejordan · 2026-04-01T19:15:11Z

I'm very happy to see this coming along!

Adds ORAS-based transport for non-Azure OCI registries (GHCR, Docker Hub, etc). New experimental feature flag 'ociEnabled' gates the new code path. Includes priority-based registry provider routing, Docker credential support, and session-based push/pull/resolve operations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

andyleejordan · 2026-04-02T19:12:36Z

Good news! I've successfully tested this to upload my extension to GitHub:

Publishing extension package to "br:ghcr.io/microsoft/bicep-types-dsc:latest".

...I still need to test it restoring (without credentials) and I should test it with RedHat's Podmon instead of Docker.

Signed-off-by: willdavsmith <willdavsmith@gmail.com>

willdavsmith · 2026-04-02T22:29:50Z

Good news! I've successfully tested this to upload my extension to GitHub:

Publishing extension package to "br:ghcr.io/microsoft/bicep-types-dsc:latest".

...I still need to test it restoring (without credentials) and I should test it with RedHat's Podmon instead of Docker.

Awesome! Thanks for trying it out and I'm glad it's useful for you. Feel free to update here, and if my commits break anything, please let me know.

andyleejordan · 2026-04-08T19:23:21Z

@willdavsmith successful demo with a dev build of the VS Code extension restoring the extension off GitHub for my Bicep file.

gXkch · 2026-04-14T13:46:56Z

@willdavsmith thank you for your work on this. this will make usage in an enterprise environment where self managed OCI registries exist finally a reality.

anthony-c-martin · 2026-04-14T14:20:19Z


        public IDirectoryHandle CacheRootDirectory => GetCacheRootDirectory(this.configuration.CacheRootDirectory);

+        public bool OciEnabled => this.configuration.ExperimentalFeaturesEnabled.OciEnabled || ReadBooleanEnvVar("BICEP_EXPERIMENTAL_OCI", defaultValue: false);


Do we need this env var at all? Generally we manage feature flags purely through bicepconfig, rather than duplicating.

No, it was just set for testing. Removed.

Signed-off-by: willdavsmith <willdavsmith@gmail.com>

anthony-c-martin · 2026-04-14T17:46:53Z

            var reference = ValidateReference(args.TargetExtensionReference);
            var overwriteIfExists = args.Force;

+            logger.LogInformation("Preparing to publish extension \"{Reference}\" (force={Force}, indexFile={IndexFile}, binariesSpecified={BinaryCount}).",


The logger here will output everythign to stdout, whereas it looks more like the intention here is to add tracing.

I'd suggest either:

Removing the logging

Using trace methods instead (e.g. Trace.WriteLine(...))

anthony-c-martin · 2026-04-14T17:48:01Z

                "BCP367",
                $"The \"{featureName}\" feature is temporarily disabled.");

+            public Diagnostic NonAzureOciRegistryRequiresExperimentalFeature(string registry) => CoreError(


[nit] Could you add this to the file in ascending code order (e.g. after BCP445)?

anthony-c-martin · 2026-04-14T17:49:10Z

+        {
+            var value = Environment.GetEnvironmentVariable(envVar);
+            if (value is null)
+            {
+                return defaultValue;
+            }
+
+            if (bool.TryParse(value, out var boolValue))
+            {
+                return boolValue;
+            }
+
+            if (int.TryParse(value, NumberStyles.Integer, CultureInfo.InvariantCulture, out var intValue))
+            {
+                if (intValue == 1)
+                {
+                    return true;
+                }
+
+                if (intValue == 0)
+                {
+                    return false;
+                }
+            }
+
+            return defaultValue;
+        }


Is this change strictly necessary, now you've removed the use of env vars for feature flag enablement? If not, let's remove it.

anthony-c-martin · 2026-04-14T17:58:21Z

+        services.TryAddSingleton<IOciRegistryTransportFactory>(sp =>
+        {
+            var providerFactory = sp.GetRequiredService<RegistryProviderFactory>();
+            return new OciRegistryTransportFactory(providerFactory);
+        });


Is this necessary? Can't you just write:

services.TryAddSingleton<IOciRegistryTransportFactory, OciRegistryTransportFactory>();

anthony-c-martin · 2026-04-14T18:00:51Z

+        services.TryAddSingleton<AzureContainerRegistryManager>();
+        services.TryAddSingleton<DockerCredentialProvider>();
+        services.TryAddSingleton<DockerCredentialSource>();
+        services.TryAddSingleton<ICredentialSource>(sp => sp.GetRequiredService<DockerCredentialSource>());


It doesn't seem right that requesting the generic interface ICredentialSource should always give you an instance of DockerCredentialSource. If that's intentional, should we rename ICredentialSource to IDockerCredentialSource to indicate that you are specifically requesting the Docker implementation?

anthony-c-martin · 2026-04-14T18:01:47Z

+  <ItemGroup>
+    <PackageReference Include="OrasProject.Oras" />
+  </ItemGroup>


[nit] Add to the section with the other PackageReference blocks

anthony-c-martin · 2026-04-14T18:05:26Z

+                        serviceProvider.GetRequiredService<IPublicModuleMetadataProvider>(),
+                        serviceProvider.GetRequiredService<ICredentialChain>(),
+                        serviceProvider.GetService<ILogger<OciArtifactRegistry>>() ?? NullLogger<OciArtifactRegistry>.Instance),
                    new TemplateSpecModuleRegistry(templateSpecRepositoryFactory),


Why not follow the standard DI pattern of passing these in as constructor arguments?

anthony-c-martin · 2026-04-14T18:06:25Z

                {
                    foreach (var tag in manifestProps.Tags)
                    {
+                        cancellationToken.ThrowIfCancellationRequested();


[nit] The explicit cancellation checks feel unnecessary, given that you're passing the token down to async methods correctly.

anthony-c-martin · 2026-04-14T18:06:54Z


            // Fall back to authenticated client.
-            return await DownloadManifestInternalAsync(anonymousAccess: false);
+            return await DownloadManifestInternalAsync(anonymousAccess: false, cancellationToken).ConfigureAwait(false);


[nit] we haven't been requiring this pattern in this repo, given it's a .NET 10 project.

anthony-c-martin · 2026-04-14T18:09:13Z

@@ -23,14 +24,38 @@ public static class TypesV1Archive
 {
    public static async Task<BinaryData> PackIntoBinaryData(IFileHandle typeIndexFile)


Why were the changes to this file necessary?

anthony-c-martin · 2026-04-14T18:11:31Z

+    private static readonly ImmutableHashSet<string> AzureRegistryHosts =
+        ImmutableHashSet.Create(StringComparer.OrdinalIgnoreCase, "mcr.microsoft.com");


It feels odd to treat mcr.microsoft.com as an "Azure registry host", which I would assume means an "ACR". Is this correct?

anthony-c-martin · 2026-04-14T18:14:24Z

@@ -34,6 +38,20 @@ public static IServiceCollection AddBicepCore(this IServiceCollection services)
        services.TryAddSingleton<INamespaceProvider, NamespaceProvider>();
        services.TryAddSingleton<IResourceTypeProviderFactory, ResourceTypeProviderFactory>();
        services.TryAddSingleton<IContainerRegistryClientFactory, ContainerRegistryClientFactory>();


It looks like this interface and class are now ACR-specific - is that correct? If so, should we name them something specific to make this clearer?

anthony-c-martin · 2026-04-14T18:21:30Z

+
+namespace Bicep.Core.Registry.Sessions;
+
+public sealed record RegistryRef(string Host, string Repository, string? Tag, string? Digest);


How does this overlap with the existing IOciArtifactAddressComponents interface?

anthony-c-martin · 2026-04-14T21:12:00Z

+    IOciRegistryTransport GetTransport(OciArtifactReference reference);
+
+    IOciRegistryTransport GetTransport(string registry);
+
+    IRegistrySession CreateSession(RegistryRef reference, RegistryProviderContext context);


It looks like there's some overlap between IRegistrySession and IOciRegistryTransport, and the naming of these 2 interfaces doesn't make it super clear to me what the 2 intended responsibilities are. Could you clarify on this?

anthony-c-martin · 2026-04-15T02:13:13Z

+
+namespace Bicep.Core.Registry.Sessions;
+
+public sealed record RegistryRef(string Host, string Repository, string? Tag, string? Digest);


RegistryRef looks structurally identical to IOciArtifactAddressComponents (same fields, just Host renamed to Registry). The only usage in OciArtifactRegistry is CreateRegistryRef, which projects an OciArtifactReference into a RegistryRef — and AcrRegistrySession then immediately wraps it back into a private SessionOciArtifactReference that re-implements IOciArtifactReference. Could we just pass IOciArtifactAddressComponents (or OciArtifactReference) directly to IRegistrySession, and avoid the round-trip?

anthony-c-martin · 2026-04-15T02:13:13Z

+
+namespace Bicep.Core.Registry.Sessions;
+
+public sealed record RegistryArtifact(


RegistryArtifact looks like OciManifest minus SchemaVersion. After a pull via IRegistrySession.PullAsync, the result is immediately converted back to OciArtifactResult via ConvertToOciArtifactResult. Could we just use OciManifest for push input and OciArtifactResult for pull output, and avoid the conversion step?

anthony-c-martin · 2026-04-15T02:13:13Z

+
+namespace Bicep.Core.Registry.Sessions;
+
+public sealed record RegistryManifestInfo(


The fields here (Digest, MediaType, ArtifactType, Annotations) are a subset of what's already available from OciManifest + OciArtifactResult.ManifestDigest. Could ResolveAsync return OciArtifactResult instead, so we don't need a separate type?

anthony-c-martin · 2026-04-15T02:13:14Z


        public override async Task<bool> CheckArtifactExists(ArtifactType artifactType, OciArtifactReference reference)
        {
+            if (reference.ReferencingFile.Features.OciEnabled)


Every operation (PublishModule, PublishExtension, CheckArtifactExists, TryRestoreArtifactAsync, TryGetOciAnnotations) has an if (OciEnabled) { session path } else { transport path } fork. Since AcrRegistrySession already wraps AzureContainerRegistryManager, is there a reason the ACR path can't go through IRegistrySession unconditionally? It would simplify things a lot and mean we're not carrying dead code once the feature flag is removed.

anthony-c-martin · 2026-04-15T02:13:14Z

+
+namespace Bicep.Core.Registry.Auth;
+
+public interface ICredentialSource


There's only one ICredentialSource implementation (DockerCredentialSource), and CompositeCredentialChain just iterates a single-element list. Also, the AuthMetadata? challenge parameter is accepted by all the credential interfaces but never actually read in DockerCredentialSource. Could we simplify this — e.g. inject DockerCredentialProvider directly into OrasRegistrySession, and add back the composite pattern only if a second source is actually needed?

anthony-c-martin · 2026-04-15T02:13:14Z

+/// <summary>
+/// Represents a strategy for handling registry interactions for a specific host or group of hosts.
+/// </summary>
+public interface IRegistryProvider


The routing chain here is OciArtifactRegistry → IOciRegistryTransportFactory → RegistryProviderFactory → IRegistryProvider, and both OciRegistryTransportFactory and RegistryProviderFactory do essentially the same thing (resolve by hostname, delegate). The Name/Priority/CanHandle strategy pattern on IRegistryProvider feels heavyweight for a two-case dispatch (*.azurecr.io vs everything else). Could these layers be collapsed?

anthony-c-martin · 2026-04-15T02:13:14Z

+
+    public required CloudConfiguration Cloud { get; init; }
+
+    public CancellationToken CancellationToken { get; init; }


Passing CancellationToken through a context object is unusual in .NET — tokens normally flow through method arguments. Looking at the usage, TryCreateSession always passes default for the token, and every session method already accepts its own token directly. Could we remove the token from the context? Similarly, ILogger and CloudConfiguration feel like they should be constructor parameters on the session implementations (via DI) rather than passed in at session-creation time.

willdavsmith changed the title ~~[WIP] OCI registry support for Bicep extension publishing~~ OCI registry support for Bicep extension publishing Mar 10, 2026

willdavsmith marked this pull request as ready for review March 10, 2026 21:55

willdavsmith mentioned this pull request Apr 1, 2026

Support OCI-compliant alternative container registry for bicep publish #4884

Open

willdavsmith force-pushed the oci-support branch 4 times, most recently from 0bddcfd to 4afe9d0 Compare April 1, 2026 23:01

willdavsmith force-pushed the oci-support branch from 4afe9d0 to 2d48764 Compare April 2, 2026 16:39

0402 review

2840a1b

Signed-off-by: willdavsmith <willdavsmith@gmail.com>

anthony-c-martin reviewed Apr 14, 2026

View reviewed changes

Remove BICEP_EXPERIMENTAL_OCI env var

c631e0d

Signed-off-by: willdavsmith <willdavsmith@gmail.com>

willdavsmith requested a review from anthony-c-martin April 14, 2026 17:43

anthony-c-martin reviewed Apr 14, 2026

View reviewed changes

anthony-c-martin reviewed Apr 15, 2026

View reviewed changes


		public IDirectoryHandle CacheRootDirectory => GetCacheRootDirectory(this.configuration.CacheRootDirectory);

		public bool OciEnabled => this.configuration.ExperimentalFeaturesEnabled.OciEnabled \|\| ReadBooleanEnvVar("BICEP_EXPERIMENTAL_OCI", defaultValue: false);

		@@ -23,14 +24,38 @@ public static class TypesV1Archive
		{
		public static async Task<BinaryData> PackIntoBinaryData(IFileHandle typeIndexFile)

		private static readonly ImmutableHashSet<string> AzureRegistryHosts =
		ImmutableHashSet.Create(StringComparer.OrdinalIgnoreCase, "mcr.microsoft.com");


		namespace Bicep.Core.Registry.Sessions;

		public sealed record RegistryRef(string Host, string Repository, string? Tag, string? Digest);


		namespace Bicep.Core.Registry.Sessions;

		public sealed record RegistryArtifact(


		namespace Bicep.Core.Registry.Sessions;

		public sealed record RegistryManifestInfo(


		namespace Bicep.Core.Registry.Auth;

		public interface ICredentialSource


		public required CloudConfiguration Cloud { get; init; }

		public CancellationToken CancellationToken { get; init; }

Conversation

willdavsmith commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

OCI Registry Support for Bicep Extension Publishing

Description

User Experience

Feature flag

Authentication

Example: publish a module to GHCR

Example: publish an extension

New diagnostic: BCP440

Design

Registry providers

Transport abstraction

Session API

Credential chain

New dependency

Registry routing

What's unchanged

Checklist

Microsoft Reviewers: Open in CodeFlow

Uh oh!

majastrz commented Feb 18, 2026

Uh oh!

andyleejordan commented Apr 1, 2026

Uh oh!

andyleejordan commented Apr 2, 2026

Uh oh!

willdavsmith commented Apr 2, 2026

Uh oh!

andyleejordan commented Apr 8, 2026

Uh oh!

gXkch commented Apr 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

willdavsmith commented Feb 5, 2026 •

edited

Loading