volt/docs/gitops.md

# Volt GitOps

Volt includes built-in GitOps pipelines that automatically deploy workloads when code is pushed to a Git repository. No external CI/CD system required — Volt handles the entire flow from webhook to deployment.

## Overview

A GitOps pipeline links a Git repository branch to a Volt workload. When a push is detected on the tracked branch:

1. **Webhook received** — GitHub, GitLab, or Bitbucket sends a push event (or SVN revision changes are detected via polling)
2. **Validate** — The webhook signature is verified against the configured HMAC secret
3. **Clone** — The repository is cloned (or pulled if already cached)
4. **Detect** — Volt looks for `volt-manifest.yaml` or `Voltfile` in the repo root
5. **Deploy** — The workload is updated according to the manifest
6. **Log** — The result (success or failure) is recorded in the deploy history

```
┌──────────┐    push     ┌──────────────┐   clone    ┌──────────┐   deploy   ┌──────────┐
│  GitHub  │───────────→ │ Volt GitOps  │──────────→ │   Repo   │──────────→ │ Workload │
│  GitLab  │  webhook    │   Server     │            │ (cached) │            │          │
│Bitbucket │             │  :9090       │            └──────────┘            └──────────┘
│   SVN    │  polling    │              │
└──────────┘             └──────────────┘
```

## Supported Providers

| Provider | Method | Signature Validation |
|----------|--------|---------------------|
| GitHub | Webhook (`POST /hooks/github`) | HMAC-SHA256 (`X-Hub-Signature-256`) |
| GitLab | Webhook (`POST /hooks/gitlab`) | Secret token (`X-Gitlab-Token`) |
| Bitbucket | Webhook (`POST /hooks/bitbucket`) | HMAC-SHA256 |
| SVN | Polling (configurable interval) | N/A |

## Quick Start

### 1. Create a Pipeline

```bash
volt gitops create \
  --name web-app \
  --repo https://github.com/myorg/myapp \
  --provider github \
  --branch main \
  --workload web \
  --secret my-webhook-secret
```

### 2. Start the Webhook Server

```bash
# Foreground (for testing)
volt gitops serve --port 9090

# Or install as a systemd service (production)
sudo volt gitops install-service
sudo systemctl enable --now volt-gitops.service
```

### 3. Configure Your Git Provider

Add a webhook in your repository settings:

**GitHub:**
- Payload URL: `https://your-server:9090/hooks/github`
- Content type: `application/json`
- Secret: `my-webhook-secret` (must match `--secret`)
- Events: "Just the push event"

**GitLab:**
- URL: `https://your-server:9090/hooks/gitlab`
- Secret token: `my-webhook-secret`
- Trigger: Push events

**Bitbucket:**
- URL: `https://your-server:9090/hooks/bitbucket`
- Events: Repository push

### 4. Push and Deploy

Push to your tracked branch. The pipeline will automatically detect the push, clone the repo, and deploy the workload.

```bash
# Check pipeline status
volt gitops status

# View deploy history
volt gitops logs --name web-app
```

## Creating Pipelines

### GitHub

```bash
volt gitops create \
  --name web-app \
  --repo https://github.com/myorg/myapp \
  --provider github \
  --branch main \
  --workload web \
  --secret my-webhook-secret
```

The `--secret` flag sets the HMAC secret used to validate webhook signatures. This ensures only authentic GitHub push events trigger deployments.

### GitLab

```bash
volt gitops create \
  --name api \
  --repo https://gitlab.com/myorg/api \
  --provider gitlab \
  --branch develop \
  --workload api-svc \
  --secret my-gitlab-secret
```

### Bitbucket

```bash
volt gitops create \
  --name frontend \
  --repo https://bitbucket.org/myorg/frontend \
  --provider bitbucket \
  --branch main \
  --workload frontend-app \
  --secret my-bitbucket-secret
```

### SVN (Polling)

For SVN repositories, Volt polls for revision changes instead of using webhooks:

```bash
volt gitops create \
  --name legacy-app \
  --repo svn://svn.example.com/trunk \
  --provider svn \
  --branch trunk \
  --workload legacy-app \
  --poll-interval 60
```

The `--poll-interval` flag sets how often (in seconds) Volt checks for new SVN revisions. Default: 60 seconds.

## Repository Structure

Volt looks for deployment configuration in the repository root:

