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
What is this?Clevis is a self-hosted dashboard that turns the GitHub API into security and analytics insight for your repositories and organizations — it computes a security score from six automated checks (MFA enforcement, branch protection, secret scanning, Dependabot alerts, code scanning alerts, default-branch force-push protection) and lets admins run privileged maintenance jobs like clearing GitHub Actions caches.
Is this one app or several services?It is made of three independently deployable services sharing one check library: a FastAPI REST backend (auth, analytics, RBAC, job enqueueing), a Python worker that polls a Postgres-backed job queue, and a Next.js/React dashboard UI.
How do I get it running?Run it with Docker + Docker Compose, then open the UI; the first visit lands on /setup to create the initial admin, after which you connect a GitHub org via Settings → Connected GitHub accounts → Install GitHub App.
Do I need a GitHub App or can I just use a token?A GitHub App installation is the preferred path since it lets Clevis mint short-lived installation tokens; a legacy personal access token with read:org scope works only as a manual fallback and unlocks fewer features.
What happens if I only connect with a personal access token?A legacy PAT only powers the Overview page's analytics endpoint — Repositories, Activity, Releases, Automation, and Collaborators still require the GitHub App connection (or an accepted org invite for non-admins) and show an 'isn't connected to Clevis yet' error until then.
How are GitHub tokens stored?Saved GitHub credentials and job payloads are Fernet-encrypted at rest and only decrypted by the worker when it actually processes a job.
What are the six security checks it runs?MFA enforcement, branch protection, secret scanning, Dependabot alerts, code scanning alerts, and default-branch force-push protection — each reported as pass, fail, error, or not-applicable with remediation guidance.
Does it keep a record of admin actions?Yes, every privileged action (like running an Actions cache cleanup) is recorded in an immutable audit log, and cache cleanup jobs support a dry-run mode.
Can the background worker be scaled?Yes — it claims jobs from the queue using a Postgres SELECT ... FOR UPDATE SKIP LOCKED pattern, so you can safely run multiple worker replicas.
Where do I find full setup and production hardening details?docs/self-hosting.md covers the full env var reference, GitHub App registration, and production hardening notes; AGENTS.md covers running it locally without Docker.
What are similar projects?searchmirror, bisibility, flowsint, NodePilot, casdoor, labtether, claude-relay-service, infisical
Which topics is it in?job-queue, security-audit, audit-log, jwt, rbac, fastapi, oauth, github, authentication, nextjs, encryption, postgresql
Creator
nazarli-shabnam
Size
4.8 MB
Stars
169
Updated
CommitOct 07
Age
6mo
Commits · 90 Days