Skip to content

Commit 7d009d6

Browse files
committed
Add support for multiple Docker registries including ghcr.io
This commit adds comprehensive multi-registry support to the Kamal Accessories Updater, starting with GitHub Container Registry (ghcr.io). Key Changes: - Added parse_image_name() function to parse registry prefix from image names (e.g., ghcr.io/org/image, docker.io/library/redis) - Added detect_registry_type() function to identify registry type - Implemented GHCR-specific functions: * get_latest_version_ghcr() - Fetches tags from GHCR with token auth * get_image_sha256_ghcr() - Retrieves SHA256 digests from GHCR - Refactored Docker Hub functions into registry-specific implementations: * get_latest_version_dockerhub() * get_image_sha256_dockerhub() - Updated main dispatcher functions to route to appropriate registry handlers - Enhanced caching to support multiple registries with separate cache keys - Added GHCR_TOKEN environment variable support for authentication Registry Support: - Docker Hub (docker.io) - Full support, no auth required for public images - GitHub Container Registry (ghcr.io) - Full support with token authentication - Google Container Registry (gcr.io) - Detection ready - Quay.io - Detection ready - Generic OCI registries - Basic detection Documentation: - Updated README with multi-registry support information - Added "Supported Registries" section with examples - Documented GHCR authentication requirements - Added configuration examples for different registries - Updated "How It Works" section to reflect registry detection The implementation maintains backward compatibility with existing Docker Hub configurations while enabling users to specify registry prefixes for images from other registries.
1 parent ecbebed commit 7d009d6

File tree

2 files changed

+413
-49
lines changed

2 files changed

+413
-49
lines changed

README.md

