Nexus Repository integration
OSA Proxy supports static routes to Sonatype Nexus Repository Manager 3 and automatic repository discovery through the Nexus inventory API. This page covers discovery configuration, client URL construction, repository context propagation, and block response behavior.
Automatic repository discovery
Runtime discovery retrieves the Nexus repository list and creates dynamic routes for matching entries. Repositories do not need to be listed one by one in static ecosystem sections such as npm, maven, or pypi.
Discovery runs at startup and periodically afterwards. For every repository, OSA Proxy determines the ecosystem, builds the upstream URL, and applies the first matching repository-routing rule.
When Configuration Store is disabled, changes in osa-proxy.yml require a
restart. With Configuration Store enabled, managed discovery fields such as
enabled, repository-types, repository-routing, route-mode, and the
refresh interval can be changed through the Admin API
without a restart. Credentials and base-url remain bootstrap-owned and require
a restart.
Access requirements
Create a service account that can call GET /service/rest/v1/repositories and view the repositories that must be included in the inventory. Nexus discovery uses Basic auth.
In the following command, NEXUS_BASE_URL is the root URL without a path, for example https://nexus.example.com:
Discovery client credentials are used only for the inventory API. OSA Proxy does not automatically add them to package requests sent to discovered upstream repositories. Configure private package access separately, for example with incoming client credentials, anonymous read access, or a trusted reverse proxy.
Discovery configuration
base-url must be the Nexus root URL without a path, query, or fragment. Both username and password are required when discovery is enabled.
Allowed repository classes in repository-types are hosted, proxy, and group.
Selecting repositories
Every package type requires a separate rule. package-type does not support wildcards.
Omit name-regex to include all repositories of one type:
Name filters use Go regular expressions (RE2), not globs. Anchors ^ and $ are recommended:
Rules for one package type are evaluated from top to bottom. If a repository matches several rules, the first rule wins. Put specific expressions before a general fallback rule.
The scan-manifest, scan-package, remove-blocked-versions, work-mode, url-encoded-config, distro, and file-type-filter fields have the same meaning as in static ecosystem configuration. An unsupported combination causes a configuration error or rejects the discovery snapshot.
Supported formats
Nexus discovery supports:
npm, maven, nuget, pypi, composer, cocoapods, swift, ruby, r, conan, go, debian, and rpm.
Nexus formats are normalized as follows:
docker, raw, bower, Hex, and unknown formats are skipped. Swift discovery requires a Nexus Repository version that supports the Swift format.
Client routes
With route-mode: native, a discovered repository is published at /repository/{name}. For example:
The client or reverse proxy only needs to replace the Nexus host with the OSA Proxy host while preserving the path.
With route-mode: flat, OSA Proxy uses /{name}. A route-prefix in an individual routing rule takes precedence over route-mode; the resulting path is /{route-prefix}/{name}.
Static routes from ecosystem sections have the highest priority. If a discovered repository path conflicts with a static route, the dynamic route is skipped while the other discovered repositories continue to work.
Artifactory and Nexus can be enabled at the same time. In native mode, identical repository names normally do not conflict:
Identical or nested paths from different dynamic managers are considered a conflict. In that case, the new snapshot is rejected and OSA Proxy keeps the last successfully built dynamic routes.
Repository context in the URL
The url-encoded-config: true setting allows URL-safe Base64 metadata containing the repository manager URL, repository name, and user to be passed in a request. This is used for CodeScoring policies bound to a specific Nexus repository context.
For a native route, the encoded segment is placed after the complete repository path:
The object format and encoding examples are documented in Base64 URL configuration.
Block responses
Nexus receives the HTTP code configured in codescoring.block-status-code instead of 404. With codescoring.enable-status-line: true, the block reason is added to the HTTP/1.1 status line, matching the Nexus plugin behavior.
The status line supports ASCII only and does not exist in HTTP/2 or HTTP/3. If users must see the block reason, set codescoring.block-message to an ASCII string, for example Component download blocked by security policy.
If the HTTP code is correct but the reason is not displayed, inspect the reverse proxy in front of Nexus. Traefik, nginx, or the ingress controller must not overwrite the HTTP/1.1 status line.
Refresh and diagnostics
The first inventory sync runs at startup. Further syncs run at refresh.interval with up to 10% jitter. Added and removed repositories are applied without a restart.
When an HTTP, decoding, or route construction error occurs, OSA Proxy keeps the last successful snapshot. A successful empty inventory removes all dynamic Nexus routes. The snapshot is stored in memory only; after a restart with an unavailable Nexus, only static routes are available.
The /healthz endpoint checks the OSA Proxy process, not discovery status. Use these metrics:
nexus_discovery_syncs_total;nexus_discovery_sync_duration_seconds;nexus_discovery_last_success_timestamp_seconds;nexus_discovery_active_repositories;nexus_discovery_repository_changes_total.
The other supported repository manager is documented in JFrog Artifactory integration.