This repository contains a collection of configuration files for use with Kometa, designed to manage metadata, playlists, collections, and more for a Plex instance.
Important
I am not affiliated with Kometa, Node-Red, Radarr, Sonarr, or Plex in any way.
- Overview
- Repository Structure
- Getting Started
- Metadata Automation
- Manual Metadata Management
- Collections & Playlists
- Workflows & Automation
- Testing
- Contributing
- FAQ
- Links & Resources
- Detailed Instructions
This repository centralizes your Plex metadata, collections, and playlist configurations as code. It enables automated and manual updates, preserves customizations, and ensures easy recovery or migration for your media library using Kometa and other supporting tools.
kometa-configs/
├── .github/workflows/ # GitHub Actions for automation (import, linting, sorting, manual add, etc.)
├── functions/ # Bash scripts for reused logic (manipulating metadata, sorting, formatting, etc.)
├── node-red/ # Node-RED flows for processing webhooks from Servarr apps
├── scripts/ # Python scripts for one-time or advanced operations
├── tests/ # Bats test suite for shell functions.
├── movie-collections.yml # Collection definitions for movies
├── show-collections.yml # Collection definitions for TV shows
├── movie-metadata.yml # Centralized metadata for movies (auto-updated)
├── show-metadata.yml # Centralized metadata for TV shows (auto-updated)
└── playlists.yml # Playlist definitions and rules
- A running Plex Media Server
- Kometa
- Sonarr and/or Radarr
- Node-Red (to bridge webhooks & GitHub)
- A fork of this repository
- Fork this repository.
- Set up Node-Red with the provided flow.
- Configure Servarr webhooks to POST to your Node-Red instance.
- Point Kometa to your repo for metadata.
- (Optional) Run kometa-post-metadata-info.py to seed metadata from your media directories.
See Detailed Instructions for step-by-step instructions.
Metadata is kept up-to-date automatically when new files are imported via Servarr (Radarr/Sonarr). The workflow is:
- Radarr/Sonarr imports new media and triggers a webhook.
- Node-Red processes the webhook and triggers a GitHub Action.
- The Action updates
movie-metadata.ymlorshow-metadata.yml. - Kometa pulls the latest metadata on its next sync.
You can manually add metadata using workflow_dispatch workflows or by editing YAML files directly. Functions are provided for sorting and formatting to ensure consistency.
- Manual Add Workflow: Use the "Manually add Media" GitHub Action to insert a new movie/show.
Define and customize your collections and playlists in YAML:
- Collections:
movie-collections.yml,show-collections.yml - Playlists:
playlists.yml
This repo leverages GitHub Actions for:
- Automated metadata updates on webhook/import
- Linting and formatting YAML
- Finding missing posters/genres
- Manual add & sync operations
- Monthly tagging for backup/snapshots
Shell scripts are tested with Bats. See tests/README.md for structure and how to run tests.
Q: What happens if I lose my Plex server?
A: Just restore your repo and point Kometa to it — your metadata, collections, and playlists are preserved!
Q: Can I add custom fields?
A: Yes, but keep YAML structure consistent and update sorting/formatting scripts as needed.
Q: How do I get alerts for YAML errors?
A: Configure the Discord webhook and use the provided linting workflow.
The general workflow looks like the following diagram.
- Fork this Repository.
- Generate a GitHub Fine-Grained Personal Access Token with Read and Write access to contents on your fork, save it for later.
- Create a workflow in your node-red instance by importing "metadata-update-flow.json"
- Add your GitHub token created in step 2 here.
- Replace chase-roohms with your GitHub username or organization here
- In your starr apps create a webhook (Settings -> Connect -> Add Connection -> Webhook) to run only "On File Import", it should POST to the endpoint
http://<NODE_RED_IP>:<NODE_RED_PORT>/arr-import - Point your kometa config to pull metadata from your fork (check the docs), and optionally you can keep your collections and playlist configuration here as well.
- OPTIONAL: To do a one time update of the files based on your movie and show directory folder names you can use kometa-post-metadata-info.py, but make sure you replace the values at the top of the script, and your folders / media should all be named according to the trash guides naming schemes for movies and shows
- OPTIONAL: lint-and-alert.yml runs on every push, and will alert you via Discord if you introduce erroneous yaml files. If you want this functionality create a repository secret with the name "DISCORD_WEBHOOK_URL", otherwise, edit lint-and-alert.yml and remove the alert step and the DISCORD_WEBHOOK_URL environment variable.
Example Discord alert