Docker Registries Supported by Dewy: Complete OCI Integration Guide

Dewy supports any OCI-compatible Docker registry through the img:// URL scheme, with built-in authentication handling for Docker Hub, GitHub Container Registry, and private registries using environment-based credentials.

Dewy is an open-source deployment tool (linyows/dewy) designed to automate application releases from container images. Understanding what Docker registries are supported by Dewy is essential for configuring your deployment pipeline, whether you are pulling from public repositories or private enterprise registries behind corporate firewalls.

How Dewy Implements Docker Registry Support

Dewy abstracts registry interactions through a common interface defined in registry/registry.go. When you provide a URL with the img:// scheme, the factory function (lines 73-75) instantiates the OCI driver to handle all communication with the registry.

The OCI implementation in registry/oci.go provides complete Docker Registry HTTP API V2 support. This includes tag listing, manifest retrieval, pagination handling, and authentication negotiation. The loadCredentials function (lines 79-86) dynamically selects the appropriate authentication method based on the registry hostname, eliminating the need for manual configuration files.

Supported Docker Registries

Dewy's OCI driver supports any registry implementing the Open Container Initiative (OCI) Distribution Specification. The following configurations are explicitly supported with automated credential handling:

Docker Hub and Generic Registries

For Docker Hub (index.docker.io) or any standard Docker registry, Dewy uses the DOCKER_USERNAME and DOCKER_PASSWORD environment variables. These credentials are passed as basic authentication headers when accessing private repositories, or used to negotiate bearer tokens if the registry requires token-based authentication.

GitHub Container Registry (ghcr.io)

When the registry URL contains ghcr.io, Dewy automatically detects the GitHub Container Registry and uses the GITHUB_TOKEN environment variable as a bearer token. This eliminates the need to manually configure Docker credentials for GitHub-hosted images. Ensure your token has the read:packages scope to access private packages.

Private Self-Hosted Registries

Dewy supports private registries running on internal infrastructure, including Harbor, Nexus, Artifactory, or the open-source Docker Registry. Configure access using the standard DOCKER_USERNAME and DOCKER_PASSWORD environment variables. The OCI driver negotiates authentication using the registry's supported challenge scheme, whether basic auth or bearer token.

Future Registry Support

Source code comments in registry/oci.go indicate planned Phase 2 support for cloud-native registries:

• AWS Elastic Container Registry (ECR): Will integrate with AWS CLI credentials or IAM roles
• Google Artifact Registry: Will support gcloud authentication

These are not yet implemented in the current stable release, though you can use these registries if they expose a standard Docker Registry HTTP API V2 endpoint with basic authentication enabled.

Authentication Mechanisms

Dewy implements a flexible authentication flow in the loadCredentials function within registry/oci.go. The process follows these steps:

1. Registry Detection: Parse the hostname from the img:// URL
2. Credential Selection:
   • If hostname contains ghcr.io, use GITHUB_TOKEN
   • Otherwise, use DOCKER_USERNAME/DOCKER_PASSWORD
3. Auth Negotiation: Attempt basic auth first; if the registry returns a 401 with a WWW-Authenticate header, negotiate a bearer token using the provided credentials

This approach ensures compatibility with both legacy basic-auth registries and modern token-based systems without requiring configuration file changes.

Practical Code Examples

Pulling from Docker Hub

To retrieve the latest image from Docker Hub, instantiate the registry with the img:// scheme and call Current():

registryURL := "img://index.docker.io/library/alpine"
reg, err := registry.New(context.Background(), registryURL, logger)
if err != nil {
    log.Fatal(err)
}

current, err := reg.Current(context.Background())
if err != nil {
    log.Fatal(err)
}
// current.ArtifactURL contains the resolved image reference

Set DOCKER_USERNAME and DOCKER_PASSWORD environment variables if accessing private repositories.

Accessing GitHub Container Registry

For GitHub Container Registry, Dewy automatically handles authentication when it detects the ghcr.io hostname:

registryURL := "img://ghcr.io/owner/repo"
os.Setenv("GITHUB_TOKEN", "<personal-access-token>")

reg, err := registry.New(context.Background(), registryURL, logger)
if err != nil {
    log.Fatal(err)
}

cur, err := reg.Current(context.Background())
if err != nil {
    log.Fatal(err)
}

The token must have the read:packages scope to access private packages. The loadCredentials function in registry/oci.go automatically selects the token based on the hostname.

Connecting to Private Registries

For internal registries requiring basic authentication:

registryURL := "img://my.private-registry.local/myapp"
os.Setenv("DOCKER_USERNAME", "user")
os.Setenv("DOCKER_PASSWORD", "s3cr3t")

reg, err := registry.New(context.Background(), registryURL, logger)
if err != nil {
    log.Fatal(err)
}

cur, err := reg.Current(context.Background())
if err != nil {
    log.Fatal(err)
}

The OCI driver negotiates the appropriate authentication method based on the registry's challenge response, supporting both basic auth and bearer token flows.

Key Implementation Files

Understanding the source structure helps when extending or debugging registry support:

• registry/registry.go: Contains the factory function that parses the img:// scheme and instantiates the OCI driver (lines 73-75). This is the entry point for all registry operations in Dewy.
• registry/oci.go: Implements the OCI Distribution Specification client, including the loadCredentials function (lines 79-86) that handles authentication logic for Docker Hub, GHCR, and generic registries. This file manages tag listing, manifest retrieval, and token negotiation.

These files demonstrate how Dewy abstracts registry-specific details behind a common interface while maintaining flexibility for various authentication mechanisms.

Summary

• Dewy supports any OCI-compatible Docker registry through the img:// URL scheme, including Docker Hub, GitHub Container Registry, and private self-hosted instances.
• Authentication is environment-driven: Use DOCKER_USERNAME/DOCKER_PASSWORD for standard registries and GITHUB_TOKEN for GHCR.
• The OCI implementation in registry/oci.go handles Docker Registry HTTP API V2, including token negotiation and manifest retrieval.
• AWS ECR and Google Artifact Registry are planned for future Phase 2 support according to source code comments.
• Private registries work immediately if they expose the standard Docker Registry HTTP API V2 with basic auth or bearer token support.

Frequently Asked Questions

Does Dewy support Amazon ECR or Google Artifact Registry?

Currently, Dewy does not natively support AWS Elastic Container Registry or Google Artifact Registry in the stable release. However, source code comments in registry/oci.go indicate these are planned for Phase 2 implementation, where the driver will integrate with AWS CLI credentials and gcloud authentication respectively. For now, you can use these registries only if they expose a standard Docker Registry HTTP API V2 endpoint with basic authentication or bearer token support enabled.

How does Dewy authenticate with GitHub Container Registry?

Dewy automatically detects GitHub Container Registry when the URL contains ghcr.io. The loadCredentials function in registry/oci.go (lines 79-86) specifically checks for this hostname and uses the GITHUB_TOKEN environment variable as a bearer token. This eliminates manual Docker credential configuration, though you must ensure your token has the read:packages scope to access private repositories.

Can I use Dewy with a private registry behind a firewall?

Yes, Dewy supports private self-hosted registries such as Harbor, Nexus, Artifactory, or the open-source Docker Registry running behind corporate firewalls. Configure access by setting the DOCKER_USERNAME and DOCKER_PASSWORD environment variables. The OCI driver in registry/oci.go negotiates authentication using the registry's challenge scheme, supporting both basic authentication and bearer token flows as defined by the Docker Registry HTTP API V2 specification.

What URL scheme does Dewy use for container images?

Dewy uses the img:// scheme to identify container image sources. When the registry.New() factory function in registry/registry.go (lines 73-75) detects this scheme, it instantiates the OCI driver to handle registry communication. The URL format follows img://<registry-host>/<repository-path>, such as img://index.docker.io/library/alpine for Docker Hub or img://ghcr.io/owner/repo for GitHub Container Registry.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}