GrimoireLab: a CHAOSS analytics stack for repository data

A toolkit, not a product you install and use

GrimoireLab is described as a CHAOSS toolset for software development analytics, and the description in the README is a pipeline: it includes a coordinated set of tools to retrieve data from systems used to support software development, store it in databases, enrich it by computing relevant metrics, and make it easy to run analytics and visualizations on it.

Four verbs, four subsystems. That framing matters because GrimoireLab is not a single program with a user interface. The repository you are looking at is the orchestrating entry point, with a console script named grimoirelab, and the real work lives in a dozen sibling repositories under the chaoss organisation. The primary language listed for this repository is Shell, which reflects that the top level is largely about launching containers and orchestrating the other pieces.

The metrics themselves are not invented here. The README states that metrics available in GrimoireLab are, in part, developed in the CHAOSS project, and points at the CHAOSS metrics documentation for the latest release. That is the differentiator for anyone who has to defend a number in a review: the definitions are public and community maintained rather than buried in a vendor's dashboard.

The audience is engineering effectiveness teams, open source maintainers and researchers who need to analyse repositories at scale. The GitHub Projects image in the README points at a Bitergia-hosted dashboard, which shows the intended end state: metrics over a population of repositories, not over one codebase.

The licence is GPL-3.0+, and the package metadata classifies the project as Development Status :: 5 - Production/Stable. That combination, a mature status with a copyleft licence, is the profile of infrastructure that organisations deploy on a server rather than vendor into a product.

Thirteen component repositories in four layers

The component map in the README is the most useful part of the document, because it tells you the architecture and also tells you how to take a subset.

Data retrieval components come first. Perceval handles retrieval of data from data sources, and it has four bundles for specific communities: OPNFV, Mozilla, Puppet and Weblate. Graal performs source data analysis with external tools, and KingArthur is for batch processing of massive retrieval, which is the component you would reach for when a single pass over one repository is not enough.

Data enrichment components sit in the middle. GrimoireElk handles storage and enrichment of data, Cereslib is the generic data processor, and SortingHat does identity management, which in this ecosystem means resolving who the contributors are across many repositories and aliases.

Data consumption components turn the stored data into things people read. Sigils provides visualizations and dashboards, Kidash manages those visualizations and dashboards, and Manuscripts produces reporting.

Finally, platform management and orchestration: Mordred is the orchestration component that runs the pipeline, and the GrimoireLab Toolkit holds common utilities.

Read as a pipeline, that is retrieve, enrich, consume, orchestrate. Read as a dependency list, it is a lot of moving parts, and the pyproject.toml shows it: the package depends on grimoirelab-toolkit, four perceval bundles, sortinghat, kidash, grimoirelab-panels, grimoire-elk, sirmordred, cereslib, graal and perceval, all with allow-prereleases enabled and lower bounds rather than exact pins. The requirements.txt pins the exact versions for a release, which is the file to use when you want reproducibility.

The docker-compose path and what it costs in resources

The getting started section is built around a default setup, which is a configuration for analysing the git activity of this repository. It exists so that a newcomer can see data appear before they understand the configuration format.

The software requirements are git, a docker client and docker compose, and the README shows a working configuration as a series of version outputs from a machine where git reported version 2.17.1, docker version 19.03.1 and docker-compose version 1.22.0. The hardware requirement is 2 CPU cores, 8GB of memory, and enough virtual memory for Elasticsearch, with a link to the Elasticsearch documentation on the maximum map count. That last clause is not optional: Elasticsearch will refuse to start on a host with an insufficient map count, and it is the most common failure for a first-time deployer.

The steps are two commands after the clone:

git clone https://github.com/chaoss/grimoirelab

cd grimoirelab/docker-compose
docker-compose up -d

Then you wait. The README says the data will be ready after a while, that the waiting time depends on the amount of data to fetch from a repo, and that for small repositories you can expect data to be available after 10 to 15 minutes.

Three endpoints appear when it is up. OpenSearch Dashboards is at http://localhost:8000 and the API directly at http://localhost:9200. Identity management lives in SortingHat at http://localhost:8000/identities/.

One more step is easy to miss. OpenSearch Dashboards starts with no visualisation at all, and you import the default dashboards yourself from the grimoirelab-sigils repository by opening Stack Management and then Saved Objects and importing the files you want.

docker run mounts two configuration files

The second supported route runs the grimoirelab image directly, and it is the route to understand if you want to see exactly what configuration the pipeline consumes.

The requirements change accordingly. Instead of docker compose, you need git and a docker client, and you must already have ElasticSearch and Kibana up and running, plus SortingHat up and running. The image then reads two files from the default settings directory through volume mounts, projects.json and setup-docker.cfg, mounted into the container at /home/grimoire/conf.

