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

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

# 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.

# Check pipeline status
volt gitops status

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

Creating Pipelines

GitHub

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

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

Bitbucket

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:

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

volt gitops list
volt gitops list -o json

Check Status

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:

volt gitops sync --name web-app

This is useful for:

• Initial deployment
• Re-deploying after a failed webhook
• Testing the pipeline

View Deploy History

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

volt gitops delete --name web-app

Webhook Server

Foreground Mode

For testing or development:

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:

# 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:

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:

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:

   volt gitops status
   systemctl status volt-gitops.service
   

2. Check the pipeline exists:

   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:

   volt gitops logs --name <pipeline>
   

Deploy Fails After Webhook

1. Check the deploy logs:

   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:

   volt gitops sync --name <pipeline>
   

See Also

• CLI Reference — GitOps Commands
• Architecture — GitOps Pipeline
• Compose / Voltfile Format
• Ingress Proxy