gitops-by-veera 1.0.0

Conversational autonomous Git and GitHub operations coordinator using Groq-hosted LLMs.

gitops-by-veera

A production-ready, security-hardened, conversational autonomous Git and GitHub operations coordinator. Convert natural language into safe, validated local Git commands and GitHub REST API calls — powered by Groq-hosted LLMs.

---

Features

• Natural language to Git/GitHub actions — describe what you want, GitOps plans and executes it
• Dual-domain operations — local Git commands and GitHub cloud API calls in a single pipeline
• Security-first architecture — command injection prevention, path traversal blocking, shell injection defense, and prompt injection resistance
• Model cascading — automatic fallback across three Groq-hosted model tiers
• Self-healing remediation — failed operations trigger AI-generated fix suggestions (capped at 2 cycles)
• Direct evaluation bypass — trivial commands (git status, git diff, git log) skip the LLM entirely for speed
• Structured JSON contracts — all LLM output is parsed into strict Pydantic models
• Session telemetry — detailed execution metrics available with --debug
• Colab/Jupyter compatible — runs in notebooks, cloud runtimes, and local terminals

---

Installation

From PyPI

pip install gitops-by-veera

From source

git clone https://github.com/vkprince6/gitops-by-veera.git
cd gitops-by-veera
pip install -e ".[dev]"

Google Colab

!pip install gitops-by-veera
import subprocess
subprocess.run(["git-ops", "setup"])

---

Credentials & Security

GitOps requires two API credentials:

Credential	Environment Variable	Description
Groq API Key	GROQ_API_KEY	From console.groq.com
GitHub Token	GITHUB_TOKEN	Fine-grained PAT with repo read/write scopes

IMPORTANT: Classic admin GitHub tokens are strictly prohibited. You MUST use fine-grained Personal Access Tokens scoped to specific repositories with only the permissions required for your workflow.

Credentials are stored at ~/.gitops_by_veera_config.json with chmod 600 permissions. They are never logged or printed to the terminal.

---

Setup

git-ops setup

You will be prompted (via getpass) for your Groq API key and GitHub token. Alternatively, set environment variables:

export GROQ_API_KEY="gsk_..."
export GITHUB_TOKEN="github_pat_..."

---

Usage

Run a natural language pipeline

git-ops run "Stage all files, commit with message 'feat: initial setup', and push to origin main"

Dry-run (plan and validate only — no execution)

git-ops run "Create a branch called feature-xyz and push it" --dry-run

Debug mode with telemetry

git-ops run "Open a PR from feature-xyz to main with title 'New Feature'" --debug

---

Supported Operations

Local Git

Operation	Risk Level
git status, git diff, git log	Safe
git add, git commit, git fetch, git pull	Safe
git push, git branch, git checkout, git switch	Safe
git reset --hard, git clean -fd, git push --force	Warning — requires confirmation
git rebase, git cherry-pick, git stash clear	Warning — requires confirmation
git filter-branch, git reflog expire, git gc --prune=now	Blocked

GitHub Cloud (via REST API)

• Create repositories (/user/repos, /orgs/{org}/repos)
• Manage branches and refs (/repos/{owner}/{repo}/git/refs)
• Open, list, and update Pull Requests (/repos/{owner}/{repo}/pulls)
• Merge Pull Requests (/repos/{owner}/{repo}/pulls/{number}/merge)
• Create and update Issues (/repos/{owner}/{repo}/issues)
• Trigger GitHub Actions workflows (/repos/{owner}/{repo}/actions/workflows/{id}/dispatches)

All DELETE requests and repository-level destructive endpoints are strictly blocked.

---

Example Workflows

# View repository status (bypasses LLM entirely for speed)
git-ops run "show status"

# Full branch + commit + PR workflow
git-ops run "Create branch feature-auth, commit staged files with message 'feat: add auth', push, and open a PR to main"

# Create a GitHub issue
git-ops run "Create an issue titled 'Bug: login fails on mobile' with a description"

# Trigger a workflow dispatch
git-ops run "Trigger the deploy.yml workflow on the main branch"

---

Google Colab Integration

!pip install gitops-by-veera

import os
os.environ["GROQ_API_KEY"] = "gsk_..."      # or use Colab secrets
os.environ["GITHUB_TOKEN"] = "github_pat_..."

import subprocess
result = subprocess.run(
    ["git-ops", "run", "show git status", "--dry-run"],
    capture_output=True, text=True
)
print(result.stdout)

---

Architecture

User prompt
    │
    ├── Direct Evaluation Router (regex bypass for trivial commands)
    │       └── Returns plan immediately, skips LLM
    │
    └── LLM Cascade (Groq API)
            ├── Tier 1: openai/gpt-oss-120b
            ├── Tier 2: openai/gpt-oss-20b
            └── Tier 3: llama-3.1-8b-instant (also used for remediation)
                    │
                    └── Pydantic-validated ExecutionPlan
                            │
                            └── Multi-stage Validator
                                    ├── Binary whitelist enforcement
                                    ├── Shell injection detection
                                    ├── Path traversal blocking
                                    ├── GitHub endpoint whitelist
                                    └── Payload field sanitization
                                            │
                                            └── Sequential Executor
                                                    ├── Local: subprocess.run (shell=False)
                                                    └── Cloud: requests → GitHub REST API
                                                            │
                                                            └── Self-Healing Remediation (≤2 cycles)

---

Development

pip install -e ".[dev]"

# Run tests
pytest --cov=src/gitops_by_veera --cov-report=term-missing

# Type checking
mypy src/

# Linting
ruff check src/ tests/

---

License

MIT License — see LICENSE.

---

Security

See SECURITY.md for the full security architecture and responsible disclosure policy.