How to Manage Repositories and Upstream Mirrors

Overview

Repositories in Chainsaw represent upstream package registries that the proxy mirrors. Each repository is a pull-through cache for a specific ecosystem — when a package is requested, Chainsaw fetches it from upstream, caches it locally, and serves it to the client. This tutorial covers managing these repositories.

Prerequisites

• Admin or Owner role in Chainsaw
• Understanding of which package ecosystems your organization uses

Step 1: View All Repositories

Navigate to Repositories in the sidebar. You’ll see a list of all configured repositories.

Each repository card shows:

Step 2: Enable or Disable Repositories

Toggle repositories on or off based on which ecosystems your organization needs:

1. Click on a repository
2. Toggle the Enabled switch
3. Disabled repositories reject all requests

Step 3: Configure Anonymous Access

By default, repositories require client credentials. You can enable anonymous access for specific repositories if needed (e.g., for open development environments):

1. Click on the repository
2. Toggle Anonymous Access
3. When enabled, requests without credentials are accepted

Step 4: Browse Cached Packages

Click into a repository to see the packages that have been cached:

The package browser shows:

• Package name and versions
• Last access time
• Download count
• Vulnerability status (if scanned)

Step 5: View Per-Repository Traffic

Each repository has a Traffic tab showing request metrics:

• Total requests over time
• Cache hit ratio
• Top requested packages
• Blocked requests

This helps you understand:

• Which ecosystems generate the most traffic
• How effective the cache is per registry
• Which packages are most frequently requested

Step 6: View Client Setup Guides

Each repository page includes a Setup Guide section with copy-paste instructions for configuring package managers to use that specific repository.

Share these guides with your development teams to simplify onboarding.

Step 7: Understand Negative Caching

Chainsaw uses negative caching to prevent repeated 404 requests to upstream registries. When an upstream returns a 404:

1. Chainsaw caches the negative result
2. Subsequent requests for the same package return 404 immediately
3. The cache expires after a configurable time

This reduces load on upstream registries and improves response times for packages that don’t exist.

Step 8: Format-Aware URL Rewriting

For some ecosystems (PyPI, Composer), upstream responses contain absolute URLs that point back to the original registry. Chainsaw automatically rewrites these URLs to point through the proxy, ensuring all subsequent requests stay on the Chainsaw path.

Supported Repository Formats

Next Steps

• How to Configure Your Package Manager to Use Chainsaw — Per-ecosystem configuration
• How to Manage Cache and Optimize Build Performance — Cache management and purging
• How to Create and Manage Client Credentials — Credential management for repository access