Lines changed: 88 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,12 @@
33
[![Test](https://github.com/robfrank/kamal-accessories-updater/actions/workflows/test.yml/badge.svg)](https://github.com/robfrank/kamal-accessories-updater/actions/workflows/test.yml)
44
[![Release](https://github.com/robfrank/kamal-accessories-updater/actions/workflows/release.yml/badge.svg)](https://github.com/robfrank/kamal-accessories-updater/actions/workflows/release.yml)
55

6-
A GitHub Action that automatically checks for and updates [Kamal](https://kamal-deploy.org/) accessories to their latest versions from Docker Hub.
6+
A GitHub Action that automatically checks for and updates [Kamal](https://kamal-deploy.org/) accessories to their latest versions from Docker Hub, GitHub Container Registry (GHCR), and other OCI registries.
77

88
## Features
99

10-
- 🔍 **Automatic Version Detection** - Scans your Kamal deployment configurations for accessories and checks Docker Hub for latest versions
10+
- 🔍 **Automatic Version Detection** - Scans your Kamal deployment configurations for accessories and checks registries for latest versions
11+
- 🌐 **Multi-Registry Support** - Works with Docker Hub, GitHub Container Registry (ghcr.io), and other OCI-compliant registries
1112
- 📦 **Semantic Versioning** - Intelligently compares semantic versions to ensure only newer versions are applied
1213
- 🔒 **SHA256 Support** - Automatically fetches and includes SHA256 digests for enhanced security
1314
- 📝 **Pull Request Creation** - Optionally creates pull requests with detailed update information
@@ -139,11 +140,12 @@ Check for updates and create a PR:
139140

140141
1. **Scans Configuration Files** - Finds all `deploy*.yml` files in your config directory
141142
2. **Extracts Accessories** - Parses YAML to identify accessories and their current versions
142-
3. **Checks Docker Hub** - Queries Docker Hub API for latest semantic versions
143-
4. **Compares Versions** - Intelligently compares versions to determine if updates are available
144-
5. **Fetches Digests** - Retrieves SHA256 digests for the latest versions
145-
6. **Updates Files** - Modifies your configuration files with new versions and digests
146-
7. **Creates PR** - Optionally creates a pull request with the changes
143+
3. **Detects Registry** - Automatically detects the registry (Docker Hub, GHCR, etc.) from the image name
144+
4. **Queries Registry API** - Fetches latest semantic versions from the appropriate registry
145+
5. **Compares Versions** - Intelligently compares versions to determine if updates are available
146+
6. **Fetches Digests** - Retrieves SHA256 digests for the latest versions
147+
7. **Updates Files** - Modifies your configuration files with new versions and digests
148+
8. **Creates PR** - Optionally creates a pull request with the changes
147149

148150
## Supported Accessories
149151

@@ -156,37 +158,112 @@ This action works with any Docker image used as a Kamal accessory. Common exampl
156158
- BusyBox (`busybox`)
157159
- Any custom Docker image on Docker Hub
158160

161+
## Supported Registries
162+
163+
The action supports multiple container registries:
164+
165+
### Docker Hub (docker.io)
166+
167+
**Default registry** - No authentication required for public images.
168+
169+
```yaml
170+
accessories:
171+
redis:
172+
image: redis:7.0.0 # Official image (implicit docker.io)
173+
174+
custom:
175+
image: myorg/myapp:1.0.0 # Organization image
176+
177+
explicit:
178+
image: docker.io/library/postgres:15 # Explicit registry prefix
179+
```
180+
181+
### GitHub Container Registry (ghcr.io)
182+
183+
**Requires authentication** for most operations. Set the `GHCR_TOKEN` environment variable with a GitHub Personal Access Token (PAT) or use the automatic `GITHUB_TOKEN`.
184+
185+
```yaml
186+
accessories:
187+
myapp:
188+
image: ghcr.io/myorg/myapp:1.0.0
189+
190+
public:
191+
image: ghcr.io/owner/public-image:2.0.0
192+
```
193+
194+
**GitHub Action Configuration for GHCR:**
195+
196+
```yaml
197+
- name: Update accessories
198+
uses: robfrank/kamal-accessories-updater@v1
199+
with:
200+
config-dir: config
201+
env:
202+
GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Use GitHub token for GHCR access
203+
```
204+
205+
**For private GHCR images**, create a GitHub PAT with `read:packages` scope:
206+
207+
```yaml
208+
env:
209+
GHCR_TOKEN: ${{ secrets.GHCR_PAT }} # Use custom PAT for private images
210+
```
211+
212+
### Other Registries
213+
214+
The action includes detection for:
215+
- **Google Container Registry** (gcr.io)
216+
- **Quay.io** (quay.io)
217+
- **Generic OCI registries** (basic support)
218+
219+
Support for additional registries is being actively developed. Open an issue if you need support for a specific registry.
220+
159221
## Configuration File Format
160222

161223
Your Kamal configuration files should follow the standard format:
162224

163225
```yaml
164226
accessories:
227+
# Docker Hub - official image (default registry)
165228
redis:
166229
image: redis:7.0.0
167230
host: 192.168.0.1
168231
# ... other configuration
169232
233+
# Docker Hub - with SHA256 digest
170234
postgres:
171235
image: postgres:15.0@sha256:abc123...
172236
host: 192.168.0.1
173237
# ... other configuration
238+
239+
# GitHub Container Registry
240+
myapp:
241+
image: ghcr.io/myorg/myapp:1.2.3@sha256:def456...
242+
host: 192.168.0.1
243+
# ... other configuration
244+
245+
# Docker Hub - organization image
246+
custom:
247+
image: mycompany/myservice:2.0.0
248+
host: 192.168.0.1
249+
# ... other configuration
174250
```
175251

176252
The action will:
253+
- Automatically detect the registry from the image name
177254
- Preserve your existing configuration structure
178255
- Update only the image version
179256
- Add or update SHA256 digests
180257
- Keep all other settings intact
181258

182259
## Caching
183260

184-
The action caches Docker Hub API responses for 1 hour to:
261+
The action caches registry API responses for 1 hour to:
185262
- Reduce API calls
186263
- Improve performance
187264
- Avoid rate limiting
188265

189-
Cache is stored in `/tmp/docker-registry-cache` and automatically cleaned up.
266+
Cache is stored in `/tmp/docker-registry-cache` and automatically cleaned up. Each registry is cached separately to ensure accuracy.
190267

191268
## Testing
192269

@@ -256,6 +333,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
256333
- [Kamal Documentation](https://kamal-deploy.org/)
257334
- [Kamal Accessories Guide](https://kamal-deploy.org/docs/configuration/accessories/)
258335
- [Docker Hub API](https://docs.docker.com/registry/spec/api/)
336+
- [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
337+
- [OCI Distribution Spec](https://github.com/opencontainers/distribution-spec)
259338

260339
## Acknowledgments
261340

0 commit comments

Comments
 (0)