GitOps / State Management

Scribe

Reverse GitOps — Automatically capture runtime state changes from your Kubernetes cluster and persist them to Git as the source of truth.

Learn More Get Started
Scribe wireframe
01

Overview

Scribe is a Kubernetes operator that enables capturing runtime state changes from cluster resources and automatically committing them back to Git. Unlike traditional GitOps tools like ArgoCD and Flux that synchronize from Git to cluster, Scribe does the opposite: it watches your running workloads for changes, extracts specified fields, and persists them to your repository as the authoritative source of truth.

Resources change at runtime for a variety of reasons. When Autoscalers scale your deployments, when FinOps tools adjust your quotas, when operators like cert-manager generate certificates, or when manual changes need to become the new baseline, Scribe captures these runtime-generated values and commits them to Git. Your repository always reflects the actual desired state, enabling true declarative infrastructure with full audit trails and cross-cluster state synchronization.

02

Features

Field Extraction & CEL Transforms

Extract specific fields using JSONPath expressions like `.spec.replicas` or `.status.loadBalancer.ingress[0].ip`. Apply CEL (Common Expression Language) transformations to modify values before writing, enabling computed fields and data normalization.

Dynamic Resource Watching

Watch any Kubernetes resource type with on-demand informer creation. No operator restart required when adding new resource types. Supports label selectors, namespace filtering, and multi-resource monitoring with reference-counted lifecycle management.

Intelligent Change Detection

LRU cache-based change detection with hashing prevents redundant commits. Per-resource, per-field tracking ensures only actual changes trigger Git operations.

Batching & Rate Limiting

Time-windowed change aggregation combines multiple updates into single commits. Configurable rate limits (commits per hour, minimum push interval) protect your Git server and reduce history noise while ensuring timely synchronization.

Multiple Output Formats

Write captured state in YAML patch (minimal diff), full YAML, JSON, or Kustomize patch format. Choose strategic merge, JSON merge, or full replacement patch strategies to match your GitOps workflow requirements.

Pull Request Workflows

Create pull requests instead of direct commits with support for GitHub, GitLab, Bitbucket, and Gitea. Configure branch strategies, auto-merge policies, custom reviewers, and CI integration for governed change management.

03

Use Cases

04

Custom Resources

05

Example Workflow

This example demonstrates capturing HPA-managed replica counts from Deployments and persisting them to a Git repository. When the autoscaler adjusts replicas, Scribe automatically commits the new values, ensuring your Git repository always reflects the actual running state. 

# 1. Create a GitRepository resource to connect to your config repo
  oc apply -f - <<EOF
  apiVersion: scribe.cosmosdevops.co.uk/v1alpha1
  kind: GitRepository
  metadata:
    name: platform-config
    namespace: scribe-system
  spec:
    url: https://github.com/your-org/platform-config.git
    branch: main
    auth:
      type: https-token
      secretRef:
        name: git-credentials
  EOF

  # 2. Create a ScribePolicy to capture Deployment replicas
  oc apply -f - <<EOF
  apiVersion: scribe.cosmosdevops.co.uk/v1alpha1
  kind: ScribePolicy
  metadata:
    name: capture-replicas
    namespace: default
  spec:
    source:
      apiVersion: apps/v1
      kind: Deployment
      selector:
        matchLabels:
          scribe.cosmosdevops.co.uk/capture: "true"
    fields:
      - path: ".spec.replicas"
    target:
      repositoryRef:
        name: platform-config
        namespace: scribe-system
      pathTemplate: "apps/{{ .Namespace }}/{{ .Name }}.yaml"
      format: yaml-patch
    sync:
      interval: 5m
      batchWindow: 30s
  EOF

  # 3. Label Deployments you want to capture
  oc label deployment my-app scribe.cosmosdevops.co.uk/capture=true

  # 4. Verify the policy is active and syncing
  oc get scribepolicy capture-replicas -o yaml | grep -A 10 status

Ready to implement reverse GitOps?

Start capturing runtime state changes and persisting them to Git. Close the loop on GitOps with automatic state synchronization from cluster to repository.

Get Started