git-pkgs proxy

A caching proxy for package registries. Speeds up package downloads by caching artifacts locally, reducing bandwidth usage and improving reliability.

Most supply chain attacks rely on speed: a malicious version gets published and consumed by automated pipelines within minutes, before anyone notices. The cooldown feature adds a quarantine period to newly published versions. When enabled, the proxy strips versions from metadata responses until they've aged past a configurable threshold.

cooldown:
 default: "3d" # hide versions published less than 3 days ago
 ecosystems:
 npm: "7d" # npm gets a longer window
 cargo: "0" # disable for cargo
 packages:
 "pkg:npm/lodash": "0" # exempt trusted packages

A 3-day cooldown means that when lodash publishes version 4.18.0, your builds keep using 4.17.21 until 3 days have passed. If the new release turns out to be compromised, you were never exposed.

Resolution order: package override, then ecosystem override, then global default. This lets you set a conservative default and carve out exceptions for packages where you need faster updates. See docs/configuration.md for the full config reference.

Cooldown only looks at a version's publish timestamp — it never inspects the actual bytes. Artifact scanning closes that gap: when enabled, every artifact is staged into storage and scanned by one or more external services (trivy, ClamAV, Wiz, or anything else that speaks a small HTTP/JSON contract) before it's committed to the cache and served to clients.

scanning:
 enabled: true
 signing_key: ${PROXY_SCANNING_SIGNING_KEY}
 scanners:
 - name: clamav
 url: http://clamav-adapter:8080/scan
 mode: block # a block verdict deletes the artifact and returns 403
 - name: trivy
 url: http://trivy-adapter:8081/scan
 mode: monitor # findings are logged, never gate caching
 ecosystems: [npm, pypi]

The proxy never uploads artifact bytes to a scanner. Each scanner is notified with package metadata plus a short-lived signed URL; the scanner pulls the bytes itself from the proxy's own storage. Scanners run concurrently, and the first block-mode scanner to report a verdict of not-allowed wins immediately, canceling the rest. See docs/configuration.md for the full config reference and the scanner HTTP contract.

Cooldown requires publish timestamps in metadata. Registries without a "Yes" in the cooldown column either don't expose timestamps or haven't been wired up yet.

* Hex cooldown requires disabling registry signature verification (HEX_NO_VERIFY_REPO_ORIGIN=1) since the proxy re-encodes the protobuf payload.

brew install git-pkgs/git-pkgs/proxy

Or download a binary from the releases page.

Install the chart from GHCR, setting the public URL that package-manager clients will use to reach the proxy:

helm install proxy oci://ghcr.io/git-pkgs/charts/proxy \
 --set config.data.base_url=https://proxy.example.com

The default chart deploys one replica backed by a 10 GiB persistent volume, using SQLite and filesystem artifact storage under /data. See deploy/charts/proxy/values.yaml for ingress, external database and object-storage configuration options.

# Build from source
go build -o proxy ./cmd/proxy
# Run with defaults (listens on :8080)
./proxy
# Run with custom settings
./proxy -listen :3000 -base-url https://proxy.example.com

The proxy is now running. Configure your package managers to use it.

This repo uses swaggo to generate an OpenAPI spec from annotated handlers.

Generate the spec:

go install github.com/swaggo/swag/cmd/swag@latest
go generate ./internal/server

Generated files are written to docs/swagger/.

When the proxy is running, fetch the live spec from:

• http://localhost:8080/openapi.json

Or replace http://localhost:8080 with your configured base URL. This link is also shown on the dashboard.

Create or edit ~/.npmrc:

registry=http://localhost:8080/npm/

Or set per-project in .npmrc:

registry=http://localhost:8080/npm/

Or use environment variable:

npm_config_registry=http://localhost:8080/npm/ npm install

Create or edit ~/.cargo/config.toml:

[source.crates-io]
replace-with = "proxy"
[source.proxy]
registry = "sparse+http://localhost:8080/cargo/"

Or set per-project in .cargo/config.toml in your project root.

Set the gem source in your Gemfile:

source "http://localhost:8080/gem"

