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 是一个自托管仪表盘,把 GitHub API 转化为面向你的仓库和组织的安全与分析洞察——它通过六项自动检查(强制 MFA、分支保护、密钥扫描、Dependabot 警报、代码扫描警报、默认分支强制推送保护)计算安全评分,并允许管理员运行清理 GitHub Actions 缓存等特权维护任务。
这是一个应用,还是多个服务?它由三个可独立部署的服务组成,共享同一个检查库:一个 FastAPI REST 后端(认证、分析、RBAC、任务入队)、一个轮询 Postgres 任务队列的 Python worker,以及一个 Next.js/React 仪表盘界面。
怎么把它跑起来?用 Docker + Docker Compose 运行,然后打开界面;首次访问会落在 /setup 创建初始管理员,之后通过 Settings → Connected GitHub accounts → Install GitHub App 连接 GitHub 组织。
我需要 GitHub App,还是只用 token 就行?首选 GitHub App 安装,因为 Clevis 能据此铸造短时效的安装令牌;带 read:org 权限的传统个人访问令牌只能作为手动备选,可解锁的功能也更少。
如果只用个人访问令牌连接会怎样?传统 PAT 只能支撑概览页的分析端点——仓库、活动、发布、自动化和协作者页面仍然需要 GitHub App 连接(非管理员则需要接受组织邀请),在此之前会显示「尚未连接到 Clevis」的错误。
GitHub 令牌是怎么存储的?保存的 GitHub 凭据和任务负载在静态存储时用 Fernet 加密,只有 worker 在实际处理任务时才会解密。
它运行的六项安全检查是什么?强制 MFA、分支保护、密钥扫描、Dependabot 警报、代码扫描警报,以及默认分支强制推送保护——每项都以通过、失败、错误或不适用上报,并附整改建议。
它会记录管理员操作吗?会,每一项特权操作(比如运行 Actions 缓存清理)都会记录在不可篡改的审计日志中,缓存清理任务还支持试运行模式。
后台 worker 能横向扩展吗?可以——它用 Postgres 的 SELECT ... FOR UPDATE SKIP LOCKED 模式从队列领取任务,因此可以安全地运行多个 worker 副本。
在哪里能找到完整的部署和生产加固细节?docs/self-hosting.md 涵盖完整的环境变量参考、GitHub App 注册和生产加固说明;AGENTS.md 介绍不用 Docker 在本地运行的方法。
Size
4.8 MB
Stars
169
Updated
CommitOct 07
Age
6mo
Commits · 90 Days