Metadata-Version: 2.4
Name: ngen-gitops
Version: 0.1.1
Summary: GitOps CLI and web server for Bitbucket operations
Author: ngen-gitops contributors
License: MIT
Project-URL: Homepage, https://github.com/mamatnurahmat/ngen-gitops
Project-URL: Repository, https://github.com/mamatnurahmat/ngen-gitops
Project-URL: Issues, https://github.com/mamatnurahmat/ngen-gitops/issues
Keywords: cli,gitops,bitbucket,devops,api,ci-cd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: fastapi>=0.68.0
Requires-Dist: uvicorn>=0.15.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: python-dotenv>=0.19.0

# ngen-gitops

GitOps CLI and web server for Bitbucket operations. Automate branch creation, YAML image updates, pull request creation, and merging via command-line interface or REST API.

[![PyPI version](https://badge.fury.io/py/ngen-gitops.svg)](https://badge.fury.io/py/ngen-gitops)
[![Python](https://img.shields.io/pypi/pyversions/ngen-gitops.svg)](https://pypi.org/project/ngen-gitops/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🌿 **Branch Management**: Create branches from source branches
- 🖼️ **Image Updates**: Update container images in Kubernetes YAML files
- 🔄 **Pull Requests**: Create and merge pull requests automatically
- 🌐 **Web API**: REST API server with FastAPI for integration
- 🔐 **Secure**: Uses Bitbucket app passwords for authentication
- 📦 **Easy Configuration**: Simple JSON config file
- 🚀 **PyPI Package**: Install with pip

## Installation

```bash
pip install ngen-gitops
```

## Quick Start

### 1. Configuration

On first run, ngen-gitops creates a config file at `~/.ngen-gitops/config.json`:

```json
{
  "bitbucket": {
    "username": "",
    "app_password": "",
    "organization": "loyaltoid"
  },
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  }
}
```

**Update the config with your credentials:**

1. Go to Bitbucket Settings → App passwords
2. Create a new app password with repository read/write permissions
3. Update `~/.ngen-gitops/config.json` with your username and app password

**Or use environment variables:**

```bash
export BITBUCKET_USER="your-username"
export BITBUCKET_APP_PASSWORD="your-app-password"
export BITBUCKET_ORG="your-organization"
```

### 2. Verify Configuration

```bash
ngen-gitops config
```

## Usage

### CLI Commands

#### Create Branch

Create a new branch from a source branch:

```bash
ngen-gitops create-branch <repo> <src_branch> <dest_branch>
```

**Example:**
```bash
ngen-gitops create-branch my-app main feature/new-feature
```

**Output:**
```
🔍 Creating branch 'feature/new-feature' from 'main' in repository 'my-app'...
✅ Source branch 'main' validated (commit: abc1234)
✅ Branch 'feature/new-feature' created successfully from 'main'

✅ Branch 'feature/new-feature' created successfully
   Branch URL: https://bitbucket.org/org/my-app/branch/feature/new-feature
```

#### Update Image in YAML

Update container image in Kubernetes YAML file:

```bash
ngen-gitops set-image-yaml <repo> <branch> <yaml_path> <image> [--dry-run]
```

**Example:**
```bash
ngen-gitops set-image-yaml my-app develop k8s/deployment.yaml myregistry/myapp:v1.2.3
```

**Output:**
```
🔍 Cloning repository my-app (branch: develop)...
✅ Repository cloned
   Current image(s): myregistry/myapp:v1.2.0
   New image: myregistry/myapp:v1.2.3
✅ Updated image in YAML file
✅ Changes committed
✅ Changes pushed to develop

✅ Image updated to myregistry/myapp:v1.2.3 and pushed to develop
   [develop abc1234] chore: update image to myregistry/myapp:v1.2.3
```

**Dry-run mode** (don't push changes):
```bash
ngen-gitops set-image-yaml my-app develop k8s/deployment.yaml myapp:v1.0.0 --dry-run
```

#### Create Pull Request

Create a pull request from source to destination branch:

```bash
ngen-gitops pull-request <repo> <src_branch> <dest_branch> [--delete-after-merge]
```

**Example:**
```bash
ngen-gitops pull-request my-app feature/new-feature develop --delete-after-merge
```

**Output:**
```
🔍 Creating pull request from 'feature/new-feature' to 'develop' in repository 'my-app'...
   ⚠️  Source branch 'feature/new-feature' will be deleted after merge
✅ Source branch 'feature/new-feature' validated
✅ Destination branch 'develop' validated
✅ Pull request created successfully
   PR #42
   URL: https://bitbucket.org/org/my-app/pull-requests/42

✅ Pull request #42 created successfully
   Pull Request URL: https://bitbucket.org/org/my-app/pull-requests/42
```

#### Merge Pull Request

Merge an existing pull request:

```bash
ngen-gitops merge <pr_url> [--delete-after-merge]
```

**Example:**
```bash
ngen-gitops merge https://bitbucket.org/org/my-app/pull-requests/42
```

**Output:**
```
🔍 Merging pull request #42 in repository 'my-app'...
✅ Pull request validated
   Source branch: feature/new-feature
   Destination branch: develop
   State: OPEN
✅ Pull request #42 merged successfully
   Merge commit: abc1234

✅ Pull request #42 merged successfully
   Merge commit: abc1234
```

#### Start Web Server

Start the REST API server:

```bash
ngen-gitops server [--host HOST] [--port PORT]
```

**Example:**
```bash
ngen-gitops server --port 8080
```

**Output:**
```
🚀 Starting ngen-gitops server...
   Host: 0.0.0.0
   Port: 8080
   Endpoints:
     - POST /v1/gitops/create-branch
     - POST /v1/gitops/set-image-yaml
     - POST /v1/gitops/pull-request
     - POST /v1/gitops/merge

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
```

### JSON Output

All commands support `--json` flag for machine-readable output:

```bash
ngen-gitops create-branch my-app main develop --json
```

**Output:**
```json
{
  "success": true,
  "repository": "my-app",
  "source_branch": "main",
  "destination_branch": "develop",
  "message": "Branch 'develop' created successfully",
  "branch_url": "https://bitbucket.org/org/my-app/branch/develop"
}
```

## REST API

### Starting the Server

```bash
ngen-gitops server --port 8080
```

### API Endpoints

#### 1. Create Branch

**Endpoint:** `POST /v1/gitops/create-branch`

**Request:**
```json
{
  "repo": "my-app",
  "src_branch": "main",
  "dest_branch": "feature/new-feature"
}
```

**Response:**
```json
{
  "success": true,
  "repository": "my-app",
  "source_branch": "main",
  "destination_branch": "feature/new-feature",
  "message": "Branch 'feature/new-feature' created successfully",
  "branch_url": "https://bitbucket.org/org/my-app/branch/feature/new-feature"
}
```

**cURL Example:**
```bash
curl -X POST http://localhost:8080/v1/gitops/create-branch \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "my-app",
    "src_branch": "main",
    "dest_branch": "feature/new-feature"
  }'
```

#### 2. Update Image in YAML

**Endpoint:** `POST /v1/gitops/set-image-yaml`

**Request:**
```json
{
  "repo": "my-app",
  "refs": "develop",
  "yaml_path": "k8s/deployment.yaml",
  "image": "myregistry/myapp:v1.2.3",
  "dry_run": false
}
```

**Response:**
```json
{
  "success": true,
  "repository": "my-app",
  "branch": "develop",
  "yaml_path": "k8s/deployment.yaml",
  "image": "myregistry/myapp:v1.2.3",
  "message": "Image updated to myregistry/myapp:v1.2.3 and pushed to develop",
  "commit": "[develop abc1234] chore: update image to myregistry/myapp:v1.2.3"
}
```

**cURL Example:**
```bash
curl -X POST http://localhost:8080/v1/gitops/set-image-yaml \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "my-app",
    "refs": "develop",
    "yaml_path": "k8s/deployment.yaml",
    "image": "myregistry/myapp:v1.2.3",
    "dry_run": false
  }'
```

#### 3. Create Pull Request

**Endpoint:** `POST /v1/gitops/pull-request`

**Request:**
```json
{
  "repo": "my-app",
  "src_branch": "feature/new-feature",
  "dest_branch": "develop",
  "delete_after_merge": false
}
```

**Response:**
```json
{
  "success": true,
  "repository": "my-app",
  "source": "feature/new-feature",
  "destination": "develop",
  "delete_after_merge": false,
  "pr_id": 42,
  "pr_url": "https://bitbucket.org/org/my-app/pull-requests/42",
  "message": "Pull request #42 created successfully"
}
```

**cURL Example:**
```bash
curl -X POST http://localhost:8080/v1/gitops/pull-request \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "my-app",
    "src_branch": "feature/new-feature",
    "dest_branch": "develop",
    "delete_after_merge": false
  }'
```

#### 4. Merge Pull Request

**Endpoint:** `POST /v1/gitops/merge`

**Request:**
```json
{
  "pr_url": "https://bitbucket.org/org/my-app/pull-requests/42",
  "delete_after_merge": false
}
```

**Response:**
```json
{
  "success": true,
  "pr_url": "https://bitbucket.org/org/my-app/pull-requests/42",
  "repository": "my-app",
  "pr_id": "42",
  "source": "feature/new-feature",
  "destination": "develop",
  "message": "Pull request #42 merged successfully",
  "merge_commit": "abc1234",
  "delete_after_merge": false
}
```

**cURL Example:**
```bash
curl -X POST http://localhost:8080/v1/gitops/merge \
  -H "Content-Type: application/json" \
  -d '{
    "pr_url": "https://bitbucket.org/org/my-app/pull-requests/42",
    "delete_after_merge": false
  }'
```

### API Documentation

When the server is running, visit:

- **Swagger UI**: `http://localhost:8080/docs`
- **ReDoc**: `http://localhost:8080/redoc`

## Use Cases

### CI/CD Integration

**Update image after Docker build:**

```bash
# Build Docker image
docker build -t myregistry/myapp:${VERSION} .
docker push myregistry/myapp:${VERSION}

# Update Kubernetes deployment
ngen-gitops set-image-yaml my-app develop k8s/deployment.yaml myregistry/myapp:${VERSION}
```

**Automated PR workflow:**

```bash
# Create feature branch
ngen-gitops create-branch my-app develop feature/auto-update-${VERSION}

# Update image in feature branch
ngen-gitops set-image-yaml my-app feature/auto-update-${VERSION} k8s/deployment.yaml myregistry/myapp:${VERSION}

# Create pull request
PR_URL=$(ngen-gitops pull-request my-app feature/auto-update-${VERSION} develop --delete-after-merge --json | jq -r '.pr_url')

# Auto-merge (optional)
ngen-gitops merge $PR_URL
```

### REST API Integration

**Python example:**

```python
import requests

# Create branch
response = requests.post('http://localhost:8080/v1/gitops/create-branch', json={
    'repo': 'my-app',
    'src_branch': 'main',
    'dest_branch': 'feature/new-feature'
})
print(response.json())

# Update image
response = requests.post('http://localhost:8080/v1/gitops/set-image-yaml', json={
    'repo': 'my-app',
    'refs': 'develop',
    'yaml_path': 'k8s/deployment.yaml',
    'image': 'myapp:v1.0.0',
    'dry_run': False
})
print(response.json())
```

## Configuration

### Config File Location

`~/.ngen-gitops/config.json`

### Config Structure

```json
{
  "bitbucket": {
    "username": "your-bitbucket-username",
    "app_password": "your-app-password",
    "organization": "your-org-name"
  },
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  }
}
```

### Environment Variables

Override config with environment variables:

- `BITBUCKET_USER`: Bitbucket username
- `BITBUCKET_APP_PASSWORD`: Bitbucket app password
- `BITBUCKET_ORG`: Bitbucket organization

## Development

### Build from Source

```bash
# Clone repository
git clone https://github.com/mamatnurahmat/ngen-gitops.git
cd ngen-gitops

# Install in development mode
pip install -e .

# Run commands
ngen-gitops --help
```

### Build Package

```bash
# Install build tools
pip install build twine

# Build package
python -m build

# Check distribution
twine check dist/*
```

### Publish to PyPI

```bash
# Publish to TestPyPI first
twine upload --repository testpypi dist/*

# Test installation
pip install --index-url https://test.pypi.org/simple/ ngen-gitops

# Publish to PyPI
twine upload dist/*
```

## Troubleshooting

### Authentication Errors

**Problem:** `Bitbucket credentials not configured`

**Solution:**
1. Check config file exists: `~/.ngen-gitops/config.json`
2. Verify credentials are set correctly
3. Or set environment variables: `BITBUCKET_USER` and `BITBUCKET_APP_PASSWORD`

### Branch Not Found

**Problem:** `Source branch 'xyz' not found`

**Solution:**
1. Verify branch name is correct (case-sensitive)
2. Check branch exists in Bitbucket repository
3. Use `git branch -a` to list all branches

### Image Update Fails

**Problem:** `File 'k8s/deployment.yaml' not found`

**Solution:**
1. Verify YAML path is correct relative to repository root
2. Check file exists in the specified branch
3. Ensure YAML file contains `image:` field

## License

MIT License - see LICENSE file for details

## Contributing

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

## Author

ngen-gitops contributors

## Related Projects

- [ngen-j](https://github.com/mamatnurahmat/ngen-j) - Jenkins API management CLI

## Links

- **GitHub**: https://github.com/mamatnurahmat/ngen-gitops
- **PyPI**: https://pypi.org/project/ngen-gitops/
- **Issues**: https://github.com/mamatnurahmat/ngen-gitops/issues