Or configure globally:

gem sources --add http://localhost:8080/gem/
bundle config mirror.https://rubygems.org http://localhost:8080/gem

Set the GOPROXY environment variable:

export GOPROXY=http://localhost:8080/go,direct

Or in your shell profile for persistence.

Point Homebrew's JSON API and artifact domain at the proxy:

export HOMEBREW_API_DOMAIN=http://localhost:8080/homebrew
export HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080

The artifact domain proxies manifests and bottle blobs under /v2/homebrew/core/. GHCR routing is limited to that repository. Source archives, cask application downloads, custom tap artifacts, and legacy flat-file bottle mirrors use Homebrew's normal fallback URLs. Keep fallback enabled by leaving HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK unset.

Enable cache_metadata or set PROXY_CACHE_METADATA=true to retain Homebrew JSON API responses for offline fallback. Bottle blobs and their OCI manifests are cached without this setting.

The upstreams default to https://formulae.brew.sh/api for the JSON API and https://ghcr.io for artifacts. To chain this proxy to another proxy, configure its Homebrew endpoints as the upstreams:

upstream:
 homebrew_api: "https://upstream-proxy.example.com/homebrew"
 homebrew_artifact: "https://upstream-proxy.example.com"

The equivalent environment variables are PROXY_UPSTREAM_HOMEBREW_API and PROXY_UPSTREAM_HOMEBREW_ARTIFACT.

Configure in ~/.hex/hex.config:

{default_url, <<"http://localhost:8080/hex">>}.

Or set the environment variable:

export HEX_MIRROR=http://localhost:8080/hex

Set the PUB_HOSTED_URL environment variable:

export PUB_HOSTED_URL=http://localhost:8080/pub

Configure pip to use the proxy:

pip install --index-url http://localhost:8080/pypi/simple/ package_name

Or set in ~/.pip/pip.conf:

[global]
index-url = http://localhost:8080/pypi/simple/

Add to your ~/.m2/settings.xml:

<settings>
 <mirrors>
 <mirror>
 <id>proxy</id>
 <mirrorOf>central</mirrorOf>
 <url>http://localhost:8080/maven/</url>
 </mirror>
 </mirrors>
</settings>

The /maven/ endpoint uses Maven Central as primary upstream and falls back to the Gradle Plugin Portal for Gradle plugin marker metadata and related artifacts when the primary upstream returns not found.

For Gradle plugin resolution via the same proxy endpoint:

pluginManagement {
 repositories {
 maven(url = "http://localhost:8080/maven/")
 }
}

Configure in settings.gradle(.kts):

buildCache {
 local {
 enabled = false
 }
 remote<HttpBuildCache> {
 url = uri("http://localhost:8080/gradle/")
 push = true
 }
}

Configure in nuget.config:

<configuration>
 <packageSources>
 <clear />
 <add key="proxy" value="http://localhost:8080/nuget/v3/index.json" />
 </packageSources>
</configuration>

Or use the CLI:

dotnet nuget add source http://localhost:8080/nuget/v3/index.json -n proxy

Configure in composer.json:

{
 "repositories": [
 {
 "type": "composer",
 "url": "http://localhost:8080/composer"
 }
 ]
}

Or set globally:

composer config -g repositories.proxy composer http://localhost:8080/composer

Add the proxy as a remote:

conan remote add proxy http://localhost:8080/conan
conan remote disable conancenter

Or configure in ~/.conan2/remotes.json.

Configure in ~/.condarc:

channels:
 - http://localhost:8080/conda/main
 - http://localhost:8080/conda/conda-forge
default_channels:
 - http://localhost:8080/conda/main

Or set via command:

conda config --add channels http://localhost:8080/conda/main

Set the repository in R:

options(repos = c(CRAN = "http://localhost:8080/cran"))

Or in ~/.Rprofile for persistence:

local({
 r <- getOption("repos")
 r["CRAN"] <- "http://localhost:8080/cran"
 options(repos = r)
})

Set the Pkg server before starting Julia:

export JULIA_PKG_SERVER=http://localhost:8080/julia

