Red-Index clones every listed repo every fifteen minutes

A fifteen minute job that clones and compiles

The mechanism is a scheduled GitHub Actions workflow, and it does four things on a cycle. Every fifteen minutes, or when someone triggers it by hand, the workflow parses the list of repositories, clones each one, and compiles a JSON file in the index directory holding the current metadata for every repository and cog it found. The list of repositories is itself a file in the repository, repositories.yaml, and there is a separate repositories-example.yaml that exists so a new repository entry can be copied from a working example rather than written from scratch. The Python side of the job is small: an indexer script and a parser script at the root, plus a metadata.json. Nothing about this needs a long lived server, which is why the only moving part is a cron schedule inside Actions.

Two filenames carry a version contract

Consumers are given one instruction and one warning. The instruction is to fetch the minified version of the index, index/1-min.json, or its gzip equivalent index/1-min.json.gz, from whatever website or service you are building, and parse it. The warning is the part that matters for anyone depending on it: in case of substantial changes to the data format, the maintainers will increase the version number and the link will change. That is an unusually clean contract for a free data source, because it means a consumer can pin to version 1 and be explicit when it upgrades, rather than silently parsing a shape that has moved underneath it. The practical advice follows from the warning: treat the version segment of the filename as part of your integration, and do not assume the path stays the same across years.

Approved and unapproved are two different doors

Adding a repository is not one path, it is two, and the difference is a category. The intended route is to create a Cog Creator application, which is a form on the Cog Creators board, and being accepted as a Cog Creator gets the repository added to the approved category, along with what the README calls a few other perks. The fallback route exists for anyone still waiting on that application or not ready to apply: open a pull request and the repository may be added to the unapproved category. So the index has a quality signal built into its structure rather than left to the consumer to judge, and a service that wants to show only vetted entries can filter on it. It also means the two categories will never be equally current, since an approved entry arrives through a review and an unapproved one through a merge.

The Makefile is incremental and warns you not to break it

The build is a Makefile whose first comment is a request rather than a description: it supports incremental builds, and please do not break that if you make changes. The dependency chain explains why. The default target runs clone and then index. Cloning depends on a clean cache and on the cache step, the cache step depends on a generated clonerepos.sh, and that script is produced by the parser script from the repositories list. Only when the cache exists does the indexer run:

.venv/bin/python indexer.py repositories.yaml

A separate clean target removes the generated script and the virtual environment, and a cleancache target removes only the cache directory. The virtual environment target creates it with the standard module and installs the one dependency directly:

python3 -m venv .venv
.venv/bin/pip install pyyaml

So the cache is invalidated by configuration rather than by timestamps alone, which is the behaviour the comment asks you to preserve.

One runtime dependency and about twenty rule families

The packaging is minimal and the linting is not. The project metadata names the package Red-Index at version 1.0.0, requires Python 3.14 or newer, and declares exactly one dependency, pyyaml, which is all the indexer needs to read the repository list. The Ruff configuration is the interesting part of the file. Line length is 99, formatting uses line feed endings, and the selected rule families include pyflakes, pycodestyle, import sorting, pyupgrade, bugbear, bandit, builtin shadowing, unused arguments, refurb with an explicitly enabled preview rule, type annotations, simplify, logging, logging format, comprehensions, boolean trap, implicit string concatenation, perflint, pygrep hooks, flake8-pie, Ruff's own rules, leftover breakpoints and tidy imports. Six rules are switched off with a reason each, and preview mode with explicit preview rules is turned on.

uv is locked, but the Makefile makes its own venv

The root of the repository contains a uv.lock file alongside the Makefile's own bootstrapping, and the two approaches coexist rather than one replacing the other. The Makefile creates a virtual environment with the standard library module and installs pyyaml with pip, taking no lockfile into account, which keeps the workflow readable for someone who only wants to run the indexer once. The lockfile serves the other path, the managed one used by contributors who already work with uv, and the presence of a pre-commit configuration at the root suggests that lint runs before commit rather than only in review. A pinned .python-version file sits next to them, matching the requirement declared in the packaging metadata. If you fork this to run your own index, the Makefile path is the shortest; if you intend to contribute, matching the locked environment avoids discovering a rule difference as a failing check.

Two consumers are named, and one of them is a cog

The projects section lists what is currently known to read the index, and the two entries sit at different layers. The first is a web interface hosted at index.discord.red, which is the browsable front end for the whole index. The second is a cog from another repository, written to search the index and install repositories and cogs directly from a running Red instance, which means the index is consumed from inside the bot itself rather than from a browser. Anyone who has built a service on top of the index is invited to open a pull request so it can be added to that list, so the section doubles as a registry of clients. For a reader deciding whether to depend on the data, the two examples are the useful evidence: one service treats it as read-only catalogue data, and one treats it as a package source it can install from.

Editorial conclusion

Red-Index suits anyone building a browsable catalogue of Red repositories, since the job does the cloning and metadata collection that a service would otherwise have to do itself, and the versioned filename gives you something stable to pin. It does not suit a service that needs to know a repository exists the minute it is created, since the cycle is fifteen minutes, and it does not suit anyone expecting a list of approved repositories, because inclusion is either a review process or a pull request. Before you build on it, note that a substantial change to the data format bumps the version and moves the link, so read the version from the file you fetch rather than hardcoding a path, and remember that metadata reflects the moment of the clone.

Frequently asked questions

Official sources

1. Official README
2. Project repository