# Registry Resolution

GPM's registry resolution system provides flexible and secure package management across multiple registries. This system ensures packages are resolved from the correct registry based on access levels, authentication, and configuration.

## Registry Types

### Global Registry

The global registry hosts public packages available to all users:

* **URL**: `https://registry.gpm.sh`
* **Access**: Public packages only
* **Authentication**: Required for publishing
* **Use Case**: Open source packages, industry standards

### Tenant Registries

Tenant registries host organization-specific packages:

* **URL**: `https://<tenant>.gpm.sh`
* **Access**: Scoped and private packages
* **Authentication**: Required for private packages
* **Use Case**: Company packages, proprietary content

## Registry Selection

### Automatic Resolution

GPM automatically selects the appropriate registry based on:

1. **Package Access Level**: Public requires global, scoped/private requires tenant
2. **Configuration**: Registry URL from config or command line
3. **Authentication**: Available tokens for registry access

### Resolution Priority

1. **Command Line Flags**: `--registry` flag (highest priority)
2. **Environment Variables**: `GPM_REGISTRY` variable
3. **Configuration File**: `registry` setting in config
4. **Default Values**: Global registry fallback

## Configuration

### Setting Registry URL

```bash
# Set global registry
gpm config set registry https://registry.gpm.sh

# Set tenant registry
gpm config set registry https://company.gpm.sh

# Set custom registry
gpm config set registry https://custom.gpm.sh
```

### Environment Variables

```bash
# Set via environment variable
export GPM_REGISTRY=https://company.gpm.sh

# Override for single command
gpm search package --registry https://custom.gpm.sh
```

### Configuration File

GPM stores registry configuration in:

* **macOS**: `~/Library/Application Support/gpm/config.json`
* **Linux**: `~/.config/gpm/config.json`
* **Windows**: `%AppData%\gpm\config.json`

```json
{
  "registry": "https://company.gpm.sh",
  "registry_timeout": 60
}
```

## Access Level Resolution

### Public Packages

Public packages must be published to and read from the global registry:

```bash
# Publish public package (requires global registry)
gpm config set registry https://registry.gpm.sh
gpm login
gpm publish --access=public

# Install public package (works from any registry)
gpm install com.unity.analytics
```

### Scoped Packages

Scoped packages must be published to and read from tenant registries:

```bash
# Publish scoped package (requires tenant registry)
gpm config set registry https://company.gpm.sh
gpm login
gpm publish --access=scoped

# Install scoped package (requires tenant registry)
gpm config set registry https://company.gpm.sh
gpm install com.company.package
```

### Private Packages

Private packages require tenant registry and authentication:

```bash
# Publish private package (requires tenant registry + auth)
gpm config set registry https://company.gpm.sh
gpm login
gpm publish --access=private

# Install private package (requires tenant registry + auth)
gpm config set registry https://company.gpm.sh
gpm login
gpm install com.company.private-package
```

## Registry Validation

### Publishing Validation

GPM validates registry compatibility during publishing:

#### Public Access

* **Valid**: Global registry + global token
* **Invalid**: Tenant registry (error: "public requires global registry")

#### Scoped Access

* **Valid**: Tenant registry + tenant token
* **Invalid**: Global registry (error: "scoped requires tenant registry")

#### Private Access

* **Valid**: Tenant registry + tenant token
* **Invalid**: Global registry (error: "private requires tenant registry")

### Error Examples

```bash
# Error: Public on tenant registry
gpm config set registry https://company.gpm.sh
gpm publish --access=public
# Error: access level validation failed: public requires global registry

# Error: Scoped on global registry
gpm config set registry https://registry.gpm.sh
gpm publish --access=scoped
# Error: access level validation failed: scoped requires tenant registry
```

## Package Visibility

### Reading Packages

#### From Global Registry

* **Valid**: Public packages only
* **Invalid**: Scoped/private packages not visible

#### From Tenant Registry

* **Valid**: Public packages (from global)
* **Valid**: Scoped packages (no auth required)
* **Valid**: Private packages (with authentication)

### Installation Examples

```bash
# Install public package from global registry
gpm config set registry https://registry.gpm.sh
gpm install com.unity.analytics

# Install scoped package from tenant registry
gpm config set registry https://company.gpm.sh
gpm install com.company.analytics

# Install private package (requires authentication)
gpm config set registry https://company.gpm.sh
gpm login
gpm install com.company.proprietary
```

## Multi-Registry Workflows

### Development Workflow