Or inside a running session:

ENV["JULIA_PKG_SERVER"] = "http://localhost:8080/julia"
using Pkg; Pkg.update()

Configure the proxy as the default registry for the current Swift package:

swift package-registry set --allow-insecure-http http://localhost:8080/swift

Registry dependencies use their scoped package identifier in Package.swift:

dependencies: [
 .package(id: "apple.swift-argument-parser", from: "1.2.0")
]

The proxy supports dependency resolution and source downloads. Publishing with swift package-registry publish is not supported.

Configure Docker to use the proxy as a registry mirror in /etc/docker/daemon.json:

{
 "registry-mirrors": ["http://localhost:8080"]
}

Then restart Docker:

sudo systemctl restart docker

Or pull images directly:

docker pull localhost:8080/library/nginx:latest

Configure each HTTP chart repository with a name, then add the matching proxy URL to Helm:

upstream:
 helm:
 bitnami: "https://charts.bitnami.com/bitnami"

helm repo add bitnami http://localhost:8080/helm/bitnami
helm repo update
helm pull bitnami/nginx

The proxy caches index.yaml using the normal metadata-cache settings and caches chart archives after verifying their SHA-256 digest from the index.

For charts stored in an OCI registry, configure a named OCI upstream and add the reserved upstream/{name} prefix to the chart reference:

upstream:
 oci:
 ghcr: "https://ghcr.io"

helm pull oci://localhost:8080/upstream/ghcr/owner/charts/mychart --version 1.0.0 --plain-http

Configure APT to use the proxy in /etc/apt/sources.list.d/proxy.list:

deb http://localhost:8080/debian stable main contrib

Replace your existing sources.list entries, then:

sudo apt update

The upstream defaults to http://deb.debian.org/debian. To proxy a different APT repository (e.g. Ubuntu), set upstream.debian in the config file or PROXY_UPSTREAM_DEBIAN in the environment:

upstream:
 debian: "http://archive.ubuntu.com/ubuntu"

Configure yum/dnf to use the proxy in /etc/yum.repos.d/proxy.repo:

[proxy-fedora]
name=Fedora via Proxy
baseurl=http://localhost:8080/rpm/releases/$releasever/Everything/$basearch/os/
enabled=1
gpgcheck=0

Then:

sudo dnf clean all
sudo dnf update

