# 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