Container Registry Integrations

Container registry integrations track new releases and versions of container images, helping you keep your infrastructure up to date.

Supported Registries

Docker Hub

Official Docker registry

GitHub Container Registry

GitHub’s container platform

Quay

Red Hat’s container registry

Docker Hub

Track Docker image releases and updates from Docker Hub.

Configuration

url

string

default:"https://hub.docker.com"

Docker Hub URL (usually default)

username

string

Docker Hub username (optional, for private images)

personalAccessToken

string

Docker Hub personal access token (optional, for authentication)

Authentication is optional for public images but required for:

Private repositories
Higher API rate limits
Organizational repositories

Generating a Personal Access Token

Navigate to hub.docker.com

Account Settings

Click your username → Account Settings → Security

Create Token

Click New Access Token

Configure Token

Description: “Homarr”
Access permissions: Read-only

Copy Token

Save the token immediately - it’s shown only once!

Available Features

Release Tracking

Monitor container image versions:

Latest matching release
Version tags and digests
Release timestamps
Image size information
Pull count statistics
Star count
Description and README
Links to repository page

API Method: getLatestMatchingReleaseAsync(identifier, versionRegex?)Supported formats:

library/image-name - Official images
username/image-name - User images
organization/image-name - Org images
image-name - Official library images (shorthand)

Version Filtering

Use regex patterns to match specific versions:

// Get latest stable (non-beta) version
await integration.getLatestMatchingReleaseAsync(
  'nginx',
  '^\\d+\\.\\d+\\.\\d+$'
);

// Get latest LTS version
await integration.getLatestMatchingReleaseAsync(
  'node',
  '^\\d+\\.\\d+\\.\\d+-alpine$'
);

// Get specific major version
await integration.getLatestMatchingReleaseAsync(
  'postgres',
  '^15\\.'
);

The integration searches up to 5 pages (500 tags) to find a match.

Release Response

{
  success: true,
  data: {
    // Version information
    name: "1.25.3",
    version: "1.25.3",
    versionName: "1.25.3",
    createdAt: "2024-01-15T10:30:00Z",
    
    // Repository details
    projectUrl: "https://hub.docker.com/r/library/nginx",
    projectDescription: "Official build of Nginx",
    starsCount: 15420,
    
    // Image metadata
    size: 142000000,  // bytes
    pullCount: 1000000000,
    digest: "sha256:abc123..."
  }
}

On failure:

{
  success: false,
  error: {
    code: "noMatchingVersion" | "invalidIdentifier" | "unexpected",
    message?: "Error details"
  }
}

Session Management

Docker Hub integration includes automatic session handling:

Access tokens are cached per integration
Tokens auto-refresh on expiration (401 errors)
Unauthenticated mode for public images
Efficient API usage

Example Configuration

Public Images
With Authentication

{
  "name": "Docker Hub",
  "url": "https://hub.docker.com",
  "secrets": {}
}

No authentication needed for public images.

{
  "name": "Docker Hub",
  "url": "https://hub.docker.com",
  "secrets": {
    "username": "your-username",
    "personalAccessToken": "dckr_pat_xxxxx"
  }
}

Required for private images and higher rate limits.

Usage Examples

// Track official Nginx image
await dockerHub.getLatestMatchingReleaseAsync('nginx');

// Track specific user image
await dockerHub.getLatestMatchingReleaseAsync('linuxserver/plex');

// Track with version filter
await dockerHub.getLatestMatchingReleaseAsync(
  'postgres',
  '^15\\.\\d+\\.\\d+$'
);

GitHub Container Registry (GHCR)

Monitor container images from GitHub Container Registry.

Configuration

url

string

default:"https://ghcr.io"

GHCR URL (usually default)

token

string

GitHub Personal Access Token with read:packages scope

Generating a GitHub Token

GitHub Settings

Go to GitHub → Settings → Developer settings

Personal Access Tokens

Click Personal access tokens → Tokens (classic)

Generate New Token

Click Generate new token (classic)

Select Scopes

Enable:

read:packages - Read packages and metadata
Optionally repo if tracking private repositories

Generate

Click Generate token and copy it immediately

Available Features

Track GHCR container releases
Monitor organization packages
Private package support
Version filtering with regex
Package metadata and stats

Package Identifier Format

ghcr.io/owner/package-name

Examples:

ghcr.io/homarr-labs/homarr - Organization package
ghcr.io/username/my-app - User package

Example Configuration

{
  "name": "GitHub Container Registry",
  "url": "https://ghcr.io",
  "secrets": {
    "token": "ghp_xxxxxxxxxxxxx"
  }
}

Quay.io

Monitor container images from Red Hat’s Quay registry.

Configuration

url

string

default:"https://quay.io"

Quay URL (usually default)

token

string

Quay OAuth token (optional, for private repos)

Generating a Quay Token

Navigate to quay.io

Account Settings

Click your username → Account Settings

Generate Token

Go to Robot Accounts or OAuth Applications

Create Application

Create a new OAuth application for Homarr

Copy Token

