156 lines
3.7 KiB
Markdown
156 lines
3.7 KiB
Markdown
# 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
|