GitHub - robfrank/kamal-accessories-updater: Action to keep Kamal accessories updated (original) (raw)

Test Release

A GitHub Action that automatically checks for and updates Kamal accessories to their latest versions from Docker Hub, GitHub Container Registry (GHCR), and other OCI registries.

Features

Quick Start

Add this action to your workflow to automatically check for accessory updates:

name: Update Kamal Accessories

on: workflow_dispatch: schedule: - cron: "0 8 * * 0" # Every Sunday at 8 AM UTC

jobs: update: runs-on: ubuntu-latest permissions: contents: write pull-requests: write steps: - uses: actions/checkout@v4

  - name: Update Kamal accessories
    uses: robfrank/kamal-accessories-updater@v25
    with:
      config-dir: config
      mode: update-all
      create-pr: true
      github-token: ${{ secrets.GITHUB_TOKEN }}

Inputs

Input Description Required Default
config-dir Directory containing Kamal deploy*.yml files No config
mode Update mode: check, update, or update-all No update-all
create-pr Whether to create a pull request with updates No true
pr-branch Branch name for the pull request No update/kamal-accessories
pr-title Title for the pull request No chore: bump Kamal accessories versions
pr-body Body text for the pull request No See action.yml
pr-labels Comma-separated list of labels for the PR No dependencies
github-token GitHub token for creating pull requests No ${{ github.token }}

Mode Options

Outputs

Output Description
updates-available Whether any updates are available (true/false)
updates-count Number of updates available
updates-json JSON array of all updates
pr-number Pull request number if created
pr-url Pull request URL if created

Usage Examples

Basic Usage

Check for updates and create a PR:

Check Only (No Updates)

Update Without PR

Custom PR Configuration

How It Works

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

Supported Accessories

This action works with any Docker image used as a Kamal accessory. Common examples include:

Supported Registries

The action supports multiple container registries:

Docker Hub (docker.io)

Default registry - No authentication required for public images.

accessories: redis: image: redis:7.0.0 # Official image (implicit docker.io)

custom: image: myorg/myapp:1.0.0 # Organization image

explicit: image: docker.io/library/postgres:15 # Explicit registry prefix

GitHub Container Registry (ghcr.io)

Requires authentication for most operations. Set the GHCR_TOKEN environment variable with a GitHub Personal Access Token (PAT) or use the automatic GITHUB_TOKEN.

accessories: myapp: image: ghcr.io/myorg/myapp:1.0.0

public: image: ghcr.io/owner/public-image:2.0.0

GitHub Action Configuration for GHCR:

For private GHCR images, create a GitHub PAT with read:packages scope:

env: GHCR_TOKEN: ${{ secrets.GHCR_PAT }} # Use custom PAT for private images

Other Registries

The action includes detection for:

Support for additional registries is being actively developed. Open an issue if you need support for a specific registry.

Configuration File Format

Your Kamal configuration files should follow the standard format:

accessories:

Docker Hub - official image (default registry)

redis: image: redis:7.0.0 host: 192.168.0.1 # ... other configuration

Docker Hub - with SHA256 digest

postgres: image: postgres:15.0@sha256:abc123... host: 192.168.0.1 # ... other configuration

GitHub Container Registry

myapp: image: ghcr.io/myorg/myapp:1.2.3@sha256:def456... host: 192.168.0.1 # ... other configuration

Docker Hub - organization image

custom: image: mycompany/myservice:2.0.0 host: 192.168.0.1 # ... other configuration

The action will:

Caching

The action caches registry API responses for 1 hour to:

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

Testing

Run the test suite locally:

Run all tests

./test/run-tests.sh

Run unit tests only

./test/test-utils.sh

Run integration tests only

./test/test-integration.sh

Development

Project Structure

.
├── action.yml                    # Action metadata
├── src/
│   ├── check-updates.sh         # Main update logic
│   └── utils.sh                 # Utility functions
├── test/
│   ├── fixtures/                # Test configurations
│   ├── test-utils.sh           # Unit tests
│   ├── test-integration.sh     # Integration tests
│   └── run-tests.sh            # Test runner
└── .github/
    └── workflows/
        ├── test.yml            # CI workflow
        ├── release.yml         # Release workflow
        └── upgrade-accessories-versions.yml  # Example workflow

Running Locally

You can test the action locally with your own configuration:

Check for updates only

./src/check-updates.sh path/to/config check

Update all accessories

./src/check-updates.sh path/to/config update-all

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for your changes
  4. Ensure all tests pass
  5. Submit a pull request

License

This project is licensed under the ASL 2.0 License - see the LICENSE file for details.

Acknowledgments

Support

If you encounter any issues or have questions: