OpsLedger

A centralized change logging system for tracking infrastructure, deployment, and configuration changes across your organization's systems.

Overview

OpsLedger provides a single source of truth for all changes made to your infrastructure. Whether you're deploying new services, updating configurations, or modifying network settings, this platform helps teams maintain visibility and accountability over their entire change history.

Screenshots

Change Log	Filter by Environment

Register Change	API Key Management

Features

Change Management

Register Changes - Log infrastructure, deployment, and configuration changes with rich metadata including system, environment, change type, and detailed descriptions
Scheduled Changes - Pre-register planned changes before they happen. Scheduled changes appear in the change log and on a dedicated calendar view. Past-due scheduled changes are flagged as overdue and require explicit confirmation to close out
Confirm Changes - Mark a scheduled change as executed (via the change log, calendar, or API), optionally overriding the execution timestamp
Real-time Filtering - Filter changes by system, environment, user, change type, status (executed / scheduled / overdue), and time range
Search & Autocomplete - Quickly find changes with full-text search and intelligent autocomplete for systems, environments, and users
Calendar View - Visual month grid at /calendar showing upcoming scheduled changes with overdue highlighting and day-level detail

Authentication & Authorization

Role-Based Access Control - Three roles with distinct permissions:
- Viewer - Read-only access to the change log
- Editor - Can register new changes
- Admin - Full access including user and API key management
JWT Session Authentication - Secure email/password authentication with token-based sessions

API Key System

Programmatic Access - Create API keys for CI/CD pipelines and external tools
Scoped Permissions - Define key permissions with scopes like changes:read and changes:write
Key Rotation - Easily rotate and revoke API keys
Usage Tracking - Monitor when keys were last used

Connectors

Jira Integration - Connect OpsLedger to Jira via webhook. Incoming Jira issue events are automatically converted into change log entries using a configurable type mapping and environment label prefix
Webhook Security - Each connector is issued a unique secret; all incoming webhook payloads are verified with HMAC-SHA256 before processing
Connector Management - Admins can create, enable/disable, edit, and delete connectors from the dedicated Connectors page (/connectors)

Admin Panel

User management (create, edit, delete users)
API key lifecycle management
Connector management (Jira webhooks)
Audit log for security tracking

Real-time Updates

The change log updates live across all open browser sessions without any page refresh — powered by Server-Sent Events (SSE)

Use Cases

DevOps Teams

Track all infrastructure changes in one place. When incidents occur, quickly identify what changed and who made the change.

Compliance & Auditing

Maintain a complete audit trail of all system modifications for compliance requirements (SOC 2, ISO 27001, etc.).

CI/CD Integration

Automatically log deployment changes from your CI/CD pipelines using the API key system. Integrate with GitHub Actions, GitLab CI, Jenkins, or any other CI tool.

Incident Response

During post-incident reviews, quickly correlate outages with recent changes to identify root causes.

Knowledge Sharing

Teams can see what changes others are making, reducing duplicate work and improving cross-team coordination.

Agent vs Human Change Tracking

Track changes made by different sources to understand automation impact:

MCP Agents - Log changes from AI agents and automation tools (e.g., Claude Code, custom MCP servers). Available MCP tools: register_change, confirm_change, update_change, list_changes, delete_change
REST API - Track changes made via direct API calls from external systems
UI Changes - Record changes made by humans through the web interface

This provides visibility into how much of your change history is driven by automation versus manual human actions, helping teams understand their level of infrastructure automation.

Getting Started

Prerequisites

Docker & Docker Compose (recommended)
Or: Node.js 18+, Go 1.21+, MariaDB/MySQL 8+

Quick Start with Docker (recommended)

Clone the repository

git clone https://github.com/your-org/ops-ledger.git
cd ops-ledger

Start all services
```
make up
```
- UI: http://localhost:8080
- Backend API: http://localhost:8081
- MariaDB: localhost:3306
Register your first user Visit http://localhost:8080 — the first registered user is automatically granted the admin role.

Local Development (without Docker)

Start the backend
```
cd backend
go run .
```
The API server starts on http://localhost:8081.
Start the frontend
```
cd frontend
npm install
npm run dev
```
The frontend dev server starts on http://localhost:5173.

Environment Variables

Copy .env.example to .env in the project root to override defaults.

Backend (defaults in backend/config/config.go, no .env required for local dev):

PORT=8081
DB_HOST=localhost
DB_PORT=3306
DB_USER=tracker
DB_PASSWORD=tracker_dev
DB_NAME=ops_ledger
JWT_SECRET=your_jwt_secret

Frontend (create frontend/.env):

VITE_API_URL=http://localhost:8081/api

API Documentation

Authentication

Method	Endpoint	Description
POST	`/api/auth/register`	Register a new user
POST	`/api/auth/login`	Login and get JWT
GET	`/api/auth/me`	Get current user info
POST	`/api/auth/logout`	Logout

Changes API

