Add opt-in GHCR latest-version lookup from GitHub Releases

[Copilot]

Some GHCR-backed projects publish the version signal in GitHub Releases rather than in container package tags, which makes latest-version detection unreliable for those images. This change adds an explicit per-container switch to source latest versions from GitHub Releases when needed, and documents a known configuration for n8n.

• New annotation for GHCR release-backed version discovery

  • Adds use-github-release.version-checker.io/<container>: "true" to opt a container into GitHub Releases as the source of version candidates.
  • Keeps existing GHCR behavior unchanged unless the annotation is present.

• GHCR client support for GitHub Releases

  • Adds a GHCR release lookup path that lists repository releases and converts release tags into ImageTag entries.
  • Ignores draft releases and preserves release timestamps for existing semver selection logic.

• Option plumbing through version resolution

  • Threads the new option through the version/client fetch path so latest-version resolution can choose GHCR package tags or GitHub Releases per container.
  • Separates cache entries for release-backed lookups from default image-tag lookups.

• Docs and known configurations

  • Documents the new annotation in installation docs.
  • Adds an example known configuration for ghcr.io/n8n-io/n8n.

Example:

metadata:
  annotations:
    enable.version-checker.io/n8n: "true"
    use-github-release.version-checker.io/n8n: "true"

[Copilot]

Pull request overview

This PR adds an opt-in mechanism for GHCR images to source “latest version” candidates from the backing GitHub repository’s Releases (instead of GHCR package tags), improving correctness for projects where GHCR tags aren’t a reliable version signal.

Changes:

• Introduces use-github-release.version-checker.io/<container>: "true" annotation, plumbed into api.Options and the controller option builder.
• Extends the registry client interface to accept options and adds a GHCR GitHub-Releases lookup path that converts release tags into ImageTag candidates (skipping drafts).
• Separates caching for release-backed lookups vs tag-backed lookups, and documents a known configuration for ghcr.io/n8n-io/n8n.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/version/version.go	Passes options through cache fetch and separates image-tag cache keys for release-backed lookups.
pkg/version/version_test.go	Updates mocks/tests to match the new Tags(..., opts) signature.
pkg/controller/options/options.go	Adds parsing of the new use-github-release annotation into api.Options.
pkg/controller/options/options_test.go	Adds test coverage for the new option and its incompatibility with use-sha.
pkg/client/ghcr/ghcr.go	Implements GitHub Releases listing and converts release tags to ImageTag entries with timestamps.
pkg/client/ghcr/ghcr_test.go	Adds unit test coverage for GHCR release tag extraction behavior (draft filtering, timestamps).
pkg/client/client.go	Extends client handler API with options and routes GHCR lookups to Releases when opted in.
pkg/client/client_test.go	Adds an integration-style test ensuring the client uses Releases for GHCR when configured.
pkg/api/options.go	Adds UseGitHubRelease option flag.
pkg/api/annotations.go	Adds UseGitHubReleaseAnnotationKey constant.
known-configurations.md	Documents an n8n configuration using the new annotation.
docs/installation.md	Documents the new annotation in installation instructions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.