flytegg / flytegg/plugin-portal
Redesign GitHub Releases adapter
- Dominant language
- Kotlin
- Stars
- 92
- Forks
- 15
- Avg merge
- 49m
- Merged PRs (30d)
- 4
Description
## Summary
Redesign the GitHub Releases adapter so external plugins hosted on GitHub can be installed and updated reliably through Plugin Portal.
Credit to [Zoriot](https://github.com/Zoriot) for the report and adapter feedback.
## Problem
The current adapter system has an early GitHub Releases implementation, but it is not reliable enough to recommend as a polished feature. It is startup/config based, has limited user feedback, and appears to treat an existing adapter cache entry as up to date without comparing the cached version against the latest matching GitHub release.
Adapters should be useful for external plugins that are not available through normal marketplace indexing. GitHub Releases is the most important first target because many Minecraft plugins publish jars there.
## Goals
- Support GitHub Releases as a first-class external plugin source.
- Make install/update behavior predictable and visible to server operators.
- Match release assets by explicit rules so the correct `.jar` is selected.
- Track the installed release/version and detect newer matching releases correctly.
- Keep this focused on GitHub only. Jenkins and other custom adapters can be separate features.
## Non-goals
- Preserve compatibility with the current adapter config shape if a cleaner model is better.
- Implement Jenkins support in this issue.
- Implement custom Floodgate support in this issue.
- Rehost or mirror third-party artifacts to Plugin Portal or marketplaces.
## Proposed behavior
A GitHub adapter entry should be able to define:
- Repository, for example `ViaVersion/ViaVersion`.
- Release channel policy, such as stable releases only or include prereleases.
- Asset selection rule, usually a regex matching the desired `.jar`.
- Optional installed filename or display name.
- Optional authentication token for private repos or higher rate limits.
Plugin Portal should then be able to:
- Check the latest matching release.
- Compare it to the locally tracked adapter plugin version.
- Download the matching asset when installing or updating.
- Skip downloads when the installed adapter plugin is already current.
- Show clear output when no matching release, asset, or downloadable jar is found.
## Suggested command/config shape
Exact UX can change, but the feature should not rely only on silent startup behavior. Possible shape:
```yaml
adapters:
viaversion:
type: github
repo: ViaVersion/ViaVersion
includePrereleases: false
assetPattern: "^ViaVersion.*\\.jar$"
filename: "ViaVersion.jar"
```
Useful commands could include:
- `/pp adapter check `
- `/pp adapter install `
- `/pp adapter update `
- `/pp adapter updateAll`
- `/pp adapter list`
## Implementation notes
- Use GitHub release `tag_name` or immutable release/asset IDs for version tracking instead of just checking whether a repo is already in `adapter-plugins.json`.
- Prefer explicit asset matching and fail loudly if multiple assets match unexpectedly.
- Store adapter plugin state separately from normal marketplace plugin state, but make list/update output understandable.
- Consider rate limit handling and optional token support.
- Avoid updating during startup without clear operator control unless auto-update is explicitly enabled per adapter.
- Current code under `plugin/adapters/platforms/github` can be used as a reference, but the design should be allowed to replace it.
Contributor guide
Research direction
Start by reading the current implementation under plugin/adapters/platforms/github and map how adapter configuration, cached state, installation, and updates currently work. Review the proposed adapter commands and configuration shape, then define the smallest design that supports release and asset matching, version checks, and clear failure output. Done means GitHub adapters can install and update predictably without treating an existing cache entry as current.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github, kotlin
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100