A unified dashboard for managing Gitea and GitLab instances — browse projects, manage secrets, monitor CI/CD pipelines, stream build logs, and receive webhook notifications, all from a single app.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

🚀 Features

Multi-Provider — Connect to Gitea and GitLab simultaneously via a unified provider abstraction
Secrets Management — View, create, update, and delete CI/CD secrets across projects and groups
Pipeline Monitoring — Browse pipelines, view jobs, retry failed builds, cancel running ones
Build Log Streaming — Fetch and display raw job logs with monospace rendering
Webhook Integration — Receive push/PR/pipeline events via POST /webhook/:connectionId and broadcast to all connected clients in real-time via WebSocket
Secrets Cache & Scanning — Background scan service fetches and caches all secrets every 24h with upsert-based deduplication
Secure Token Storage — Connection tokens stored in OS keychain via @push.rocks/smartsecret (encrypted file fallback), never in plaintext on disk
Auto-Refresh — Frontend polls for updates every 30s, with manual refresh available on every view
Embedded SPA — Frontend is bundled (base64-encoded) and served from memory, no static file server needed

📦 Install

Prerequisites

Deno v2+
pnpm (for frontend deps and bundling)
MongoDB-compatible database (auto-provisioned via @push.rocks/smartmongo / LocalTsmDb)

Setup

# Clone the repository
git clone https://code.foss.global/serve.zone/gitops.git
cd gitops

# Install frontend dependencies
pnpm install

# Build the frontend bundle
pnpm build

# Start the server
deno run --allow-all mod.ts server

The app will be available at http://localhost:3000.

⚙️ Configuration

All configuration is done through environment variables:

Variable	Default	Description
`GITOPS_PORT`	`3000`	HTTP/WebSocket server port
`GITOPS_ADMIN_USERNAME`	`admin`	Admin login username
`GITOPS_ADMIN_PASSWORD`	`admin`	Admin login password

Data is stored at ~/.serve.zone/gitops/:

~/.serve.zone/gitops/
├── storage/          # Connection configs (JSON, tokens replaced with keychain refs)
│   └── connections/  # One file per connection
└── tsmdb/            # Embedded MongoDB data (cached secrets, projects)

🏗️ Architecture

┌──────────────────────────────────────────────────────┐
│                    GitOps App                         │
├──────────┬───────────────┬───────────────────────────┤
│ OpsServer│ ConnectionMgr │ SecretsScanService        │
│ (HTTP/WS)│ (Providers)   │ (24h background scan)     │
├──────────┤               ├───────────────────────────┤
│ Handlers │  GiteaProvider│ CacheDb                   │
│ (9 total)│  GitLabProvider│ (LocalTsmDb + SmartdataDb)│
├──────────┴───────────────┴───────────────────────────┤
│                  StorageManager                       │
│            (filesystem key-value store)               │
├──────────────────────────────────────────────────────┤
│                   SmartSecret                         │
│             (OS keychain / encrypted file)            │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│                   Frontend SPA                        │
│        Lit + dees-catalog + smartstate                │
├──────────────────────────────────────────────────────┤
│  Dashboard │ 8 Views │ WebSocket Client │ Auto-Refresh│
└──────────────────────────────────────────────────────┘

Backend (`ts/`)

GitopsApp — Main orchestrator. Owns all subsystems, handles startup/shutdown lifecycle.
ConnectionManager — CRUD for provider connections. Tokens secured in OS keychain. Background health checks on startup.
BaseProvider → GiteaProvider / GitLabProvider — Unified interface over both APIs (projects, groups, secrets, pipelines, jobs, logs).
OpsServer — TypedServer-based HTTP/WebSocket server with 9 handler modules:
- AdminHandler — JWT-based auth (login/logout/verify)
- ConnectionsHandler — Connection CRUD + test
- ProjectsHandler / GroupsHandler — Browse repos and orgs
- SecretsHandler — Cache-first secret CRUD
- PipelinesHandler — Pipeline list/jobs/retry/cancel
- LogsHandler — Job log fetch
- WebhookHandler — Custom HTTP route for incoming webhooks
- ActionsHandler — Force scan / scan status
SecretsScanService — Background scanner with upsert-based deduplication. Runs on startup and every 24h.
CacheDb — Embedded MongoDB via LocalTsmDb + SmartdataDb. TTL-based expiration with periodic cleanup.
StorageManager — Filesystem-backed key-value store with atomic writes.

