git-change-operator¶

A Kubernetes operator that enables automated Git operations from within clusters. Commit files directly or reference existing Kubernetes resources (encrypt Secrets, ConfigMaps, etc.) and push them to Git repositories with flexible output strategies.

Docs: https://gco.galos.one

Features¶

• Direct File Commits: Commit static file content to Git repositories
• Resource References: Reference arbitrary Kubernetes resources and commit their data
• Flexible Output Strategies:
• Dump entire resources as YAML
• Extract all resource fields as separate files
• Extract specific fields with custom naming
• Write Modes: Overwrite or append to existing files
• Git Operations: Support for both direct commits and pull requests
• File Encryption: Age-based encryption with support for SSH keys, age keys, and passphrases
• Secure Authentication: Uses Kubernetes Secrets for Git authentication

Minimal demo¶

apiVersion: gco.galos.one/v1
kind: GitCommit
metadata:
  name: resource-backup
  namespace: my-namespace
spec:
  repository:
    url: "https://github.com/your-username/k8s-backups.git"
    branch: "main"

  auth:
    secretName: "git-credentials"

  commit:
    author: "Git Change Operator <[email protected]>"
    message: "Automated backup of cluster resources"

  resourceReferences:
    # Backup ConfigMap as complete YAML
    - name: "app-config"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "default"
      strategy: "dump"
      output:
        path: "backups/configmaps/app-config.yaml"

Minimal demo using self-hosted Kind cluster¶

Please have a token (preferably fine-grained) with fine-grained permissions ready, the following step asks for it if not already present in a git-ignored file called token in this repo.

make kind-full-demo

Resource Reference Capabilities¶

The operator can reference any Kubernetes resource and extract its data using various strategies:

Output Strategies¶

1. Dump: Output entire resource as YAML
2. Fields: Extract all data fields as separate files
3. Single-Field: Extract specific fields with custom naming

Write Modes¶

• Overwrite: Replace file content (default)
• Append: Add to existing file content

Architecture¶

graph TB
    %% User creates resources
    User["👤 User"] -->|creates| A["📄 GitCommit/PullRequest CR"]

    %% Operator watches and processes
    B["⚙️ Git Change Operator"] -->|watches| A

    %% Operator reads from K8s Cluster
    B -->|reads data from| D["☸️ K8s Cluster"]
    D -->|contains| E["📦 ConfigMaps"]
    D -->|contains| F["🔐 Secrets"] 

    %% Operator authenticates and writes to Git
    B -->|clones/pulls| C["📚 Git Repository"]
    B -->|commits & pushes| C
    B -->|creates PR| G["🐙 GitHub"]

    %% Repository states

    %% Styling
    classDef userAction fill:#e1f5fe
    classDef operator fill:#f3e5f5
    classDef k8sResource fill:#e8f5e8
    classDef gitResource fill:#fff3e0
    classDef github fill:#f6f8fa

    class User userAction
    class B operator
    class D,E,F k8sResource
    class C gitResource
    class G github

Use Cases¶

Configuration Management¶

Export cluster configuration to Git repositories for backup and version control.

GitOps Workflows¶

Automatically update Git repositories when cluster state changes, enabling bidirectional GitOps.

Compliance & Auditing¶

Maintain Git history of configuration changes for compliance and audit trails.

Multi-Cluster Synchronization¶

Share configuration between clusters through Git repositories.

Quick Navigation¶

License¶

This project is licensed under the MIT License - see the LICENSE file for details.