• English

    • Repository groups

    A group combines several npm, Maven, or PyPI repositories under one URL. OSA Proxy merges member versions and checks them against CodeScoring policies.

    Configuration

    npm:
  enabled: true
  repository:
    - name: npm-internal
      registry: https://npm.example.com
    - name: npm-public
      registry: https://registry.npmjs.org
  group:
    - name: npm-all
      members: [npm-internal, npm-public]
      scan-manifest: true
      scan-package: true
      remove-blocked-versions: true
      continue-on-member-error: false
    npm config set registry https://osa-proxy.example.com/npm-all/

    The same group block is available in maven and pypi. Configure a Maven group as a regular repository or mirror, and a PyPI group as a Simple API index:

    pip install --index-url https://osa-proxy.example.com/pypi-all/simple/ requests
    ParameterPurpose
    nameUnique group name and public path /{name}/. Must not match a repository or another group name.
    membersNonempty list of distinct regular repository names from the same section, in priority order. Nested groups are not supported.
    scan-manifest, scan-package, work-mode, url-encoded-config, file-type-filterCheck settings for requests through the group. The corresponding member settings do not apply to these requests.
    remove-blocked-versionsFor npm and PyPI: remove blocked versions (true by default) or retain them with block markers (false). Omit this parameter for Maven: blocked versions are always removed.
    continue-on-member-errorContinue with other members when one fails. Defaults to false.

    Members use their own timeouts. In Configuration Store, groups are set in the groups field; see Admin API. Member health is available in metrics.

    Source priority and policies

    Version lists are merged from member responses. When multiple members provide the same npm version or PyPI file, the first entry in members wins.

    For downloads, OSA Proxy searches members in order and moves to the next one only after a 404 response.

    Checks use the Artifactory or Nexus repository context of the source of the version or file. A public registry without that context uses the default policy. Context supplied through url-encoded-config replaces member context. A blocked version is not replaced with the same version from another member.

    Member authentication

    Groups do not forward client Authorization or cookies to members. In YAML, a member's username and password can be set in the registry URL. Configuration Store does not accept credentials in URLs, so group members configured through it must allow anonymous reads.

    Unavailable members

    By default, a member failure prevents fallback to the next source:

    • When merging version lists, the client receives 502. For any failure other than 401 and 403, the last complete cached document is used instead if it is not older than group-metadata-stale-if-error.
    • During file lookup, the client receives 502. If no member has the file, the client receives 404.

    With continue-on-member-error: true, the group skips failed members: it merges lists from responding members and searches subsequent members for files. If the file is not found but a member failed, the client receives 502.

    Fallback source selection

    With continue-on-member-error: true, a package from an unavailable private repository may be replaced by a package with the same name from a public source (dependency confusion). Enable this setting only where that fallback is acceptable. Downloaded packages are still checked against CodeScoring policies.

    Caching and limits

    Merged metadata is cached, and policies apply to every response. Group cache and concurrency settings (group-*) belong in http.client and require a restart.

    npm supports package documents, version or tag documents, dist-tags, and tarballs; search, audit, whoami, and ping are unavailable through a group. PyPI supports HTML and JSON project pages at /simple/<name>/ and file downloads; the root project list and legacy JSON API are unavailable.

    Was this page helpful?