Point /etc/apk/repositories at the proxy. The default repository name alpine proxies the official mirror (https://dl-cdn.alpinelinux.org/alpine):

http://localhost:8080/apk/alpine/v3.22/main
http://localhost:8080/apk/alpine/v3.22/community

Then:

apk update

Repository indexes (v2 APKINDEX.tar.gz and v3 Packages.adb), detached signatures, and packages are served byte-for-byte unchanged, so apk's normal signature verification keeps working. Indexes use the metadata cache (metadata_ttl, stale fallback); .apk packages are stored in the shared artifact cache and remain available when the upstream is unreachable.

To proxy other mirrors or private repositories, configure named upstreams under upstream.apk (this replaces the built-in default; re-add alpine if you still want it):

upstream:
 apk:
 alpine: "https://dl-cdn.alpinelinux.org/alpine"
 private: "https://apk.example.com"

http://localhost:8080/apk/private

apk appends the architecture and index filename to each repository line itself.

Configure named generic upstreams:

upstream:
 generic:
 github: "https://github.com"
 github-api: "https://api.github.com"

Then rewrite GitHub URLs in mise's settings (~/.config/mise/config.toml, mise ≥ 2025年9月3日):

[settings.url_replacements]
"regex:^https://github\\.com/([^/]+)/([^/]+)/releases/download/(.+)" = "http://localhost:8080/generic/github/1ドル/2ドル/releases/download/3ドル"
"regex:^https://api\\.github\\.com/(.*)" = "http://localhost:8080/generic/github-api/1ドル"

Release assets are cached permanently after the first download and keep installing while GitHub is down. Tag lookups through api.github.com are cached for metadata_ttl and served stale during an outage or rate limit. Commit a mise.lock and install with mise install --locked so pinned installs need no API call at all. Add a bearer token for https://api.github.com under upstream.auth if the fleet exceeds GitHub's anonymous rate limit.

The proxy can be configured via:

1. Command line flags (highest priority)
2. Environment variables
3. Configuration file (YAML or JSON)

-config string Path to configuration file
-listen string Address to listen on (default ":8080")
-base-url string Public URL of this proxy (default "http://localhost:8080")
-storage-url string Storage URL (file://, s3://, gs://, azblob://)
-storage-path string Path to artifact storage directory (deprecated, use -storage-url)
-database-driver string Database driver: sqlite or postgres (default "sqlite")
-database-path string Path to SQLite database file (default "./cache/proxy.db")
-database-url string PostgreSQL connection URL
-log-level string Log level: debug, info, warn, error (default "info")
-log-format string Log format: text, json (default "text")
-access-log string Path to the JSONL access log
-version Print version and exit

PROXY_LISTEN=:8080
PROXY_BASE_URL=http://localhost:8080
PROXY_UI_URL=http://localhost:8080 # Optional; defaults to PROXY_BASE_URL
PROXY_STORAGE_URL=file:///var/cache/proxy/artifacts
PROXY_DATABASE_DRIVER=sqlite
PROXY_DATABASE_PATH=./cache/proxy.db
PROXY_DATABASE_URL=postgres://user:pass@localhost/proxy?sslmode=disable
PROXY_LOG_LEVEL=info
PROXY_LOG_FORMAT=text
PROXY_ACCESS_LOG_PATH=/var/log/proxy/access.jsonl
PROXY_UPSTREAM_SWIFT=https://tuist.dev/api/registry/swift

listen: ":8080"
base_url: "http://localhost:8080"
storage:
 url: "file:///var/cache/proxy/artifacts"
 max_size: "10GB" # Optional: evict LRU when exceeded
database:
 driver: "sqlite"
 path: "/var/lib/proxy/cache.db"
log:
 level: "info"
 format: "text"
access_log:
 path: "/var/log/proxy/access.jsonl" # Optional JSONL activity log
# Optional: override upstream URLs
upstream:
 npm: "https://registry.npmjs.org"
 cargo: "https://index.crates.io"
 swift: "https://tuist.dev/api/registry/swift"
# Optional: version cooldown (see above)
cooldown:
 default: "3d"

See the configuration reference for every upstream key, environment variable, and default URL.

Run with config file:

./proxy -config /etc/proxy/config.yaml

SQLite is the default and works well for single-node deployments. For multi-node setups or if you prefer a managed database, switch to Postgres:

database:
 driver: "postgres"
 url: "postgres://user:password@localhost:5432/proxy?sslmode=disable"

Or via environment variables:

PROXY_DATABASE_DRIVER=postgres
PROXY_DATABASE_URL=postgres://user:password@localhost:5432/proxy?sslmode=disable

The proxy creates tables automatically on first run.

The proxy can store cached artifacts in S3 or any S3-compatible service (MinIO, R2, etc.) instead of the local filesystem.

storage:
 url: "s3://my-bucket-name?region=us-east-1"

For S3-compatible services like MinIO:

storage:
 url: "s3://my-bucket?endpoint=http://localhost:9000&disableSSL=true&s3ForcePathStyle=true"

Set credentials via standard AWS environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION).

The proxy can store cached artifacts in a GCS bucket using the gs:// URL scheme.

storage:
 url: "gs://my-bucket-name"

Authentication uses Application Default Credentials, which means no credentials need to be embedded in the config or environment. Supported sources, in order:

• GKE Workload Identity — bind the Kubernetes service account running the proxy to a Google service account that has roles/storage.objectAdmin on the bucket. The proxy will use the workload's token automatically.
• Attached service account on GCE, Cloud Run, Cloud Functions, etc.
• GOOGLE_APPLICATION_CREDENTIALS environment variable pointing at a service account JSON key file.
• gcloud auth application-default login for local development.

# 1. Create a Google service account
gcloud iam service-accounts create git-pkgs-proxy \
 --project=PROJECT_ID
# 2. Grant it access to the bucket
gsutil iam ch \
 serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com:objectAdmin \
 gs://my-bucket-name
# 3. Bind the Kubernetes service account to it
gcloud iam service-accounts add-iam-policy-binding \
 git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com \
 --role=roles/iam.workloadIdentityUser \
 --member="serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
# 4. Annotate the Kubernetes service account
kubectl annotate serviceaccount KSA_NAME \
 --namespace=NAMESPACE \
 iam.gke.io/gcp-service-account=git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com

When direct_serve: true is enabled, the proxy issues HTTP 302 redirects to presigned GCS URLs. Workload Identity provides no private key, so the GCS backend calls the IAM Credentials signBlob API. Grant the service account the token-creator role on itself:

gcloud iam service-accounts add-iam-policy-binding \
 git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com \
 --role=roles/iam.serviceAccountTokenCreator \
 --member="serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com"

Start the proxy server. This is the default command if none is specified.

proxy serve [flags]
proxy [flags] # same as 'proxy serve'

Pre-populate the cache from PURLs, SBOM files, or entire registries. Useful for ensuring offline availability or warming the cache before deployments.

# Mirror specific package versions
proxy mirror pkg:npm/lodash@4.17.21 pkg:cargo/serde@1.0.0
# Mirror all versions of a package
proxy mirror pkg:npm/lodash
# Mirror from a CycloneDX or SPDX SBOM
proxy mirror --sbom sbom.cdx.json
# Preview what would be mirrored
proxy mirror --dry-run pkg:npm/lodash
# Control parallelism
proxy mirror --concurrency 8 pkg:npm/lodash@4.17.21

The mirror command accepts the same storage and database flags as serve. Already-cached artifacts are skipped.

A mirror API is also available when the server is running:

# Start a mirror job
curl -X POST http://localhost:8080/api/mirror \
 -H "Content-Type: application/json" \
 -d '{"purls": ["pkg:npm/lodash@4.17.21"]}'
# Start a mirror job from an inline CycloneDX or SPDX JSON SBOM
curl -X POST http://localhost:8080/api/mirror \
 -H "Content-Type: application/json" \
 -d '{"sbom":{"bomFormat":"CycloneDX","components":[{"purl":"pkg:npm/lodash@4.17.21"}]}}'
# Check job status
curl http://localhost:8080/api/mirror/mirror-1
# Cancel a running job
curl -X DELETE http://localhost:8080/api/mirror/mirror-1

Show cache statistics without running the server.

# Text output
proxy stats
# JSON output
proxy stats -json
# Custom database path
proxy stats -database-path /var/lib/proxy/cache.db
# With PostgreSQL
proxy stats -database-driver postgres -database-url postgres://user:pass@localhost/proxy
# Show top 20 most popular packages
proxy stats -popular 20

Example output:

Cache Statistics
================
Packages: 45
Versions: 128
Artifacts: 128
Total size: 892.4 MB
Total hits: 1547
Packages by ecosystem:
 npm 32
 cargo 13
Most popular packages:
 1. npm/lodash (342 hits, 24.7 KB)
 2. npm/react (198 hits, 89.3 KB)
 3. cargo/serde (156 hits, 234.1 KB)
Recently cached:
 npm/express@4.18.2 (2024年01月15日 14:32, 54.2 KB)
 cargo/tokio@1.35.0 (2024年01月15日 14:28, 412.8 KB)

The proxy provides REST endpoints for package metadata enrichment, vulnerability scanning, and outdated detection.

curl http://localhost:8080/api/package/npm/lodash

Response:

{
 "ecosystem": "npm",
 "name": "lodash",
 "latest_version": "4.17.21",
 "license": "MIT",
 "license_category": "permissive",
 "description": "Lodash modular utilities",
 "homepage": "https://lodash.com/",
 "repository": "https://github.com/lodash/lodash",
 "registry_url": "https://registry.npmjs.org"
}

curl http://localhost:8080/api/package/npm/lodash/4.17.0

Response:

{
 "package": {
 "ecosystem": "npm",
 "name": "lodash",
 "latest_version": "4.17.21",
 "license": "MIT",
 "license_category": "permissive"
 },
 "version": {
 "ecosystem": "npm",
 "name": "lodash",
 "version": "4.17.0",
 "license": "MIT",
 "published_at": "2016年06月17日T03:59:56Z",
 "yanked": false,
 "is_outdated": true
 },
 "vulnerabilities": [
 {
 "id": "GHSA-p6mc-m468-83gw",
 "summary": "Prototype Pollution in lodash",
 "severity": "HIGH",
 "cvss_score": 7.4,
 "fixed_version": "4.17.12"
 }
 ],
 "is_outdated": true,
 "license_category": "permissive"
}

curl -X POST http://localhost:8080/api/outdated \
 -H "Content-Type: application/json" \
 -d '{
 "packages": [
 {"ecosystem": "npm", "name": "lodash", "version": "4.17.0"},
 {"ecosystem": "pypi", "name": "requests", "version": "2.25.0"}
 ]
 }'

Response:

{
 "results": [
 {
 "ecosystem": "npm",
 "name": "lodash",
 "version": "4.17.0",
 "latest_version": "4.17.21",
 "is_outdated": true
 },
 {
 "ecosystem": "pypi",
 "name": "requests",
 "version": "2.25.0",
 "latest_version": "2.31.0",
 "is_outdated": true
 }
 ]
}

curl -X POST http://localhost:8080/api/bulk \
 -H "Content-Type: application/json" \
 -d '{
 "purls": [
 "pkg:npm/lodash@4.17.21",
 "pkg:pypi/requests@2.28.0"
 ]
 }'

Response:

{
 "packages": {
 "pkg:npm/lodash": {
 "ecosystem": "npm",
 "name": "lodash",
 "latest_version": "4.17.21",
 "license": "MIT",
 "license_category": "permissive"
 },
 "pkg:pypi/requests": {
 "ecosystem": "pypi",
 "name": "requests",
 "latest_version": "2.31.0",
 "license": "Apache-2.0",
 "license_category": "permissive"
 }
 }
}

{
 "cached_artifacts": 142,
 "total_size_bytes": 523456789,
 "total_size": "499.2 MB",
 "storage_url": "file:///path/to/cache/artifacts",
 "database_path": "./cache/proxy.db"
}

