GitOps is a self-hosted operations dashboard for Gitea and GitLab. It connects provider instances, centralizes CI/CD secret visibility, mirrors repositories, watches pipelines, streams job logs, and can publish repository documentation into BookStack from one Deno-powered web 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.

What It Does

Connects to Gitea and GitLab through provider adapters with a shared project, group, secret, pipeline, and file-content interface.
Stores provider tokens and BookStack job tokens through @push.rocks/smartsecret, using OS keychain support where available and an encrypted fallback otherwise.
Serves a bundled Lit/dees-catalog single page app through @api.global/typedserver with TypedRequest handlers for all backend actions.
Scans project and group CI/CD secrets into an embedded SmartMongo cache and refreshes that cache on startup and every 24 hours.
Mirrors repositories from a source connection to a target connection with group offset support, metadata sync, stale repository handling, and live sync logs.
Manages reusable secret definitions that can be pushed to selected project or group targets.
Runs scheduled jobs, currently focused on syncing readme.md, changelog.md, and docs/*.md content into BookStack shelves, books, and pages.
Receives provider webhooks at POST /webhook/:connectionId and broadcasts events to connected browser clients.

Runtime Shape

GitOps is a Deno app with an npm package wrapper for dependency and build tooling.

Area	Implementation
Entry point	`mod.ts`, default command `server`
Backend	`ts/`, centered around `GitopsApp`
Web server	`ts/opsserver/`, TypedServer plus TypedRequest handlers
Shared contracts	`ts_interfaces/` data and request interfaces
Frontend	`ts_web/`, Lit web components and smartstate
Bundle output	`ts_bundled/bundle.ts`, generated by `tsbundle`
Persistent storage	`~/.serve.zone/gitops/storage/`
Cache database	`~/.serve.zone/gitops/tsmdb/`

Key Components

Component	Role
`GitopsApp`	Starts storage, provider connections, cache, sync, jobs, managed secrets, scans, and the OpsServer.
`ConnectionManager`	Persists Gitea/GitLab connections, migrates old plaintext tokens into SmartSecret, and background-checks connection health.
`GiteaProvider` / `GitLabProvider`	Provider-specific adapters behind a shared `BaseProvider` interface.
`SecretsScanService`	Fetches project and group secrets in batches and upserts them into cached SmartData documents.
`SyncManager`	Mirrors repositories with bare git clones, source/target path mapping, deletion safeguards, branch/default-branch handling, and metadata sync.
`ManagedSecretsManager`	Stores define-once secret records and pushes them to selected project or group targets.
`JobManager`	Stores scheduled jobs, starts interval timers, masks persisted secrets, and dispatches job execution to registered runners.
`AutoBookstackDocsRunner`	Maps git groups to BookStack shelves, repos to books, and markdown files to pages with content hashes to avoid noisy updates.

Server Configuration

Variable	Default	Purpose
`GITOPS_PORT`	`3000`	HTTP and WebSocket server port.
`GITOPS_ADMIN_USERNAME`	`admin`	Dashboard login username.
`GITOPS_ADMIN_PASSWORD`	`admin`	Dashboard login password.

Provider connections, sync configs, jobs, managed secrets, and action logs are persisted as JSON records below ~/.serve.zone/gitops/storage/. Cached projects and secrets live in the embedded SmartMongo directory below ~/.serve.zone/gitops/tsmdb/.

API Surface

The backend exposes TypedRequest methods through /typedrequest and a custom webhook route. The important handler groups are:

Handler	Examples
Admin	`adminLogin`, `adminLogout`, `verifyIdentity`
Connections	`getConnections`, `createConnection`, `updateConnection`, `testConnection`, `pauseConnection`, `deleteConnection`
Projects and Groups	Provider browsing with search/pagination style request contracts
Secrets	Cached and direct project/group secret CRUD
Managed Secrets	Definition CRUD plus push-to-target operations
Pipelines and Logs	Pipeline listing, jobs, retry/cancel, and raw job log fetches
Sync	Sync config CRUD, preview, trigger, status, and logs
Jobs	Scheduled job CRUD, trigger, pause/resume, and logs
Webhooks	`POST /webhook/:connectionId` for provider event fan-out

Auto BookStack Documentation

The current scheduled job type is autobookstackdocs. It reads markdown documentation from connected Git providers and publishes it into BookStack.

Git source	BookStack target
Group or organization	Shelf
Repository	Book named `@group/repo`
`readme.md` or `changelog.md`	Page named `<file> for @group/repo`
`docs/*.md`	Page named `<path> for @group/repo`

Notable behavior from the runner implementation:

SHA-256 hashes are persisted per job so unchanged pages are skipped.
Optional delete propagation can remove stale shelves, books, and pages.
Optional visibility sync can restrict private/internal repos in BookStack.
Tags are collected from git topics and package.json keywords.
Root headings that duplicate the book or page context are stripped before publication.

Development

pnpm install
pnpm build
pnpm test
pnpm run startTs

Useful direct commands:

deno run --allow-all mod.ts server
GITOPS_PORT=3001 deno run --allow-all mod.ts server
pnpm run watch

Project Map

gitops/
├── mod.ts
├── deno.json
├── package.json
├── html/
├── ts/
│   ├── classes/
│   ├── cache/
│   ├── opsserver/
│   ├── providers/
│   └── storage/
├── ts_interfaces/
├── ts_web/
├── ts_bundled/
└── test/

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