How this repository is run. PlexCleaner is a code repository, so its operations are the verification a change owes before it merges, the publish that ships a release, and the media-dependent testing that no runner can perform. The publish contract itself is WORKFLOW.md, and this file is the runbook side of it.
What verifying a change here requires, including the part CI cannot perform.
The clean-compile is the .NET Format VS Code task, chaining CSharpier Format -> .NET Build -> dotnet format style --verify-no-changes --severity=info, and it must pass before a commit, per CODESTYLE.md. CI runs the same checks plus the rest of its lint gate (unit tests with coverage, markdownlint, cspell, actionlint, editorconfig-checker, and ruff plus mypy over RegressionTests/), and Lint: All (CI parity) in .vscode/tasks.json runs that whole gate locally. A green clean-compile does not predict a green CI, so run the parity task before pushing a change that touches anything beyond .cs files.
The part CI structurally cannot exercise is media processing. The unit tests need no media files and run everywhere, but the behavior of the tool depends on the media it processes and on the external tools (FFmpeg, HandBrake, MkvToolNix, MediaInfo, 7-Zip) it drives, and a pull request runner has neither a media collection nor a reason to trust one. So a change to processing, sidecar, media-tool, or language-tag code is verified locally against real media, by the Docker test script and by the regression harness described under Runbooks, before it is called done. Read ARCHITECTURE.md before changing that code.
Merges never publish. The publisher (publish-release.yml) runs on a weekly schedule and on manual dispatch, and each run builds the one branch it is started from: the schedule rebuilds main only (a stable release, the latest image, and a refreshed ubuntu:rolling base), and a dispatch publishes its own branch (main -> stable / latest, develop -> prerelease / develop). To ship the changes accumulated on develop, dispatch the workflow from develop. A dispatch from any other branch fails at the plan job rather than passing as a no-op. A re-run whose version is unchanged creates no duplicate release, and the Docker push still refreshes the image. Absent publish rights, nothing here can be run, and the verification falls back to the static and trace audits in WORKFLOW.md section 5.
Docker/Test.sh validates basic container functionality against sample media, downloading the Matroska test files when no external media path is given. It is included in the image, so a published tag is tested from inside the container:
docker run -it --rm --name PlexCleaner-Test docker.io/ptr727/plexcleaner:latest /Test/Test.shThe regression harness under RegressionTests/ processes a curated collection of troublesome media through a given image tag on a ZFS clone and compares the results across versions down to the per-file processing decision. The collection and its media-specific reduction rules live with the media on a server and are never committed, so this runs on the host that holds them. RegressionTests/README.md is the procedure.
The repository is the record, and GitHub holds it. Nothing here keeps state outside git, and a published release or image is re-creatable from its tag by dispatching the publisher on that commit's branch. The regression media collection is the one asset the repository does not hold, and it is backed up with the media it sits beside rather than by anything here.
Workflow runs are the log for CI and publishing. gh run list --branch [branch] and gh run view [id] --log-failed reach them, and a local gate reproduces a CI lint failure exactly, so reproduce locally before reading workflow logs.
Application logging is Serilog, to the console and, with --logfile, to a file, and --loglevel sets the minimum level (Debug logs every media-tool invocation with its arguments, so a processing decision is traceable to the tool call that drove it). The sidecar file beside each media file (filename.PlexCleaner) caches the media attributes and the processing state, so re-processing a file reads it rather than the media, and a stale or suspect result is re-derived by deleting the sidecar. The regression harness keeps per-version results and logs for diffing.
The application orchestrates FFmpeg, HandBrake, MkvToolNix, MediaInfo, and 7-Zip through CLI wrappers, and the Docker image bundles tested versions of all of them, so the image is the reference environment for reproducing a media-processing result. On Windows checkfornewtools downloads newer tool versions and gettoolinfo prints the installed ones, and the README covers each platform.
The doc linters run through the hub-hosted wrapper, whose invocations and rationale are the hub's GOVERNANCE.md "Running the Linters Locally", not restated here.
The .NET Tool Update and .NET Outdated Upgrade tasks refresh the local .NET tools and prompt through dependency updates, and dotnet husky install reinstalls the commit hook after a fresh clone.
- PlexCleaner.defaults.json and PlexCleaner.schema.json: the default settings file and its JSON schema, regenerated by the
defaultsettingsandcreateschemacommands. - Samples/: the versioned sample settings files and sidecar fixtures the tests read.
- The branch rulesets, repository settings, and required secret names are hub-hosted rather than carried here, and AUDIT.md states how the self-audit reaches them.
- host-tools.json: the tools a host needs beyond the fleet's own declaration.
- .github/workflows/: the CI and publish entry points plus the carried
validate-task.yml, under the WORKFLOW.md contract. The build, publish, plan, merge-bot and Docker-Hub-overview tasks are hub-hosted and reached by a SHA pin. - global.json: the Microsoft.Testing.Platform opt-in
dotnet testneeds on the .NET 10 SDK.