vm-core/docs/GITLAB-CONSOLE-SETUP.md

GitLab → Console Integration Setup

This guide walks through wiring a real GitLab project to VaultMesh Console.

Prerequisites

1. VaultMesh Console HTTP bridge running:

   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:

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:

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:

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

   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:

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