```bash
# 1. Use global registry for public packages
gpm config set registry https://registry.gpm.sh
gpm install com.unity.analytics

# 2. Switch to company registry for private packages
gpm config set registry https://company.gpm.sh
gpm login
gpm install com.company.private-package
```

### Team Collaboration

```bash
# 1. Configure team registry
gpm config set registry https://team.gpm.sh

# 2. Install team packages
gpm install com.team.shared-utils

# 3. Publish team packages
gpm publish --access=scoped
```

### CI/CD Integration

```bash
# 1. Use environment variables for registry
export GPM_REGISTRY=https://company.gpm.sh

# 2. Install packages
gpm install

# 3. Publish packages
gpm publish --access=scoped
```

## Registry Management

### Registry Switching

```bash
# Switch to global registry
gpm config set registry https://registry.gpm.sh

# Switch to company registry
gpm config set registry https://company.gpm.sh

# Override for single command
gpm search package --registry https://custom.gpm.sh
```

### Authentication Management

```bash
# Login to global registry
gpm login --registry https://registry.gpm.sh

# Login to company registry
gpm login --registry https://company.gpm.sh

# Check authentication status
gpm whoami
```

### Registry Verification

```bash
# Test registry connectivity
gpm search test

# Check registry configuration
gpm config get registry

# Verify authentication
gpm whoami
```

## Network Configuration

### Proxy Settings

```bash
# Set HTTP proxy
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Set NO_PROXY for local addresses
export NO_PROXY=localhost,127.0.0.1,.local
```

### Timeout Configuration

```bash
# Set registry timeout
gpm config set registry_timeout 60

# Set longer timeout for slow networks
gpm config set registry_timeout 120
```

### SSL/TLS Configuration

```bash
# Verify SSL certificates
gpm search test

# Check certificate validity
openssl s_client -connect registry.gpm.sh:443
```

## Best Practices

### Registry Selection

#### Use Appropriate Registry

* **Global Registry**: For public, open source packages
* **Tenant Registry**: For company-specific packages
* **Custom Registry**: For specialized use cases

#### Configure Authentication

* **Global Registry**: Use global account for public packages
* **Tenant Registry**: Use company account for private packages
* **Multiple Registries**: Manage multiple authentication tokens

### Package Organization

#### Naming Conventions

* **Public Packages**: Use generic, descriptive names
* **Scoped Packages**: Use company domain in package name
* **Private Packages**: Use specific, descriptive names

#### Access Level Management

* **Public**: Open source, widely applicable
* **Scoped**: Company-specific, internal tools
* **Private**: Proprietary, sensitive content

### Security Considerations

#### Authentication

* **Never Commit Tokens**: Use environment variables
* **Rotate Tokens**: Regularly update authentication tokens
* **Use HTTPS**: Always use secure connections
* **Verify Certificates**: Check SSL certificate validity

#### Package Security

* **Verify Packages**: Check package integrity before installation
* **Use Trusted Registries**: Only use trusted registry sources
* **Keep Dependencies Updated**: Regular security updates
* **Monitor Package Usage**: Track package installation and usage

## Troubleshooting

### Common Issues

#### Registry Not Found

```bash
# Problem: Registry not found
gpm search package
# Error: Registry not found or unreachable

# Solutions:
# 1. Check registry URL
gpm config get registry

# 2. Test connectivity
curl -I https://registry.gpm.sh

# 3. Check network configuration
gpm config
```

#### Authentication Required

```bash
# Problem: Authentication required
gpm install com.company.private-package
# Error: Authentication required

# Solutions:
# 1. Login to registry
gpm login

# 2. Check authentication status
gpm whoami

# 3. Verify registry configuration
gpm config get registry
```

#### Access Level Mismatch

```bash
# Problem: Access level mismatch
gpm publish --access=public
# Error: public requires global registry

# Solutions:
# 1. Switch to global registry
gpm config set registry https://registry.gpm.sh

# 2. Use appropriate access level
gpm publish --access=scoped

# 3. Check package naming
gpm info com.company.package
```

### Debug Commands

```bash
# Get detailed error information
gpm search package --verbose

# Check registry configuration
gpm config

# Verify authentication
gpm whoami

# Test registry connectivity
gpm search test
```

## See Also

* [Package Guidelines](/package-guidelines/packages.md) - Package management overview
* [Access Levels](/package-guidelines/packages/access-levels.md) - Package visibility controls
* [Package Naming](/package-guidelines/packages/naming.md) - Package naming conventions
* [CLI Reference](/cli-reference/cli.md) - Package management commands
* [Configuration](/getting-started/getting-started/configuration.md) - Registry configuration


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gpm.sh/package-guidelines/packages/registry-resolution.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.