cd grimoirelab
docker run --net=host \
    -v $(pwd)/default-grimoirelab-settings/projects.json:/home/grimoire/conf/projects.json \
    -v $(pwd)/default-grimoirelab-settings/setup-docker.cfg:/home/grimoire/conf/setup.cfg \
    -t grimoirelab/grimoirelab

The two mounted files are the whole configuration surface for a first run: projects.json describes which repositories to analyse, and setup-docker.cfg carries the pipeline settings. Once you understand those two files, you are no longer limited to analysing this repository.

A naming inconsistency in the README is worth noting as a practical detail rather than a criticism. The compose section refers to OpenSearch Dashboards, while the docker run section still asks you to have ElasticSearch and Kibana running. The two names describe the same lineage of search and dashboard stack at different points, and the deployment you assemble has to be internally consistent: an OpenSearch Dashboards instance cannot read an Elasticsearch cluster that is a different major version, so pair them deliberately rather than assuming either name covers what the other does.

The network mode is host, which means the containers reach the services on the host directly, and the dashboard is again expected at http://localhost:8000 once the data has been fetched.

Identities, permission groups and the FreeBSD deployment

SortingHat deserves its own attention, because it is the component that decides whose contribution is whose. Identity management in this ecosystem means resolving contributors across repositories and their aliases, and the SortingHat UI at the identities path is where that resolution is inspected and corrected. Get it wrong and every downstream metric about people is wrong.

There is a documented breaking change here. Starting from GrimoireLab 1.3.0, creating new users in SortingHat requires assigning them to a permission group, and by default they have read-only permissions. The README links the instructions for assigning users to permission groups.

That single line is a good indicator of what this project is. It is deployed as shared infrastructure where several people query the same store, and the default for a new account is to look, not to change.

The FreeBSD section shows a real deployment. The README says FreeBSD has adopted GrimoireLab for their Bugzilla Analysis and deployed Grimoirelab in their cluster, with a public instance, and that the FreeBSD Foundation shared the process of running Grimoire on FreeBSD, available in the FreeBSD.md file in the repository. That guide also serves people who want to run Grimoirelab from source rather than deploying it with Docker, which is a genuinely useful second use of the document.

The repository also carries a kubernetes/ directory, a ROADMAP.md, a GOVERNANCE.md, MAINTAINERS.md and an ADOPTERS.md, so there is a record of who is involved and who has adopted it.

Version discipline, licensing, and taking only what you need

The release process here is disciplined in a way that is easy to miss. Recent tags include 1.22.0-rc.2 on 2026-09-16, 1.22.1-rc.1 on 2026-09-21 and 1.22.1 on 2026-09-22. Release candidates are cut first, then the final tag follows within days, and the version in pyproject.toml matches the final tag at 1.22.1. The repository also has a releases/ directory and a NEWS file.

Python 3.10 is the floor, and the build system is poetry-core. The dependency declarations use lower bounds with allow-prereleases set to true, which is the opposite of a strict pin, so an unpinned install can pull prerelease components. If you need reproducibility, requirements.txt is the file to install from, since it pins every component to an exact version: grimoirelab 1.22.1, grimoirelab-toolkit 1.2.9, perceval 1.6.1, the four bundles, grimoire-elk 1.8.3, sortinghat 1.15.2, kidash 1.1.11, grimoirelab-panels 1.2.0, sirmordred 1.2.13, cereslib 1.1.11 and graal 1.2.12.

The licence is GPL-3.0+, so running it as a service is fine for most organisations, while embedding its code inside a closed-source product carries obligations that the licence file rather than this README defines.

The alternative to the full stack is the stack's own component list. Perceval on its own fetches repository data and writes it out, without Elasticsearch, without SortingHat and without the dashboards. GrimoireElk on its own stores and enriches data you already have. Mordred on its own orchestrates a pipeline you have configured. The difference in approach is scope and cost: the full GrimoireLab deployment gives you a working multi-repository analytics environment with identity resolution and dashboards, while a single component gives you one stage of it and leaves the rest to you.

For a team that needs to answer one question about one repository, the single component is the sane choice. For a team that measures developer activity as a programme, the stack is what you want, and the FreeBSD deployment is evidence that somebody has run it that way.

Editorial conclusion

GrimoireLab fits a team that already measures developer activity and needs a defensible metric pipeline over real repositories, with the CHAOSS metric definitions behind the numbers. It is the wrong choice for a one-off question about a single repository, because the stack brings Elasticsearch, SortingHat and thirteen component packages with it, and it is the wrong choice for an organisation that cannot operate a container stack with 8GB of memory and dedicated virtual memory for Elasticsearch. Before deploying, read the component map in the README and decide whether you want the full stack or just Perceval and GrimoireElk, check the version floor in requirements.txt against the release you plan to install, and note that the package is GPL-3.0+ with the latest release 1.22.1 from 2026-09-22.

Frequently asked questions

Official sources

1. chaoss/grimoirelab on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases