Skip to content

Getting started

This tutorial walks you through installing Grimoire and monitoring your first repositories.

Before you begin

You need:

  • A GitHub personal access token with repo scope (read access to the repos you want to monitor)
  • Python 3.13+ with uv — or Docker if you prefer containers

Step 1 — Clone and configure

git clone https://github.com/lucabello/grimoire.git
cd grimoire
cp config.yaml.example config.yaml

Open config.yaml and set your token and the repositories you want to monitor:

github:
  token: "${GITHUB_TOKEN}"   # or a literal token

repositories:
  - repo: "your-org/your-repo"

Step 2 — Start Grimoire

The quickest way to run Grimoire locally — no container required:

just run

This installs dependencies (via uv) and starts the server on port 8000.

For a containerised deployment:

export GITHUB_TOKEN="ghp_your_token_here"
docker compose up -d

Step 3 — Open the dashboard

Navigate to http://localhost:8000.

Grimoire fetches data from the GitHub API immediately on startup. The dashboard populates as data arrives — each repository card shows a fetched_at timestamp so you know how fresh the data is.

Step 4 — Explore the interface

Page URL Description
Dashboard / Sortable overview of all repos' health
Backlog /backlog Prioritised list of problems across repos
Checks /checks Custom validation scripts and their results
Actions /actions Automated remediation tasks and run logs
API docs /docs Interactive Swagger UI

What's next