torrust

Guide for releasing a new version of the deployer using the standard branch/tag workflow. Covers version bump, signed release commit, pushing main, creating signed tag, creating release branch, and verifying Docker + crate publication workflows. Use when asked to "release", "cut a version", "publish a new version", or "create release vX.Y.Z".

Run a complete local end-to-end test using the LXD provider to verify a feature, fix, or change works as expected from the user's perspective. Covers creating an environment config, provisioning a VM, deploying the tracker, verifying it works, and cleaning up. Use when manually testing changes, validating a new feature locally, running a full deployment smoke test, or checking that the deployer works end-to-end. Triggers on "local e2e", "manual e2e test", "test my changes locally", "run deployer end-to-end", "smoke test", "test on LXD", "verify feature works", or "full deployment test".

Check whether the system has all dependencies required by the deployer (OpenTofu, Ansible, LXD, cargo-machete). Use before running provisioning, E2E tests, or any infrastructure command. Triggers on "check dependencies", "check system dependencies", "are dependencies installed", "verify dependencies", "dependency check", or "missing tools".

Install the system dependencies required by the deployer (OpenTofu, Ansible, LXD, cargo-machete) using the built-in dependency-installer. This is the setup/installer step before using the deployer for the first time. Triggers on "install dependencies", "install system dependencies", "setup deployer", "first time setup", "missing dependency", "install opentofu", "install ansible", "install lxd", or "deployer setup".

Open a pull request from a feature branch using GitHub CLI (preferred) or GitHub MCP tools. Covers pre-flight checks, correct base/head configuration for fork workflows, title/body conventions, and post-creation validation. Use when asked to "open PR", "create pull request", or "submit branch for review".

Guide for updating project dependencies using the update-dependencies.sh automation script. Automates the cargo update workflow including branch creation, commit, push, and optional PR creation. Use when updating dependencies, running cargo update, or automating the dependency lifecycle. Triggers on "update dependencies", "cargo update", "update deps", "bump dependencies", or "run dependency update".

Guide for committing changes in the torrust-tracker-deployer project. Covers conventional commit format, pre-commit verification checks, issue number conventions, and commit quality guidelines. Use when committing code, running pre-commit checks, or following project commit standards. Triggers on "commit", "commit changes", "how to commit", "pre-commit", "commit message", "commit format", or "conventional commits".

Guide for debugging and troubleshooting local LXD VM instances created by the deployer. Covers SSH connectivity failures (too many authentication failures, key issues, connection refused), bypassing SSH with lxc exec, cloud-init problems, networking issues, and general LXD instance inspection. Use when a developer cannot access a deployed LXD VM, encounters SSH errors, or needs to inspect VM state without SSH. Triggers on "lxd troubleshoot", "ssh failed lxd", "can't ssh into vm", "lxd debug", "too many authentication failures", "lxc exec", "vm not reachable", "lxd instance problem", "debug lxd instance", or "lxd networking issue".

End-to-end workflow for processing and resolving all Copilot code review suggestions on a pull request in torrust-tracker. Use when asked to handle PR review feedback, process all copilot suggestions, audit and resolve review comments, or manage copilot-generated review threads. Triggers on "process copilot suggestions", "handle all PR feedback", "resolve copilot review", "audit PR suggestions", or "close all copilot comments".

Guide for running a manual Docker security scan for the tracker runtime image and documenting results. Covers build, Trivy scan, CVE triage, per-CVE catalog updates, and scan history updates. Use when asked to run a manual container scan, triage Docker CVEs, or refresh security scan docs.

Use the Torrust Tracker REST API. Covers authentication, all endpoints (stats, metrics, torrents, auth keys, whitelist), and making announce/scrape requests to verify API behaviour. Triggers on "use API", "test API", "call REST API", "query API", "API endpoint", "curl tracker", "tracker client", "announce request", or "verify API".

Run code quality checks and linters for the torrust-tracker project. Includes Rust clippy, rustfmt, markdown, YAML, TOML, spell checking, and shellcheck. Use when asked to lint code, check formatting, fix code quality issues, or prepare for commit. Triggers on "lint", "run linters", "check code quality", "fix formatting", "run clippy", "run rustfmt", or "pre-commit checks".

Guide for fixing Rust Clippy warnings in the torrust-tracker project. Covers proper application of clippy suggestions, when to add allowances, and how to document exceptions. Use when asked to fix clippy warnings, improve code quality, or resolve linter issues. Triggers on "fix clippy", "clippy warnings", "rust code quality", or "linting issues".

