gitops-by-veera 1.0.3

Natural language → Git & GitHub operations, with a beautiful web UI

GitOps by Veera

Turn natural language into Git and GitHub operations — with a beautiful web UI.

---

What is it?

gitops-by-veera is an AI-powered GitOps agent that understands plain English and converts it into safe Git commands and GitHub API calls. It launches a polished dark-themed web UI where you can:

• Create GitHub repositories with a single sentence
• Stage, commit, and push code conversationally
• Open pull requests and create issues by describing what you want
• Preview every action in Dry Run mode before executing it live
• Use your voice to speak commands directly

Powered by Groq (free, fast LLM inference) and the GitHub REST API.

---

Quick Start

1. Install

pip install gitops-by-veera

2. Get your API keys

Key	Where to get it	Notes
Groq API Key	console.groq.com → API Keys	Free tier available
GitHub Token	github.com/settings/tokens → Classic token	Enable repo scope

3. Launch

import gitops_by_veera

gitops_by_veera.launch()

The web UI opens in your browser. Enter your keys in Settings (⚙) and start typing commands.

---

Installation Options

# Latest stable
pip install gitops-by-veera

# Specific version
pip install gitops-by-veera==1.0.3

# Upgrade to latest
pip install --upgrade gitops-by-veera

Requirements: Python 3.10 or higher. No other system dependencies.

---

Usage

Python API

import gitops_by_veera

# Launch with default settings (auto-detect port, open browser)
gitops_by_veera.launch()

# Custom port
gitops_by_veera.launch(port=8080)

# Server only — do not open a browser window
gitops_by_veera.launch(open_browser=False)

# Suppress uvicorn logs
gitops_by_veera.launch(log_level="error")

# Check the version
print(gitops_by_veera.__version__)   # → "1.0.3"

Command-line interface

# Launch the web UI (same as launch())
gitops serve

# Run a single command from the terminal (no UI)
gitops run "Create a branch called feature-login"

# Store credentials on disk so you don't have to type them every time
gitops setup

# Options
gitops serve --port 9000 --no-browser
gitops run "stage all and commit 'fix: typo'" --dry-run

Environment-variable credentials (CI/scripts)

export GROQ_API_KEY="gsk_..."
export GITHUB_TOKEN="ghp_..."
gitops run "Create a private repo named my-project"

---

Environment Support

Environment	Works?	Notes
Local machine	✅	Opens browser automatically
Jupyter Notebook	✅	Prints the URL; paste it in a new tab
Google Colab	✅	Displays an inline iframe automatically
Replit	✅	Reads $PORT, prints the public proxy URL
Docker / cloud VM	✅	Bind to 0.0.0.0, expose port externally
VS Code devcontainer	✅	Port-forwarding handled by VS Code

Docker example

FROM python:3.11-slim
RUN pip install gitops-by-veera
EXPOSE 7860
CMD ["python", "-c", \
  "import os, uvicorn; from gitops_by_veera.server import app; \
  uvicorn.run(app, host='0.0.0.0', port=int(os.environ.get('PORT', 7860)))"]

Running as a persistent server (recommended for production)

When you need the process to stay alive without a main-thread loop, run uvicorn directly instead of using launch():

# server.py
import os
import uvicorn
from gitops_by_veera.server import app

port = int(os.environ.get("PORT", 7860))
print(f"GitOps by Veera → http://localhost:{port}")
uvicorn.run(app, host="0.0.0.0", port=port)

python server.py
# or
PORT=8000 python server.py

Jupyter Notebook

import gitops_by_veera

url = gitops_by_veera.launch(open_browser=False)
print(f"Open: {url}")
# Keep the kernel alive — the server runs in a background daemon thread

Google Colab

!pip install gitops-by-veera -q

import gitops_by_veera
gitops_by_veera.launch()  # shows an inline iframe automatically

---

Voice Input

The 🎤 voice button in the web UI uses the browser's built-in Web Speech API.

Browser	Voice support
Chrome (desktop & Android)	✅ Full support
Edge (desktop)	✅ Full support
Safari 17+ (macOS/iOS)	⚠ Partial — may need explicit permission
Firefox	❌ Not supported (Web Speech API not available)

Troubleshooting voice:

• "Microphone access denied" — click the lock/camera icon in the address bar → allow microphone, then refresh
• "Not supported" — switch to Chrome or Edge
• Works locally but not on a remote server — Web Speech API requires HTTPS (or localhost). Use a reverse proxy with TLS, or run locally
• No speech detected — try again; speak clearly within 5 seconds of clicking 🎤

---

How It Works

You type: "Create a private repo named demo and push my local code"
          ↓
     [Groq LLM] — plans a sequence of operations as structured JSON
          ↓
  Execution Plan:
    1. [cloud] POST /user/repos  { name: "demo", private: true }
    2. [local] git remote add origin [e-mail]:you/demo.git
    3. [local] git push --set-upstream origin main
          ↓
  Validator — checks security rules, blocks dangerous operations
          ↓
  Dry Run preview (default) OR Live execution
          ↓
  Results displayed in the chat UI with full output

Security model

• Dry Run by default — nothing executes until you toggle it off
• Whitelist-only — only pre-approved GitHub API endpoints are allowed
• No DELETE — repository deletion and destructive cloud operations are blocked
• Path traversal protection — local file paths are validated against the repo root
• Shell injection prevention — commands run via subprocess with shell=False
• Payload sanitization — unknown fields are stripped from API payloads

---

Configuration

Port resolution order

1. port argument to launch() or gitops serve --port
2. $PORT environment variable
3. Default: 7860

Credential storage

Credentials can be provided in three ways (checked in priority order):

1. Environment variables — GROQ_API_KEY and GITHUB_TOKEN
2. Config file — stored by gitops setup at ~/.gitops_by_veera_config.json (chmod 600)
3. UI settings — entered in the Settings modal, saved to browser localStorage

---

REST API

The server exposes two endpoints for programmatic/headless use:

GET /api/health

{ "status": "ok", "version": "1.0.3" }

POST /api/run

Request body:

{
  "prompt": "Create a private repo named demo",
  "groq_api_key": "gsk_...",
  "github_token": "ghp_...",
  "repo_path": "/path/to/local/repo",
  "dry_run": true
}

Field	Type	Required	Default	Description
prompt	string	✅	—	Natural language command
groq_api_key	string	✅	—	Groq API key
github_token	string	✅	—	GitHub personal access token
repo_path	string	❌	cwd	Path to local git repo for local operations
dry_run	boolean	❌	true	If true, plan is returned but nothing executes

Response:

{
  "plan": [
    {
      "index": 0,
      "type": "cloud",
      "method": "POST",
      "endpoint": "/user/repos",
      "payload": { "name": "demo", "private": true },
      "risk_level": "safe",
      "reason": "Creates a new private GitHub repository."
    }
  ],
  "warnings": [],
  "results": [
    {
      "operation_index": 0,
      "operation_type": "cloud",
      "success": true,
      "stdout": "{ \"id\": 123456, \"full_name\": \"you/demo\", ... }",
      "stderr": "",
      "error_message": ""
    }
  ],
  "mode": "DRY-RUN",
  "metrics": {
    "active_model": "llama-3.3-70b-versatile",
    "total_llm_calls": 1,
    "duration": 1.23
  }
}

---

Example Commands

GitHub Cloud

Create a private repo named my-api in my account
Create a public repo named my-project with description 'Demo project'
Open a PR from feature-branch to main with title 'Add authentication'
Create an issue titled 'Bug: login fails' in repo myorg/myrepo

Local Git

Stage all files and commit with message 'feat: initial setup'
Create a branch called feature-xyz
Push to origin main
Show the last 10 commits
git status
git diff

Pipelines (multi-step)

Stage all files, commit with message 'first commit', create a private repo named demo, push to it
Create a branch called hotfix, commit all changes with message 'fix: critical bug', push the branch

---

Changelog

1.0.3

• Fixed voice input: per-error messages (not-allowed, no-speech, network), no accidental auto-send on error, try/catch on rec.start(), graceful message for unsupported browsers
• Added CORS middleware so the server works behind any proxy or cross-origin client
• Dynamic version badge in UI — fetched live from /api/health, never stale
• Improved launch(): explicit $PORT env-var support, better Replit / Colab / local detection, named daemon thread
• Version injected server-side into HTML template via string replacement

1.0.2

• Model cascade improvements and fallback hardening
• Validator endpoint whitelist expanded

1.0.0

• Initial public release

---

Development

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

# Run the dev server with auto-reload
uvicorn gitops_by_veera.server:app --reload --port 7860

# Run tests
pytest

---

License

MIT — see LICENSE.

---

Author

Built by Veera. Issues and pull requests welcome on GitHub.