Initialize repository snapshot

docs/GITLAB-CONSOLE-SETUP.md

@@ -0,0 +1,155 @@
+# GitLab → Console Integration Setup
+
+This guide walks through wiring a real GitLab project to VaultMesh Console.
+
+## Prerequisites
+
+1. **VaultMesh Console HTTP bridge running**:
+   ```bash
+   cd /root/work/vaultmesh
+   python3 scripts/console_receipts_server.py &
+   ```
+
+2. **Network access** from GitLab runners to your Console bridge
+   - If runners can't reach your host directly, expose via Tailscale/ngrok/etc.
+
+## Step 1: GitLab CI/CD Variables
+
+In your GitLab project: **Settings → CI/CD → Variables**
+
+| Variable | Value | Example |
+|----------|-------|---------|
+| `VAULTMESH_CONSOLE_BASE` | Console bridge URL | `http://your-host:9110/v1/console` |
+| `VAULTMESH_CALLER_DID` | GitLab service DID | `did:vm:service:gitlab-ci` |
+| `VAULTMESH_APPROVER_DID` | Default approver | `did:vm:human:karol` |
+| `VM_ENV` | Environment | `dev`, `staging`, or `prod` |
+
+## Step 2: Add Helper Script
+
+Copy `scripts/gitlab_console_session.sh` to your repository:
+
+```bash
+cp scripts/gitlab_console_session.sh /path/to/your/repo/scripts/
+chmod +x /path/to/your/repo/scripts/gitlab_console_session.sh
+git add scripts/gitlab_console_session.sh
+git commit -m "Add VaultMesh Console helper"
+```
+
+## Step 3: Update .gitlab-ci.yml
+
+Add Console session jobs to your pipeline:
+
+```yaml
+stages:
+  - console
+  - build
+  - test
+  - deploy
+  - console-end
+
+# Session start (first job)
+console:session-start:
+  stage: console
+  script:
+    - ./scripts/gitlab_console_session.sh start
+
+# Your existing jobs...
+build:
+  stage: build
+  script:
+    - ./scripts/gitlab_console_session.sh cmd build 0
+    - make build  # your actual build
+
+test:
+  stage: test
+  script:
+    - ./scripts/gitlab_console_session.sh cmd test 0
+    - make test  # your actual tests
+
+# Gated deploy
+deploy:prod:
+  stage: deploy
+  when: manual
+  script:
+    - ./scripts/gitlab_console_session.sh request_approval deploy_prod
+    # If we get here, approval was already granted
+    - ./scripts/deploy.sh prod
+
+# Session end (always runs)
+console:session-end:
+  stage: console-end
+  when: always
+  script:
+    - ./scripts/gitlab_console_session.sh end
+```
+
+## Step 4: (Optional) GitLab Webhooks
+
+For richer event tracking (MRs, pushes), add a webhook:
+
+**GitLab → Settings → Webhooks**
+
+- URL: `http://your-host:9110/gitlab/webhook`
+- Triggers: Push events, Merge request events, Pipeline events
+
+## Step 5: Verify
+
+Run a pipeline and check Console:
+
+```bash
+# List sessions
+vm console sessions
+
+# See pipeline story
+vm console story gitlab-pipeline-<id>
+
+# Check dashboard
+open http://127.0.0.1:9110/console/dashboard
+```
+
+## Approval Flow
+
+When a deploy job requests approval:
+
+1. Job calls `request_approval deploy_prod`
+2. Job fails with approval ID
+3. You approve:
+   ```bash
+   export VAULTMESH_ACTOR_DID="did:vm:human:karol"
+   vm console approvals
+   vm console approve approval-XXXX --reason "Deploy approved"
+   ```
+4. Retry the deploy job in GitLab UI
+
+## Environment-Based Policies
+
+Set `VM_ENV` per job or globally:
+
+| Environment | Requires Approval For |
+|-------------|----------------------|
+| `dev` | `git_force_push`, `rm -rf` |
+| `staging` | Above + `deploy_staging`, `db:migrate` |
+| `prod` | Above + `deploy_prod`, `docker push`, everything dangerous |
+
+Override per-job:
+```yaml
+deploy:staging:
+  variables:
+    VM_ENV: staging
+  script:
+    - ./scripts/gitlab_console_session.sh request_approval deploy_staging
+```
+
+## Troubleshooting
+
+**Bridge unreachable from runner**:
+- Check firewall rules
+- Try `curl $VAULTMESH_CONSOLE_BASE/health` from runner
+
+**Approvals not working**:
+- Verify `VAULTMESH_APPROVER_DID` matches your actor DID
+- Check `vm console approvals` shows the pending request
+
+**Dashboard not updating**:
+- Bridge may need restart after code changes
+- Check `/tmp/console_bridge.log` for errors