https://github.com/nazarli-shabnam/clevis
Open-source github security and maintenance tool
https://github.com/nazarli-shabnam/clevis
github github-maintenance github-management github-management-tool github-security
Last synced: about 13 hours ago
JSON representation
Open-source github security and maintenance tool
- Host: GitHub
- URL: https://github.com/nazarli-shabnam/clevis
- Owner: nazarli-shabnam
- License: gpl-3.0
- Created: 2026-03-24T11:29:48.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-08T14:04:30.000Z (20 days ago)
- Last Synced: 2026-06-08T15:24:23.852Z (20 days ago)
- Topics: github, github-maintenance, github-management, github-management-tool, github-security
- Language: TypeScript
- Homepage: https://clevis.org
- Size: 356 KB
- Stars: 100
- Watchers: 0
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Clevis
### Analytics and security insight for GitHub repositories and organizations.
[](https://github.com/nazarli-shabnam/clevis/actions/workflows/ci.yml)
[](https://github.com/nazarli-shabnam/clevis/actions/workflows/codeql.yml)
[](LICENSE)
[](#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 automated checks — **MFA enforcement**, **branch protection**, and **secret scanning** — each with pass/fail 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 (MFA, branch protection, secret scanning) with built-in GitHub pagination. |
**Security model:** RBAC is enforced per route (`viewer` / `analyst` / `admin`). GitHub tokens are **never stored persistently** — they are Fernet-encrypted when a job is enqueued and decrypted only at processing time. Every request carries a propagated `X-Request-ID` for traceability.
---
## Built with
---
## Self-host
**Prerequisites:** Docker + Docker Compose.
```bash
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`**.
> [!IMPORTANT]
> **CI secret required.** The Python test job needs a `JOB_SECRET_KEY` repository secret
> (*GitHub → Settings → Secrets and variables → Actions*). Generate one with `openssl rand -hex 32`.
Local development (without Docker)
```bash
# One-time setup
cp .env.example .env
pip install -r apps/api/requirements.txt
pip install -r requirements-test.txt
pip install -e packages/checks
cd apps/ui && npm install
```
Run each service in its own terminal:
```bash
docker compose up db # Postgres
cd apps/api && alembic upgrade head && uvicorn src.main:app --reload # API → :8080
cd apps/ui && npm run dev # UI → :3000
cd apps/worker && python src/worker.py # worker (optional)
```
Run the tests:
```bash
pytest -q # Python (hits a real Postgres; transaction-isolated)
cd apps/ui && npm run check # UI: typecheck + lint + build
```
See [`CLAUDE.md`](CLAUDE.md) for full architecture and configuration notes.
---
## CI / CD
CI runs on **every pull request** and on **pushes to any branch**, verifying:
- UI TypeScript typecheck + production build
- Python source compilation
- Docker image builds for `api`, `worker`, and `ui`
On version tags (`v*`), images are published to the GitHub Container Registry so others can self-host without building from source:
```
ghcr.io//clevis-api
ghcr.io//clevis-worker
ghcr.io//clevis-ui
```
[CodeQL](https://github.com/nazarli-shabnam/clevis/actions/workflows/codeql.yml) scans the codebase for security issues on a schedule.
---
## Contributing
Contributions are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) first — commits follow [Conventional Commits](https://www.conventionalcommits.org/) (enforced via commitlint), and the design language for any UI work is documented in [`DESIGN.md`](DESIGN.md).
Found a security issue? Please follow the [security policy](SECURITY.md) rather than opening a public issue.
## License
Released under the [GNU General Public License v3.0](LICENSE).