Save the OAuth token

Available Features

Public image tracking
Private repository support
Organization repositories
Version filtering
Security scanning results
Vulnerability information

Example Configuration

{
  "name": "Quay",
  "url": "https://quay.io",
  "secrets": {
    "token": "your-quay-token"
  }
}

Comparison

Registry	Authentication	Public Images	Private Images	Rate Limits
Docker Hub	Optional PAT	✅	✅ (with auth)	100/6h (unauth), 200/6h (auth)
GHCR	GitHub PAT	✅	✅	Generous
Quay	OAuth Token	✅	✅	Generous

Version Regex Patterns

Common regex patterns for version filtering:

Semantic Versioning
Exclude Pre-releases
Date-based Tags

# Any semantic version
^\d+\.\d+\.\d+$

# Specific major version
^15\.\d+\.\d+$

# Version with suffix
^\d+\.\d+\.\d+-alpine$

# No beta/alpha/rc
^\d+\.\d+\.\d+$

# With suffix but no pre-release
^\d+\.\d+\.\d+-(?!beta|alpha|rc)[a-z]+$

# YYYY-MM-DD format
^\d{4}-\d{2}-\d{2}$

# Latest tag
^latest$

# Nightly builds
^nightly-\d{8}$

Use registry integrations with the Release Tracker widget:

Add Widget

Edit Mode → Add Widget → Release Tracker

Select Registry

Choose your configured registry integration

Configure Tracking

Enter image identifier
Optional: Set version regex filter
Set refresh interval

Display Options

Show/hide descriptions
Display star counts
Show pull statistics
Link to registry page

Latest version badge
“New version available” notifications
One-click links to registry
Release date tracking
Auto-refresh support

API Rate Limits

Docker Hub

Unauthenticated:

100 pulls per 6 hours per IP
API rate limits apply

Authenticated:

200 pulls per 6 hours
Higher API rate limits
Access to private repositories

Always authenticate for production use to avoid rate limiting.

GitHub Container Registry

Very high rate limits
No pull limits for public images
Authentication required for private packages

Quay

Generous rate limits
No strict pull limits
Authentication for private repos

Troubleshooting

Rate Limited (Docker Hub)

Symptoms: “Rate limit exceeded” or 429 errors Solutions:

Add authentication (username + PAT)
Reduce refresh frequency
Wait for rate limit reset (6 hours)
Use Docker Hub Pro account for unlimited pulls

Image Not Found

Symptoms: “404 Not Found” or “invalidIdentifier” error Solutions:

Verify image name spelling
Check if image is public (or add auth for private)
Ensure organization/user name is correct
Test URL manually in browser

No Matching Version

Symptoms: “noMatchingVersion” error Solutions:

Verify version regex pattern
Check available tags in registry UI
Broaden regex pattern
Remove version filter to see all versions

Authentication Failed

Symptoms: “Unauthorized” or “Invalid credentials” Solutions:

Verify PAT/token hasn’t expired
Check token has correct scopes/permissions
Regenerate token if necessary
For Docker Hub, use PAT not password

Best Practices

Use Specific Tags: Don’t rely on latest tag in production
Version Filtering: Use regex to track stable releases only
Authentication: Always auth for private images and higher limits
Multiple Registries: Track images from multiple registries
Monitoring: Set up notifications for new releases
Documentation: Document which images you track and why

Next Steps

Release Widget

Create release tracking widgets

Troubleshooting

Common integration issues

API Reference

Integration API documentation

Get Started

Core Features

Configuration

Integrations

Guides

​Supported Registries

Docker Hub

GitHub Container Registry

Quay

​Docker Hub

​Configuration

​Generating a Personal Access Token

​Available Features

​Session Management

​Example Configuration

​Usage Examples

​GitHub Container Registry (GHCR)

​Configuration

​Generating a GitHub Token

​Available Features

​Package Identifier Format

​Example Configuration

​Quay.io

​Configuration

​Generating a Quay Token

​Available Features

​Example Configuration

​Comparison

​Version Regex Patterns

​Widget: Release Tracker

​Widget Features

​API Rate Limits

​Docker Hub

​GitHub Container Registry

​Quay

​Troubleshooting

​Rate Limited (Docker Hub)

​Image Not Found

​No Matching Version

​Authentication Failed

​Best Practices

​Next Steps

Release Widget

Troubleshooting

API Reference

Build docs developers (and LLMs) love

Supported Registries

Docker Hub

Configuration

Generating a Personal Access Token

Available Features

Session Management

Example Configuration

Usage Examples

GitHub Container Registry (GHCR)

Configuration

Generating a GitHub Token

Available Features

Package Identifier Format

Example Configuration

Quay.io

Configuration

Generating a Quay Token

Available Features

Example Configuration

Comparison

Version Regex Patterns

Widget: Release Tracker

Widget Features

API Rate Limits

Docker Hub

GitHub Container Registry

Quay

Troubleshooting

Rate Limited (Docker Hub)

Image Not Found

No Matching Version

Authentication Failed

Best Practices

Next Steps