Method	Endpoint	Description
GET	`/api/changes`	List changes (supports filtering)
POST	`/api/changes`	Create a new change
PUT	`/api/changes/:id`	Update an existing change
DELETE	`/api/changes/:id`	Delete a change
PATCH	`/api/changes/:id/confirm`	Confirm a scheduled change as executed

Supported Filters:

system - Filter by system name
environment - Filter by environment (prod, staging, dev, etc.)
type - Filter by change type (infrastructure, deployment, configuration)
status - Filter by status (executed, scheduled, overdue)
user - Filter by user
from / to - Date range filtering (ISO 8601)
search - Full-text search across description and system

Creating a scheduled change:

POST /api/changes
{
  "system": "api-gateway",
  "type": "deployment",
  "description": "Upgrade to v3.0",
  "status": "scheduled",
  "timestamp": "2026-06-15T10:00:00Z"
}

When status is "scheduled", timestamp is required and must be in the future. When status is "executed" (default), timestamp is optional and defaults to now.

Confirming a scheduled change:

PATCH /api/changes/:id/confirm
{ "timestamp": "2026-06-15T10:05:00Z" }   // optional — defaults to now

Returns 409 Conflict if the change is already executed.

Admin API Keys

Method	Endpoint	Description
GET	`/api/admin/api-keys`	List all API keys
POST	`/api/admin/api-keys`	Create a new API key
POST	`/api/admin/api-keys/:id/revoke`	Revoke an API key
POST	`/api/admin/api-keys/:id/rotate`	Rotate an API key

Connectors API (admin only)

Method	Endpoint	Description
GET	`/api/admin/connectors`	List all connectors
POST	`/api/admin/connectors`	Create a new Jira connector
PUT	`/api/admin/connectors/:id`	Update a connector
DELETE	`/api/admin/connectors/:id`	Delete a connector
POST	`/api/connectors/:id/webhook`	Jira webhook receiver (no auth — HMAC-verified)

Creating a Jira connector:

POST /api/admin/connectors
{
  "name": "My Jira",
  "jira_url": "https://myorg.atlassian.net",
  "api_token": "your_jira_api_token",
  "mapping": {
    "type_map": { "Change": "configuration", "Deployment": "deployment", "Infrastructure": "infrastructure" },
    "environment_label_prefix": "env:"
  }
}

The response includes the secret to use as the HMAC key when configuring the Jira webhook. Point your Jira automation webhook at POST /api/connectors/:id/webhook.

Authentication

The API supports two authentication methods:

JWT Bearer Token - Use for web interface authentication
```
Authorization: Bearer <your_jwt_token>
```
API Key - Use for CI/CD and programmatic access
```
X-API-Key: <your_api_key>
```

Tech Stack

Frontend

React 18 with TypeScript
Vite - Build tool and dev server
Tailwind CSS - Styling
shadcn/ui - Component library (Radix UI primitives)
React Router DOM - Client-side routing
TanStack Query - Server state management
React Hook Form + Zod - Form handling and validation
Recharts - Data visualization

Backend

Go with the Echo framework
MySQL database
JWT for session authentication
SHA-256 for API key hashing

Project Structure

ops-ledger/
├── frontend/
│   ├── src/
│   │   ├── components/   # Reusable UI components (shadcn/ui in components/ui/)
│   │   ├── pages/        # Page components
│   │   ├── lib/          # API client and utilities
│   │   ├── hooks/        # Custom React hooks
│   │   ├── contexts/     # Auth and app context providers
│   │   └── types/        # TypeScript type definitions
│   ├── Dockerfile        # Dev container image
│   └── Dockerfile.prod   # Production multi-stage image
├── backend/
│   ├── main.go           # Application entry point
│   ├── config/           # Environment config with dev defaults
│   ├── models/           # Database models + SQL query functions
│   ├── handlers/         # HTTP request handlers
│   ├── middleware/        # JWT and API key auth middleware
│   └── database/         # Schema migrations (CREATE TABLE IF NOT EXISTS)
├── docker-compose.yml    # Dev stack (UI :8080, API :8081, DB :3306)
├── docker-compose.prod.yml
└── Makefile              # Common dev commands

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

GNU Affero General Public License v3.0 (AGPL-3.0) — see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
backend		backend
dist		dist
docs/screenshots		docs/screenshots
frontend		frontend
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

OpsLedger

Overview

Screenshots

Features

Change Management

Authentication & Authorization

API Key System

Connectors

Admin Panel

Real-time Updates

Use Cases

DevOps Teams

Compliance & Auditing

CI/CD Integration

Incident Response

Knowledge Sharing

Agent vs Human Change Tracking

Getting Started

Prerequisites

Quick Start with Docker (recommended)

Local Development (without Docker)

Environment Variables

API Documentation

Authentication

Changes API

Admin API Keys

Connectors API (admin only)

Authentication

Tech Stack

Frontend

Backend

Project Structure

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages