How to Configure Dewy to Use GitHub Releases as a Registry

To configure Dewy to use GitHub Releases as a registry, pass a URL with the ghr:// scheme using the --registry flag or DEWY_REGISTRY environment variable, optionally appending query parameters like ?pre-release=true or ?artifact=<name> to control version selection.

Dewy is an open-source deployment tool that supports multiple artifact registries through a unified URL syntax. When you configure Dewy to use GitHub Releases, it can automatically resolve the latest tags, download specific assets, and deploy them without manual intervention. This guide explains the exact syntax, internal resolution logic, and practical examples based on the linyows/dewy source code.

Understanding the GitHub Releases Registry Scheme

Dewy identifies GitHub Releases using the ghr:// URL scheme. In registry/registry.go, the scheme is defined as a constant that routes incoming requests to the GitHub Releases implementation.

Registry URL Format

The standard format follows this pattern:

ghr://<owner>/<repo>

You can optionally append query parameters to customize artifact selection. The URL parsing logic in registry/registry.go (lines 61-80) strips the scheme and extracts the repository owner and name before delegating to the GitHub Releases handler.

Supported Query Parameters

The GitHub Releases implementation in registry/ghr.go (lines 70-78) recognizes two key query parameters:

• pre-release: Set to true to include pre-release versions in the search
• artifact: Specify a custom asset name to download instead of the default

Setting the Registry via CLI and Environment Variables

The registry URL is supplied to Dewy through the --registry flag defined in cli.go (line 41). Alternatively, you can use the DEWY_REGISTRY environment variable to configure the endpoint declaratively.

# Using the CLI flag

dewy server --registry ghr://linyows/myapp

# Using environment variable

export DEWY_REGISTRY=ghr://linyows/myapp
dewy server

How Dewy Resolves GitHub Releases Internally

When configured with a ghr:// URL, Dewy instantiates a GHR object that interacts directly with the GitHub API to resolve tags and download artifacts.

URL Parsing and Scheme Detection

In registry/registry.go (line 16), the registry handler maintains a registry of supported schemes. When it encounters the ghr scheme, it initializes the GitHub Releases provider and passes the sanitized repository path to the constructor.

Artifact Resolution and Download

The concrete implementation in registry/ghr.go performs three critical operations:

1. Tag Resolution: Queries the GitHub API to find the latest release (or latest pre-release if specified via query parameter)
2. Asset Filtering: Locates the specified artifact by name using the artifact query parameter
3. Download Generation: Constructs the authenticated download URL (line 158) to fetch the binary securely

Complete Configuration Examples

Server Deployment Examples

Deploy a server using the latest stable release from a GitHub repository:

dewy server --registry ghr://linyows/myapp \
  --slot blue -- /opt/myapp/current/myapp

Deploy using a pre-release version and a specific asset file:

dewy server --registry "ghr://linyows/myapp?pre-release=true&artifact=dewy.tar" \
  --slot blue -- /opt/myapp/current/myapp

Asset Download Examples

Download frontend assets from a GitHub Release to a specific directory:

dewy assets --registry ghr://linyows/frontend \
  -d /var/www/html \
  -l info

This pattern corresponds to the example found in the README (line 69).

Summary

• Use the ghr:// scheme to configure GitHub Releases as your Dewy registry
• Pass the URL via --registry flag or DEWY_REGISTRY environment variable
• Append ?pre-release=true to target pre-release versions instead of stable releases
• Specify ?artifact=<name> to download a specific asset from the release
• Dewy handles resolution logic in registry/ghr.go and URL routing in registry/registry.go

Frequently Asked Questions

What URL scheme does Dewy use for GitHub Releases?

Dewy uses the ghr:// scheme to identify GitHub Releases registries. This constant is defined in registry/registry.go (line 16) and triggers the GitHub-specific resolution logic implemented in registry/ghr.go when parsed.

Can I filter for pre-release versions?

Yes. Append ?pre-release=true to your registry URL. The registry/ghr.go file (lines 70-78) decodes this parameter and includes pre-releases when querying the GitHub API for the latest tag, allowing you to deploy bleeding-edge builds.

How do I specify a custom artifact name?

Use the artifact query parameter in your registry URL, such as ghr://owner/repo?artifact=myapp-linux-amd64.tar.gz. If omitted, Dewy relies on its default asset resolution logic to select the appropriate file from the release.

Is the registry URL configurable via environment variables?

Yes. While the --registry flag defined in cli.go (line 41) provides CLI access, Dewy also respects the DEWY_REGISTRY environment variable, allowing you to configure the GitHub Releases endpoint without modifying startup scripts or systemd service files.

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