1. Package manager requests package metadata from the proxy
2. Proxy fetches metadata from upstream, rewrites artifact URLs to point at proxy
3. Package manager requests artifact (tarball, crate, etc.)
4. Proxy checks local cache:
   • Cache hit: Serve from local storage
   • Cache miss: Fetch from upstream, store locally, serve to client
5. Subsequent requests for the same artifact are served from cache

┌─────────────┐ ┌─────────┐ ┌──────────┐
│ npm/cargo │────▶│ proxy │────▶│ upstream │
│ client │◀────│ │◀────│ registry │
└─────────────┘ └─────────┘ └──────────┘
 │
 ▼
 ┌─────────┐
 │ cache │
 │ storage │
 └─────────┘

The proxy serves a web UI under /ui. No separate frontend build is needed -- templates and assets are embedded in the binary. GET / redirects to /ui/. The UI is mounted under its own prefix so a reverse proxy can apply different access rules to it than to the package endpoints (for example, requiring auth for PathPrefix(/ui) while leaving /npm, /pypi etc. open to build machines).

• Dashboard (/ui/) -- cache stats, popular packages, recently cached artifacts, and vulnerability overview.
• Install guide (/ui/install) -- per-ecosystem configuration instructions, so you don't have to look them up here.
• Package browser (/ui/packages) -- browse all cached packages with filtering by ecosystem and sorting by hits, size, name, or vulnerability count.
• Search (/ui/search?q=...) -- search cached packages by name.
• Package detail (/ui/package/{ecosystem}/{name}) -- metadata, license, vulnerabilities, and version list for a package. You can select two versions to compare.
• Version detail (/ui/package/{ecosystem}/{name}/{version}) -- per-version metadata, integrity hash, artifact cache status, and hit counts.
• Source browser (/ui/package/{ecosystem}/{name}/{version}/browse) -- browse files inside cached archives with syntax highlighting for text files and image previews.
• Version diff (/ui/package/{ecosystem}/{name}/compare/{v1}...{v2}) -- side-by-side diff of two cached versions showing added, removed, and changed files.

