Providers Configuration

The providers.yaml file configures global defaults for package providers. These settings apply to all packages using each provider unless overridden in lists.yaml.

File Location

Place providers.yaml in your config directory:

Docker: /data/config/providers.yaml (default)
Custom: Set via SERVER_CONFIG_DIR environment variable

Basic Structure

providers.yaml

github:
  extra:
    maxReleases: 5
    includePrereleases: false

npm:
  extra:
    tags:
      - latest
      - beta

docker:
  extra:
    tags:
      - latest
      - slim
      - alpine

python:
  extra:
    maxReleases: 5

Provider Configuration

Each provider can have an extra object with provider-specific options. These act as defaults that can be overridden per-package in lists.yaml.

Supported Providers

GitHub
NPM
Docker
Python

GitHub Provider

Fetches releases from GitHub repositories.

github.extra.maxReleases

number

default:3

Maximum number of releases to fetch per repository (1-10).Default: 3

github.extra.includePrereleases

boolean

default:false

Whether to include pre-release versions in the results.Default: false

Example

github:
  extra:
    maxReleases: 5
    includePrereleases: false

Implementation Details

Fetches from GitHub’s REST API
Filters out draft releases
Optionally filters out pre-releases based on includePrereleases
Limits results to maxReleases (clamped between 1 and 10)
Package format: owner/repo (e.g., facebook/react)

NPM Provider

Fetches package information from NPM registry.

npm.extra.tags

string[]

default:["latest"]

Array of NPM dist-tags to track. Common tags include:

latest - Latest stable version
beta - Beta releases
next - Next version
canary - Canary builds
Custom tags defined by package maintainers

Default: ["latest"]

npm.extra.npmx

boolean

default:false

Use npmx.dev instead of npmjs.com as the external link to the package.Default: false

Example

npm:
  extra:
    tags:
      - latest
      - beta
      - next
    npmx: false

Implementation Details

Fetches from NPM’s registry API
Supports scoped packages (e.g., @types/node)
Extracts owner from scoped package names
Links to npmjs.com or npmx.dev based on npmx setting
Fetches specific dist-tags defined in tags

Docker Provider

Fetches image tags from Docker Hub.

docker.extra.tags

string[]

default:["latest","slim","alpine"]

Array of Docker image tags to track. Common tags include:

latest - Latest version
alpine - Alpine-based images
slim - Slim/minimal images
Version-specific tags (e.g., 16-alpine, 20.10.0)

Default: ["latest", "slim", "alpine"]

Example

docker:
  extra:
    tags:
      - latest
      - alpine
      - slim

Implementation Details

Fetches from Docker Hub API
Handles both official images (node → library/node) and user images (user/image)
Fetches each tag individually with retry logic
Filters out invalid releases without digest
Links to hub.docker.com

Python Provider

Fetches package information from PyPI (Python Package Index).

python.extra.maxReleases

number

default:3

Maximum number of releases to fetch per package.Default: 3

Example

python:
  extra:
    maxReleases: 5

Implementation Details

Fetches from PyPI’s JSON API
Returns the most recent releases up to maxReleases
Links to pypi.org
Package format: PyPI package name (e.g., django, requests)

Schema Structure

The providers.yaml configuration uses the following schema:

const ProviderConfig = Schema.Struct({
  extra: Schema.Record({
    key: Schema.String,
    value: Schema.Union(
      Schema.String,
      Schema.Boolean,
      Schema.Number,
      Schema.Array(Schema.Union(Schema.String, Schema.Boolean, Schema.Number)),
    ),
  }).pipe(Schema.optional),
});

const ProvidersConfig = Schema.Record({
  key: Schema.String,  // Provider name
  value: ProviderConfig,
});

This allows flexible configuration of any provider with typed extra options.

Default Values

If providers.yaml is missing or a provider is not configured, Shipped uses these defaults:

github:
  extra:
    includePrereleases: false
    maxReleases: 3

Overriding Per-Package

Global provider settings can be overridden for individual packages in lists.yaml:

lists.yaml

# Global GitHub settings: maxReleases=3, includePrereleases=false
# This package overrides to show 10 releases including pre-releases

- name: My Packages
  groups:
    - name: frameworks
      packages:
        - provider: github
          name: vuejs/vue
          extra:
            maxReleases: 10
            includePrereleases: true

The package-level extra options are merged with provider defaults, with package-level values taking precedence.

Complete Example

providers.yaml

# GitHub provider defaults
github:
  extra:
    # Fetch up to 5 releases per repository
    maxReleases: 5
    # Don't include pre-release versions
    includePrereleases: false