Guide for committing changes in the torrust-tracker project. Covers conventional commit format, pre-commit verification checklist, GPG signing, and commit quality guidelines. Use when committing code, running pre-commit checks, or following project commit standards. Triggers on "commit", "commit changes", "how to commit", "pre-commit", "commit message", "commit format", or "conventional commits".

Guide for archiving closed issue specification files from docs/issues/open/ to docs/issues/closed/. Covers verifying closure on GitHub, moving files, updating frontmatter, creating a branch, and opening a PR. Permanent deletion of closed specs is not automated — the user must explicitly request it. Use when cleaning up closed issue specs, archiving issue docs, or maintaining the docs/issues/ folder. Triggers on "cleanup issue", "archive issue", "move closed issue", "clean completed issues", or "maintain issue docs".

Run all mandatory pre-commit verification steps for the torrust-tracker project. Covers the pre-commit script (automated checks), manual review steps, and individual linter commands for debugging. Use before any commit or PR to ensure all quality gates pass. Triggers on "pre-commit checks", "run all checks", "verify before commit", or "check everything".

Workflow for checking whether UDP packet loss or uptime degradation may be caused by conntrack saturation on the torrust-tracker-demo server. Use when diagnosing UDP timeouts, low newTrackon uptime, packet drops, conntrack pressure, UDP receive-buffer errors, or when validating whether conntrack tuning is still healthy.

Step-by-step process for creating and opening a GitHub issue in the torrust-tracker-demo repository. Use when asked to open, create, or file an issue. Covers writing the draft file, human review, opening on GitHub, renaming the file, and committing. Triggers on "open issue", "create issue", "new issue", "file issue", "draft issue".

Step-by-step workflow for resizing (scaling up) the Hetzner server in the torrust-tracker-demo stack. Use when asked to resize, scale up, or upgrade the server plan. Covers pre-resize preparation, graceful shutdown, provider panel action, post-resize recovery, and evidence capture. Triggers on "resize server", "scale up", "upgrade server plan", "Hetzner resize", "change server type".

Workflow for investigating server and service performance bottlenecks in the torrust-tracker-demo repository. Use when debugging uptime degradation, high load, latency spikes, dropped packets, or suspected capacity limits. Triggers on "performance issue", "high load", "uptime drop", "bottleneck", "capacity", "scaling", "degraded service", "newTrackon uptime".

Create and open a pull request in the torrust-tracker-demo repository. Use when asked to open a PR, create a pull request, submit a PR, or push changes and create a PR. Triggers on "open PR", "create PR", "submit PR", "push and open PR", "open pull request".

Guide for committing changes in the torrust-tracker-demo repository. Covers running all linters locally before committing to ensure CI passes. Triggers on "commit", "how to commit", "before committing", "pre-commit checks", "run linters", "check before commit".

Create a git branch to start working on a GitHub issue in the torrust-tracker-demo repository. Use when asked to start working on an issue, create a branch for an issue, or check out a new branch. Triggers on "create branch", "new branch", "start working on issue", "branch for issue", "checkout branch".

Run linters for the torrust-tracker-demo repository. Covers running the canonical lint script, installing the lint wrapper and prerequisites, and troubleshooting markdown, YAML, spelling, shellcheck, npm permission, and Node/cspell compatibility issues. Triggers on "run linters", "lint", "check lint", "run lint", "linting", "spell check", "check markdown", "check yaml", "lint script", "install linter", "lint troubleshooting".

Updates the contributors list on the Torrust website homepage. Use when asked to refresh, update, or sync the contributors list from the Torrust GitHub org.

Creates a new blog post for the Torrust website. Use when asked to write, add, create, or publish a new blog post or article.

Opens a GitHub Pull Request from the current branch, linking it to the related issue when the branch name starts with an issue number.

Creates a new git branch for a GitHub issue following naming conventions with issue number as prefix.

Creates a new Svelte UI component for the Torrust website. Use when asked to add, create, or build a new reusable UI component, widget, or UI element.

Deploys the Torrust website to GitHub Pages. Use when asked to deploy, publish, or release the site, or to set up the deployment workflow.

Runs the full quality check suite for the Torrust website. Use before committing or opening a PR to verify types, linting, and that the build succeeds.