clevis README

The project's README from github.com/nazarli-shabnam/clevis. As one markdown file: README.md.

Clevis

Analytics and security insight for GitHub repositories and organizations.


CI CodeQL License: GPL v3 Self-host


Clevis turns the GitHub API into a dashboard. Track repository activity, audit organization security posture, and run privileged maintenance jobs — from a single, dense, self-hosted control panel.


What it does

Area Description
Overview At-a-glance stats across your repositories and organization.
Activity Repository and org event streams pulled from the GitHub API.
Repositories Browse and inspect repositories with their key signals in one place.
Health & Security A computed security score backed by six automated checks — MFA enforcement, branch protection, secret scanning, Dependabot alerts, code scanning alerts, and default-branch force-push protection — each with a pass, fail, error, or not_applicable status and remediation guidance.
Collaborators See who has access across the surface you manage.
Automation Run privileged maintenance jobs (e.g. clearing GitHub Actions caches) with dry-run support and a full audit trail.

Every privileged action is recorded in an immutable audit log, and long-running work is dispatched to a background worker through a Postgres-backed job queue.


Architecture

Clevis is three independently deployable services around one shared check library:

Component Stack Responsibility
apps/api FastAPI · SQLAlchemy 2 · Alembic REST backend — auth, analytics, RBAC, and job enqueueing.
apps/worker Python · psycopg3 Polls the job queue (SELECT … FOR UPDATE SKIP LOCKED) and executes GitHub API tasks. Scales to multiple replicas safely.
apps/ui Next.js 15 · React 19 · TanStack Query The dashboard — dense, dark, keyboard-friendly.
packages/checks clevis-checks (Python) The security-check engine — six checks (MFA, branch protection, secret scanning, Dependabot alerts, code scanning alerts, default-branch force-push protection) — with built-in GitHub pagination.

Security model: Access is enforced per route with JWT auth dependencies (require_auth, require_workspace_admin) and org-scoped roles (require_org_role("member"|"admin")). GitHub credentials may be stored as Fernet-encrypted rows in saved_tokens (legacy PAT path); job payloads are also Fernet-encrypted at enqueue time and decrypted only when the worker processes them. Prefer a connected GitHub App installation so the API can mint short-lived installation tokens instead. Every request carries a propagated X-Request-ID for traceability.


Built with

Python FastAPI PostgreSQL SQLAlchemy
Next.js React TypeScript Tailwind CSS Docker


Quickstart

Prerequisites: Docker + Docker Compose.

git clone https://github.com/nazarli-shabnam/clevis
cd clevis
cp .env.example .env        # fill in every variable — none have defaults
docker compose up --build -d

Then open the UI at http://localhost:3000.

Full env var reference, GitHub App registration, and production hardening notes live in docs/self-hosting.md. Local dev without Docker is covered in AGENTS.md.


Get started

Once the instance is running, here's how to go from a fresh deploy to a connected GitHub org:

  1. Create the first account. The first visit lands on /setup, which creates the initial admin. After that, sign in with a password or the "Sign in with GitHub" button.
  2. Connect a GitHub org or account. Go to Settings → Connected GitHub accounts and click Install GitHub App — this sends you to GitHub to authorize Clevis for that org/account, which is what grants read access to its repos. GitHub redirects you back into the app once you approve it, and the org/account shows up under "Connected GitHub accounts" a few seconds later. (The App itself is a one-time setup step for whoever deployed the instance — see docs/self-hosting.md if that hasn't been done yet.) If you install into a brand-new org and the connection doesn't complete, sign out and back in with "Sign in with GitHub" once (this is what verifies your admin access on that org) and retry the install.

That's it — Overview, Activity, Repositories, Collaborators, Health & Security, and Cache all work off the connected org from step 2. A legacy personal access token (Settings → Personal access tokens (legacy)) is only ever needed as a manual fallback for an org that has no GitHub App installation — it is not a required step.

Pasting a PAT connects the org only if you're a GitHub admin of it. When a workspace admin saves a token whose read:org scope lets Clevis confirm they own/administer that org, Clevis connects it then and there (same Org + membership records the App-install and OAuth paths create). If the token lacks read:org, or GitHub reports you as a plain member rather than an admin, the token is still saved but only powers Overview's /me/analytics/overview endpoint — Repositories, Activity, Releases, Automation, and Collaborators need the step-2 App connection (or, for a non-admin, an accepted org invite) first, and those pages return a clear "isn't connected to Clevis yet" error until then.


Contributing

Contributions are welcome — see CONTRIBUTING.md for dev setup, CI checks, and commit conventions, and DESIGN.md for UI design language.

Found a security issue? Please follow the security policy rather than opening a public issue.

License

Released under the GNU General Public License v3.0.

clevis (nazarli-shabnam/clevis)

Searching Database…

169 ·GitHub
Что это?Clevis — это self-hosted дашборд, превращающий GitHub API в аналитику безопасности для ваших репозиториев и организаций — он считает оценку безопасности по шести автоматическим проверкам (принудительная MFA, защита веток, сканирование секретов, оповещения Dependabot, оповещения сканирования кода, защита дефолтной ветки от force-push) и позволяет администраторам запускать привилегированные задачи обслуживания вроде очистки кэшей GitHub Actions.
Это одно приложение или несколько сервисов?Он состоит из трёх независимо развёртываемых сервисов с общей библиотекой проверок: REST-бэкенд на FastAPI (аутентификация, аналитика, RBAC, постановка задач в очередь), Python-воркер, опрашивающий очередь задач на Postgres, и UI дашборда на Next.js/React.
Как это запустить?Запустите с помощью Docker + Docker Compose, затем откройте интерфейс: первый визит ведёт на /setup для создания первого администратора, после чего подключите организацию GitHub через Settings → Connected GitHub accounts → Install GitHub App.
Нужно GitHub App или можно просто токен?Установка GitHub App — предпочтительный путь, так как она позволяет Clevis выпускать краткоживущие токены установки; классический персональный токен доступа со scope read:org работает лишь как ручной резерв и открывает меньше функций.
Что будет, если подключиться только персональным токеном доступа?Классический PAT питает только эндпоинт аналитики страницы Overview — Repositories, Activity, Releases, Automation и Collaborators всё ещё требуют подключения GitHub App (или принятого приглашения в организацию для не-админов) и до того показывают ошибку «ещё не подключено к Clevis».
Как хранятся токены GitHub?Сохранённые учётные данные GitHub и полезные нагрузки задач шифруются Fernet в покое и расшифровываются воркером только когда он реально обрабатывает задачу.
Какие шесть проверок безопасности он выполняет?Принудительная MFA, защита веток, сканирование секретов, оповещения Dependabot, оповещения сканирования кода и защита дефолтной ветки от force-push — каждая отражается как пройдена, провалена, ошибка или неприменима, с рекомендациями по исправлению.
Ведёт ли он запись действий администраторов?Да, каждое привилегированное действие (например, запуск очистки кэша Actions) записывается в неизменяемый журнал аудита, а задачи очистки кэша поддерживают режим dry-run.
Можно ли масштабировать фонового воркера?Да — он забирает задачи из очереди по паттерну Postgres SELECT ... FOR UPDATE SKIP LOCKED, так что можно безопасно запускать несколько реплик воркера.
Где найти полные детали настройки и укрепления для продакшена?docs/self-hosting.md покрывает полный справочник переменных окружения, регистрацию GitHub App и заметки по укреплению для продакшена; AGENTS.md описывает локальный запуск без Docker.
Size
4.8 MB
Stars
169
Updated
CommitOct 07
Age
6mo
Commits · 90 Days