```
myapp/
├── volt-manifest.yaml    # Preferred — workload manifest
├── Voltfile              # Alternative — Voltfile format
├── volt-compose.yaml     # Alternative — Constellation definition
├── src/
└── ...
```

The lookup order is:
1. `volt-manifest.yaml`
2. `Voltfile`
3. `volt-compose.yaml`

## Pipeline Management

### List Pipelines

```bash
volt gitops list
volt gitops list -o json
```

### Check Status

```bash
volt gitops status
```

Output:
```
NAME        REPO                                   BRANCH   PROVIDER   LAST DEPLOY    STATUS
web-app     https://github.com/myorg/myapp         main     github     2m ago         success
api         https://gitlab.com/myorg/api            develop  gitlab     1h ago         success
legacy      svn://svn.example.com/trunk             trunk    svn        5m ago         failed
```

### Manual Sync

Trigger a deployment manually without waiting for a webhook:

```bash
volt gitops sync --name web-app
```

This is useful for:
- Initial deployment
- Re-deploying after a failed webhook
- Testing the pipeline

### View Deploy History

```bash
volt gitops logs --name web-app
volt gitops logs --name web-app --limit 50
```

Output:
```
TIMESTAMP              COMMIT       BRANCH   STATUS    DURATION   NOTES
2025-07-14 15:30:01    abc1234      main     success   12s        webhook (github)
2025-07-14 14:15:22    def5678      main     success   8s         manual sync
2025-07-14 10:00:03    789abcd      main     failed    3s         Voltfile parse error
```

### Delete a Pipeline

```bash
volt gitops delete --name web-app
```

## Webhook Server

### Foreground Mode

For testing or development:

```bash
volt gitops serve --port 9090
```

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/hooks/github` | GitHub push webhooks |
| `POST` | `/hooks/gitlab` | GitLab push webhooks |
| `POST` | `/hooks/bitbucket` | Bitbucket push webhooks |
| `GET` | `/healthz` | Health check |

### Production Deployment (systemd)

Install the webhook server as a systemd service for production use:

```bash
# Install the service unit
sudo volt gitops install-service

# Enable and start
sudo systemctl enable --now volt-gitops.service

# Check status
systemctl status volt-gitops.service

# View logs
journalctl -u volt-gitops.service -f
```

The installed service runs the webhook server on port 9090 by default. To customize, edit the service:

```bash
volt service edit volt-gitops
```

## Security

### Webhook Signature Validation

Always configure a webhook secret (`--secret`) for GitHub and Bitbucket pipelines. Without a secret, any HTTP POST to the webhook endpoint could trigger a deployment.

**GitHub** — Volt validates the `X-Hub-Signature-256` header against the configured HMAC-SHA256 secret.

**GitLab** — Volt validates the `X-Gitlab-Token` header against the configured secret.

**Bitbucket** — Volt validates the HMAC-SHA256 signature.

If signature validation fails, the webhook is rejected with `403 Forbidden` and no deployment occurs.

### Network Security

In production, place the webhook server behind the Volt ingress proxy with TLS:

```bash
volt ingress create --name gitops-webhook \
  --hostname webhooks.example.com \
  --path /hooks \
  --backend localhost:9090 \
  --tls auto
```

## Troubleshooting

### Webhook Not Triggering

1. Check the webhook server is running:
   ```bash
   volt gitops status
   systemctl status volt-gitops.service
   ```

2. Check the pipeline exists:
   ```bash
   volt gitops list
   ```

3. Verify the webhook URL is correct in your Git provider settings

4. Check the webhook secret matches

5. Check deploy logs for errors:
   ```bash
   volt gitops logs --name <pipeline>
   ```

### Deploy Fails After Webhook

1. Check the deploy logs:
   ```bash
   volt gitops logs --name <pipeline>
   ```

2. Verify the repo contains a valid `volt-manifest.yaml` or `Voltfile`

3. Try a manual sync to see detailed error output:
   ```bash
   volt gitops sync --name <pipeline>
   ```

## See Also

- [CLI Reference — GitOps Commands](cli-reference.md#volt-gitops--gitops-pipelines)
- [Architecture — GitOps Pipeline](architecture.md#gitops-pipeline)
- [Compose / Voltfile Format](compose.md)
- [Ingress Proxy](networking.md#ingress-proxy)