jellyfin-scene-search/docs/gitea-jellyfin-distribution.md

Distribute the Jellyfin plugin using Gitea

This project is private on GitHub and mirrored to private Gitea. Do not make that source mirror public. Jellyfin needs a separate public Gitea repository containing only a catalog manifest and binary release attachments.

One-time setup

1. In Gitea (https://git.trufflemonkey.co.uk), create an empty public distribution repository, e.g. sleeps/jellyfin-plugins. It must not be a pull mirror. Initialise a default main branch (for example with a README).
2. Create a Gitea access token with write access limited to that public distribution repository (repository contents and releases). Store it as a GitHub Actions secret, GITEA_RELEASE_TOKEN. Never commit the token.
3. In this private GitHub repository set the Actions variables:
   • GITEA_URL = https://git.trufflemonkey.co.uk
   • GITEA_DISTRIBUTION_REPO = sleeps/jellyfin-plugins
4. Before tagging, update <Version> in jellyfin-plugin/Jellyfin.Plugin.SceneSearch/Jellyfin.Plugin.SceneSearch.csproj and merge it to main.
5. Create/push the matching tag, e.g. v0.1.5.0, on the commit you want to release. Alternatively run Publish Jellyfin plugin to Gitea from GitHub Actions, choosing an existing version tag.

The workflow builds with .NET 10, packages the plugin DLL, creates the release on Gitea and generates/updates manifest.json in the distribution repository. Previous versions remain listed. The targetAbi is currently 12.0.0.0 to match the Jellyfin 12 dependencies in the project. Update this if the plugin's Jellyfin dependency changes.

Then add this repository URL in Jellyfin's Dashboard → Plugins → Repositories:

https://git.trufflemonkey.co.uk/sleeps/jellyfin-plugins/raw/branch/main/manifest.json

The download ZIP and this raw JSON URL must both work without signing in. Wait until the release workflow has successfully completed before adding the URL. The private Gitea source mirror URL is not a Jellyfin catalog URL.

Local packaging / verification

dotnet build jellyfin-plugin/Jellyfin.Plugin.SceneSearch/Jellyfin.Plugin.SceneSearch.csproj -c Release
python3 scripts/publish-jellyfin-plugin.py
unzip -l dist/SceneSearch-0.1.5.0.zip

To publish manually, set RELEASE_TAG, GITEA_URL, GITEA_REPO and GITEA_TOKEN, then invoke the script with --publish.

Important limitations

• The plugin requires the separate Scene Search API/service; installing the DLL from Jellyfin does not install Docker, Meilisearch, model files, etc.
• Jellyfin installation/update may require restarting the Jellyfin server.
• The release ZIP contains the plugin DLL, not the private source tree.
• Publishing a same-version tag twice may replace the manifest checksum while retaining a previously uploaded asset. Publish new changes under a new version/tag, rather than reusing an already published version.
• Gitea's public distribution repository must be protected against unauthorised changes; the token grants release and manifest write permissions.