The proxy exposes Prometheus metrics at GET /metrics. All metric names are prefixed with proxy_.

Cache size and artifact count are refreshed every 60 seconds. Circuit breaker state is read from the fetcher on each scrape of /metrics and each /health request, so proxy_circuit_breaker_trips_total counts the trips visible between those reads — a breaker that opens and recovers entirely between two scrapes is not counted. The remaining metrics update on each request.

The breaker metrics carry one series per upstream host, but only for hosts whose breaker has tripped at least once since startup. A breaker is created per host the proxy fetches artifacts from, and for some ecosystems that host comes from upstream metadata rather than from configuration (composer takes it from a package's dist.url, helm from the chart URLs in index.yaml), so publishing every host would let upstream content grow the series count for the lifetime of the process. Once a host has tripped it keeps reporting, so a recovery still shows up as a transition to 0 rather than as a series that vanishes. /health is not a persistent time series and lists every breaker, tripped or not.

The registry label is the host of the URL the artifact was fetched from. Because that URL can come from upstream metadata, it is not always one a host can be read off — a signed dist.url that fails to parse, for instance — and such a breaker is labelled hostless-url-<digest> instead, where the digest is keyed by a value drawn fresh at startup. Neither /metrics nor /health requires authentication, so a fetch URL is never published as a label or a key; the digest identifies the breaker for as long as the process runs without revealing the URL behind it or letting a chosen URL be matched against it.

Alert on proxy_circuit_breaker_state == 2 sustained for more than a few minutes: while a breaker is open, artifact downloads for that upstream fail with HTTP 502 on every cache miss, and only a single probe request per backoff interval reaches the upstream. Cached artifacts keep serving, and so does metadata for the same ecosystem (metadata does not go through the circuit breaker), so installs fail in a way that looks like a partial upstream outage.

/health returns a structured JSON report of subsystem health. HTTP 200 if all checks pass; 503 if any fail.

{
 "status": "ok",
 "checks": {
 "database": {"status": "ok"},
 "storage": {"status": "ok"}
 },
 "circuit_breakers": {
 "registry.npmjs.org": "closed",
 "static.crates.io": "open"
 }
}

Failing checks include an "error" field. Storage failures also include a "step" field identifying which probe step failed (write, size, read, verify, delete). When the database check fails, the storage entry reports {"status": "skipped"} so the response always carries the same key set.

circuit_breakers reports the state of each upstream's artifact-fetch circuit breaker ("open" or "closed"), keyed by upstream host — or by the hostless-url-<digest> placeholder described under Monitoring where the fetch URL has no host to read. The key is omitted until the proxy has fetched an artifact from at least one upstream, and a host appears only once a breaker has been created for it. Breakers trip after repeated upstream failures and retry the upstream after an exponential backoff. While one is open, artifact downloads for that host return HTTP 502 on a cache miss without contacting the upstream; already-cached artifacts are still served from storage, since the cache is checked before the fetcher. A breaker is reported as "open" throughout its backoff, including the half-open window in which it admits one probe request to test recovery. Breaker state is per process and in memory, so a restart clears it, but a restart is not needed for recovery: the backoff keeps retrying for as long as the breaker is open, so it closes on its own once the upstream serves again.

An open breaker does not set status to "error" or change the HTTP status code: it reports a specific upstream refusing to serve, not this proxy being unfit to receive traffic, and failing the readiness probe over one unhealthy upstream would pull the pod out of rotation for every other ecosystem too. Use proxy_circuit_breaker_state for alerting on it.

Storage probe results are cached for health.storage_probe_interval (default 30s) to bound the cost of probing remote backends. A probe holds an internal mutex for up to 10 seconds (the hardcoded per-probe timeout), so /health is intended as a Kubernetes readiness probe rather than a liveness probe — a slow S3 round-trip should pull the pod from rotation, not restart it.

Scrape config for Prometheus:

scrape_configs:
 - job_name: git-pkgs-proxy
 static_configs:
 - targets: ["localhost:8080"]

Create /etc/systemd/system/proxy.service:

[Unit]
Description=git-pkgs proxy
After=network.target
[Service]
Type=simple
User=proxy
ExecStart=/usr/local/bin/proxy -config /etc/proxy/config.yaml
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable proxy
sudo systemctl start proxy

A Dockerfile is included in the repo. Build and run:

docker build -t proxy .
docker run -p 8080:8080 -v proxy-data:/data proxy

With Postgres and S3:

docker run -p 8080:8080 \
 -e PROXY_DATABASE_DRIVER=postgres \
 -e PROXY_DATABASE_URL=postgres://user:pass@db:5432/proxy \
 -e PROXY_STORAGE_URL=s3://my-bucket?region=us-east-1 \
 -e AWS_ACCESS_KEY_ID=... \
 -e AWS_SECRET_ACCESS_KEY=... \
 proxy

When running behind nginx, Apache, or another reverse proxy, set base_url to your public URL:

base_url: "https://proxy.example.com"

If the UI is reached on a different hostname than the package endpoints — for example, the UI exposed publicly on a domain while build machines hit a Docker network alias — set ui_base_url separately. base_url is the URL package managers and metadata rewriting use; ui_base_url is the URL advertised to humans visiting the web UI (canonical/og:url tags and the install guide banner):

base_url: "http://pkg-proxy:8080" # internal alias for build machines
ui_base_url: "https://proxy.example.com/ui" # public UI URL

When unset, ui_base_url defaults to base_url.

Warning: the proxy serves the UI and package endpoints on the same listener. Setting ui_base_url only changes what URL the UI advertises to humans; it does not stop package endpoints from being reachable on the same hostname and port. When fronting the proxy with a public reverse proxy, restrict the public route to PathPrefix(/ui) (or your proxy's equivalent), otherwise /npm, /pypi, and the other package endpoints stay exposed alongside the UI.

nginx example, restricting the public host to the UI while leaving package endpoints reachable only on the internal listener:

server {
 listen 443 ssl;
 server_name proxy.example.com;
 location /ui/ {
 proxy_pass http://127.0.0.1:8080;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_buffering off;
 }
 location / {
 return 404;
 }
}

Traefik example using PathPrefix(/ui) so the public router only matches UI traffic:

labels:
 traefik.enable: "true"
 traefik.http.services.pkg-proxy.loadbalancer.server.port: "8080"
 traefik.http.routers.pkg-proxy.rule: "Host(`proxy.example.com`) && PathPrefix(`/ui`)"
 traefik.http.routers.pkg-proxy.entrypoints: "websecure"

The proxy stores artifacts in the configured storage directory with this structure:

cache/artifacts/
├── npm/
│ └── lodash/
│ └── 4.17.21/
│ └── lodash-4.17.21.tgz
├── cargo/
│ └── serde/
│ └── 1.0.193/
│ └── serde-1.0.193.crate
├── oci/
│ └── library/nginx/
│ └── sha256:abc123.../
│ └── sha256:abc123...
├── deb/
│ └── nginx/
│ └── 1.18.0-6/
│ └── nginx_1.18.0-6_amd64.deb
└── rpm/
 └── nginx/
 └── 1.24.0-1.fc39/
 └── nginx-1.24.0-1.fc39.x86_64.rpm

Cache metadata is stored in SQLite (default) or PostgreSQL. To clear a local cache:

rm -rf ./cache/artifacts/*
rm ./cache/proxy.db

The proxy will recreate the database on next start.

Requirements:

• Go (the project version is declared in go.mod)

git clone https://github.com/git-pkgs/proxy.git
cd proxy
go build -o proxy ./cmd/proxy

Run tests:

go test ./...

GPL-3.0-or-later