# NPM provider defaults
npm:
  extra:
    # Track latest, beta, and next dist-tags
    tags:
      - latest
      - beta
      - next
    # Use npmjs.com for links (not npmx.dev)
    npmx: false

# Docker provider defaults
docker:
  extra:
    # Track latest, alpine, and slim tags
    tags:
      - latest
      - alpine
      - slim

# Python provider defaults
python:
  extra:
    # Fetch up to 5 releases per package
    maxReleases: 5

Validation and Error Handling

Validation Rules

Provider names - Must be one of: github, npm, docker, python
Extra fields - Must match the provider’s schema:
- GitHub: maxReleases (number), includePrereleases (boolean)
- NPM: tags (string[]), npmx (boolean)
- Docker: tags (string[])
- Python: maxReleases (number)
Type checking - Values must match expected types (string, boolean, number, or arrays)

Invalid Configuration Handling

When provider configuration is invalid:

The invalid provider configuration is ignored
Default values are used for that provider
A warning is logged with validation details
The application continues running normally

If the entire providers.yaml file is malformed (invalid YAML syntax), the file is ignored and defaults are used for all providers.

IDE Autocompletion

Enable IDE autocompletion by adding the schema reference:

providers.yaml

# yaml-language-server: $schema: https://raw.githubusercontent.com/nipakke/shipped/main/docs/config-files/providers.json

github:
  extra:
    maxReleases: 5
    includePrereleases: false

This provides:

Provider name autocompletion
Field validation for each provider
Type hints for configuration values

Hot Reloading

Changes to providers.yaml are automatically detected and applied without restart:

Edit providers.yaml in your config directory
Save the file
Shipped automatically reloads provider configuration
All packages use the new defaults on next fetch

Cached package data is not immediately refetched. Wait for the cache TTL (default: 3 hours) or restart to force a refetch with new provider settings.

Common Patterns

Track pre-releases globally

Enable pre-releases for all GitHub packages:

providers.yaml

github:
  extra:
    maxReleases: 5
    includePrereleases: true

Track multiple NPM dist-tags

Set up tracking for latest, beta, and canary builds:

providers.yaml

npm:
  extra:
    tags:
      - latest
      - beta
      - canary
      - next

Customize Docker image variants

Track specific image variants across all Docker packages:

providers.yaml

docker:
  extra:
    tags:
      - latest
      - alpine
      - 16-alpine
      - 20-alpine

Increase release history

Show more releases for better version history:

providers.yaml

github:
  extra:
    maxReleases: 10

python:
  extra:
    maxReleases: 10

Cache Considerations

Provider settings affect how packages are fetched, but cached data is not immediately invalidated:

Cache TTL: Default 3 hours (10,800 seconds)
Force refresh: Restart the container to clear cache
Disable cache: Set SERVER_PACKAGES_CACHE_DISABLED=true

To see provider configuration changes immediately, restart the container or wait for the cache to expire.

Environment Variables

Some provider behaviors can be influenced by environment variables:

Variable	Type	Default	Description
`SERVER_PACKAGES_FETCH_CONCURRENCY`	integer	10	Max parallel package fetches
`SERVER_PACKAGES_CACHE_TTL`	integer	10800	Cache TTL in seconds
`SERVER_PACKAGES_CACHE_DISABLED`	boolean	false	Disable package caching

Overview

Getting Started

Configuration

Providers

Features

Advanced

Providers Configuration

File Location

Basic Structure

Provider Configuration

Supported Providers

GitHub Provider

NPM Provider

Docker Provider

Python Provider

Schema Structure

Default Values

Overriding Per-Package

Complete Example

Validation and Error Handling

Invalid Configuration Handling

IDE Autocompletion

Hot Reloading

Common Patterns

Cache Considerations

Environment Variables

Next Steps

Lists Configuration

General Settings

Build docs developers (and LLMs) love

Overview

Getting Started

Configuration

Providers

Features

Advanced

​File Location

​Basic Structure

​Provider Configuration

​Supported Providers

​GitHub Provider

​NPM Provider

​Docker Provider

​Python Provider

​Schema Structure

​Default Values

​Overriding Per-Package

​Complete Example

​Validation and Error Handling

​Invalid Configuration Handling

​IDE Autocompletion

​Hot Reloading

​Common Patterns

​Cache Considerations

​Environment Variables

​Next Steps

Lists Configuration

General Settings

Build docs developers (and LLMs) love

File Location

Basic Structure

Provider Configuration

Supported Providers

GitHub Provider

NPM Provider

Docker Provider

Python Provider

Schema Structure

Default Values

Overriding Per-Package

Complete Example

Validation and Error Handling

Invalid Configuration Handling

IDE Autocompletion

Hot Reloading

Common Patterns

Cache Considerations

Environment Variables

Next Steps