Frontend (`ts_web/`)

Built with Lit web components and @design.estate/dees-catalog UI library
Reactive state management via smartstate (4 state parts: login, connections, data, UI)
8 tabbed views: Overview, Connections, Projects, Groups, Secrets, Pipelines, Build Log, Actions
WebSocket client for real-time webhook push notifications
Bundled to ts_bundled/bundle.ts via @git.zone/tsbundle (base64-encoded, committed to git)

Shared Types (`ts_interfaces/`)

data/ — Data models (IProject, ISecret, IPipeline, IIdentity, etc.)
requests/ — TypedRequest interfaces for all RPC endpoints

🔌 API

All endpoints use TypedRequest — a typed RPC protocol over HTTP POST to /typedrequest.

Authentication

// Login → returns JWT identity
{ method: 'adminLogin', request: { username, password } }
// → { identity: { jwt, userId, role, expiresAt } }

// All other requests require identity
{ method: 'getProjects', request: { identity, connectionId } }

Connections

Method	Description
`getConnections`	List all connections (tokens masked)
`createConnection`	Add a new Gitea/GitLab connection
`updateConnection`	Update connection name/URL/token
`testConnection`	Verify connection is reachable
`deleteConnection`	Remove a connection

Data

Method	Description
`getProjects`	List projects (with search/pagination)
`getGroups`	List groups/orgs (with search/pagination)
`getAllSecrets`	Get all secrets for a connection+scope (cache-first)
`getSecrets`	Get secrets for a specific entity (cache-first)
`createSecret` / `updateSecret` / `deleteSecret`	Secret CRUD
`getPipelines`	List pipelines for a project
`getPipelineJobs`	List jobs for a pipeline
`retryPipeline` / `cancelPipeline`	Pipeline actions
`getJobLog`	Fetch raw build log for a job

Actions

Method	Description
`forceScanSecrets`	Trigger immediate full secrets scan
`getScanStatus`	Get scan status, last result, timestamp

Webhooks

# Register this URL in your Gitea/GitLab webhook settings
POST http://your-server:3000/webhook/<connectionId>

Events are parsed from X-Gitea-Event / X-Gitlab-Event headers and broadcast to all connected WebSocket clients as webhookNotification.

🧪 Development

# Watch mode — auto-rebuilds frontend + restarts backend on changes
pnpm run watch

# Run tests (Deno)
pnpm test

# Build frontend bundle only
pnpm build

# Start server directly
deno run --allow-all mod.ts server

Project Structure

gitops/
├── mod.ts                    # Entry point
├── deno.json                 # Deno config + import map
├── package.json              # npm metadata + scripts
├── npmextra.json             # tsbundle + tswatch config
├── html/index.html           # HTML shell
├── ts/                       # Backend
│   ├── classes/              # GitopsApp, ConnectionManager
│   ├── providers/            # BaseProvider, GiteaProvider, GitLabProvider
│   ├── storage/              # StorageManager
│   ├── cache/                # CacheDb, CacheCleaner, SecretsScanService
│   │   └── documents/        # CachedProject, CachedSecret
│   └── opsserver/            # OpsServer + 9 handlers
│       ├── handlers/         # AdminHandler, SecretsHandler, etc.
│       └── helpers/          # Guards (JWT verification)
├── ts_interfaces/            # Shared TypeScript types
│   ├── data/                 # IProject, ISecret, IPipeline, etc.
│   └── requests/             # TypedRequest interfaces
├── ts_web/                   # Frontend SPA
│   ├── appstate.ts           # Smartstate store + actions
│   └── elements/             # Lit web components
│       └── views/            # 8 view components
├── ts_bundled/bundle.ts      # Embedded frontend (base64, committed)
└── test/                     # Deno tests

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@serve.zone/gitops