GitLab Workspaces - Agent Deployment Guide

GitLab Workspaces: Agent Deployment Guide

Date: 2026-02-05 Purpose: Step-by-step guide for deploying agents to GitLab Workspaces

🎯 Overview

What Are GitLab Workspaces?

GitLab Workspaces provide cloud-based development and execution environments:

Remote, isolated execution spaces
Access to GitLab repositories
Configurable compute resources
NOT dependent on your local machines (M4, M3, or NAS)

URL: https://gitlab.com/groups/blueflyio/-/settings/workspaces

🏗️ Architecture

Where Agents Execute

❌ OLD (INCORRECT):
┌──────────────────────────────────────┐
│ M4 Workstation                       │
│ • Running agents locally             │ ← Ties agents to M4
│ • Must be online for agents to work  │
└──────────────────────────────────────┘

❌ OLD (INCORRECT):
┌──────────────────────────────────────┐
│ NAS (Synology)                       │
│ • Running agents on NAS              │ ← Ties agents to home network
│ • Must be online for agents to work  │
└──────────────────────────────────────┘

✅ NEW (CORRECT):
┌──────────────────────────────────────┐
│ GitLab Workspaces                    │
│ • Agents execute in cloud            │ ← Independent
│ • Always accessible                  │
│ • Not tied to M4/M3/NAS              │
└──────────────────────────────────────┘

🚀 Quick Start

Step 1: Access GitLab Workspaces

Go to: https://gitlab.com/groups/blueflyio/-/settings/workspaces
Click "New Workspace"
Configure workspace:
- Name: agent-runtime-01
- Project: Select any project (e.g., platform-agents)
- Editor: Choose "Web IDE" or "SSH"
- Resources:
  - vCPU: 2
  - Memory: 4 GB
  - Storage: 10 GB

Step 2: Deploy Agent from buildkit CLI

# On M4 or M3 workstation
cd ~/Sites/blueflyio/_CURRENT_WORK/agent-buildkit

# Deploy agent to workspace
buildkit agents deploy \
  --agent merge-request-reviewer \
  --target gitlab-workspace \
  --workspace agent-runtime-01 \
  --gitlab-token $GITLAB_TOKEN

# Expected output:
# ✓ Connecting to GitLab API
# ✓ Provisioning workspace: agent-runtime-01
# ✓ Cloning agent code from gitlab.com/blueflyio/platform-agents
# ✓ Installing dependencies
# ✓ Starting agent process
# ✓ Agent deployed successfully
#
# Workspace URL: https://gitlab.com/-/ide/project/blueflyio/platform-agents/workspaces/agent-runtime-01

Step 3: Verify Agent is Running

# Check agent status
buildkit agents status --workspace agent-runtime-01

# Expected output:
# Agent: merge-request-reviewer
# Status: RUNNING
# Workspace: agent-runtime-01
# Uptime: 5 minutes
# Last Activity: 30 seconds ago

📋 Deployment Methods

Method 1: buildkit CLI (Recommended)

# Deploy single agent
buildkit agents deploy \
  --agent merge-request-reviewer \
  --target gitlab-workspace \
  --workspace agent-runtime-01

# Deploy multiple agents
buildkit agents deploy \
  --agents merge-request-reviewer,pipeline-remediation,code-quality-reviewer \
  --target gitlab-workspace \
  --workspace agent-runtime-01

# Deploy with custom config
buildkit agents deploy \
  --agent merge-request-reviewer \
  --target gitlab-workspace \
  --workspace agent-runtime-01 \
  --config ./agent-config.yaml

Method 2: agent-studio IDE

1. Open agent-studio IDE (on M4 or M3)
2. Navigate to: Agents > Deploy
3. Select agent: "merge-request-reviewer"
4. Choose target: "GitLab Workspace"
5. Select workspace: "agent-runtime-01"
6. Click "Deploy Agent"

Behind the scenes:
- agent-studio calls buildkit API
- buildkit provisions workspace
- Agent starts in isolated environment

Method 3: Drupal UI

1. Open Drupal CMS: https://nas.blueflyagents.com
2. Navigate to: Admin > AI Agents > Deployment
3. Fill form:
   - Agent: "merge-request-reviewer"
   - Target: "GitLab Workspace"
   - Workspace: "agent-runtime-01"
4. Click "Deploy"

Behind the scenes:
- Drupal module calls buildkit API
- buildkit provisions workspace
- Agent starts in isolated environment

Method 4: AI CLI Tools

# Using Claude Code, Cursor, or other AI CLI
ai deploy agent merge-request-reviewer \
  --to gitlab-workspace \
  --workspace agent-runtime-01

# Natural language (if supported)
ai "Deploy the merge request reviewer agent to GitLab Workspace"

🔧 Configuration

Workspace Configuration (.devfile.yaml)

Each agent project should include a .devfile.yaml file:

# platform-agents/.devfile.yaml
schemaVersion: 2.2.0
metadata:
  name: platform-agents-workspace
  description: Agent execution environment

components:
  - name: agent-runtime
    container:
      image: node:20-alpine
      memoryLimit: 2Gi
      cpuLimit: 1000m

      # Environment variables
      env:
        - name: NODE_ENV
          value: "production"

        - name: AGENT_MESH_URL
          value: "https://mesh.bluefly.internal"

        - name: AGENT_BRAIN_URL
          value: "https://brain.bluefly.internal"

        - name: AGENT_PROTOCOL_URL
          value: "https://api.blueflyagents.com"

        - name: COMPLIANCE_ENGINE_URL
          value: "https://compliance.bluefly.internal"

        # Tailscale (optional - for direct NAS access)
        - name: TAILSCALE_AUTH_KEY
          value: "tskey-auth-xxxxx"  # From GitLab secrets

      # Volume mounts
      volumeMounts:
        - name: agent-storage
          path: /app/storage

  # Persistent volume for agent data
  - name: agent-storage
    volume:
      size: 5Gi

commands:
  # Install dependencies
  - id: install
    exec:
      component: agent-runtime
      commandLine: npm install
      workingDir: /projects/platform-agents

  # Start default orchestrator agent
  - id: start-orchestrator
    exec:
      component: agent-runtime
      commandLine: npm run orchestrator:start
      workingDir: /projects/platform-agents

  # Start specific agent
  - id: start-agent
    exec:
      component: agent-runtime
      commandLine: npm run agent:start -- ${AGENT_NAME}
      workingDir: /projects/platform-agents

events:
  # Run on workspace start
  preStart:
    - install

  postStart:
    - start-orchestrator

Agent Configuration (agent-config.yaml)

# agent-config.yaml
agent:
  name: merge-request-reviewer
  type: reviewer
  version: 1.0.0

execution:
  workspace: agent-runtime-01
  resources:
    cpu: 1000m
    memory: 2Gi
    storage: 5Gi

services:
  mesh:
    url: https://mesh.bluefly.internal
    token: ${GITLAB_TOKEN}

  brain:
    url: https://brain.bluefly.internal
    collection: agent-memory

  protocol:
    url: https://api.blueflyagents.com

  compliance:
    url: https://compliance.bluefly.internal

monitoring:
  enabled: true
  interval: 30s
  tracer:
    url: https://tracer.bluefly.internal

logging:
  level: info
  format: json
  output: /app/storage/logs/agent.log

buildkit Configuration

// agent-buildkit/config/workspace-targets.ts
export interface WorkspaceTarget {
  provider: 'gitlab';
  baseUrl: string;
  group: string;
  defaultWorkspace: string;
  tailscale?: {
    enabled: boolean;
    authKeySecret: string;
  };
  services: {
    mesh: string;
    brain: string;
    protocol: string;
    compliance: string;
  };
}

export const workspaceTargets: Record<string, WorkspaceTarget> = {
  'gitlab-workspace': {
    provider: 'gitlab',
    baseUrl: 'https://gitlab.com',
    group: 'blueflyio',
    defaultWorkspace: 'agent-runtime-01',

    tailscale: {
      enabled: true,
      authKeySecret: 'TAILSCALE_AUTH_KEY',
    },

    services: {
      mesh: 'https://mesh.bluefly.internal',
      brain: 'https://brain.bluefly.internal',
      protocol: 'https://api.blueflyagents.com',
      compliance: 'https://compliance.bluefly.internal',
    },
  },
};

🔐 Security & Access

Tailscale Integration (Optional)

If agents need direct access to NAS services (not via Cloudflare Tunnel):

# In workspace, install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Authenticate with Tailscale
tailscale up --auth-key=${TAILSCALE_AUTH_KEY}

# Verify connection
tailscale status

# Now agents can access:
# - agent-mesh.tailcf98b3.ts.net:3005
# - blueflynas.tailcf98b3.ts.net:5432 (PostgreSQL)
# - etc.

Note: Cloudflare Tunnel already provides public access, so Tailscale is optional.

GitLab Access Token

Agents need a GitLab token to:

Read/write to repositories
Create issues/MRs
Run CI/CD pipelines

# Create token at: https://gitlab.com/-/profile/personal_access_tokens
# Scopes: api, read_repository, write_repository

# Set as environment variable
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxx

# Or add to workspace secrets
# GitLab > Group Settings > CI/CD > Variables
# Key: GITLAB_TOKEN
# Value: glpat-xxxxxxxxxxxxx

📊 Monitoring & Debugging

Check Agent Logs

# Via buildkit CLI
buildkit agents logs --workspace agent-runtime-01 --agent merge-request-reviewer

# Via GitLab Web IDE
# 1. Go to workspace URL
# 2. Open terminal
# 3. cat /app/storage/logs/agent.log

Agent Status Dashboard

# List all workspaces
buildkit workspaces list

# Expected output:
# NAME              STATUS    AGENTS    UPTIME    LAST_ACTIVITY
# agent-runtime-01  RUNNING   3         5h 23m    2 minutes ago
# agent-runtime-02  RUNNING   2         3h 45m    5 minutes ago
# agent-dev-01      STOPPED   0         0m        N/A

Debug Agent

# SSH into workspace
buildkit workspace ssh --workspace agent-runtime-01

# Once inside:
cd /projects/platform-agents
npm run agent:debug -- merge-request-reviewer

# View environment
env | grep AGENT_

# Check service connectivity
curl -I https://mesh.bluefly.internal/health
curl -I https://brain.bluefly.internal/health

🚨 Troubleshooting

Issue: Agent Not Starting

Symptoms:

buildkit agents deploy hangs
Workspace shows "PENDING" status

Solutions:

# 1. Check workspace status
buildkit workspaces status --workspace agent-runtime-01

# 2. Check GitLab Workspace UI
# Go to: https://gitlab.com/groups/blueflyio/-/settings/workspaces
# Look for errors

# 3. Verify resources are available
# GitLab group may have resource limits

# 4. Check logs
buildkit workspaces logs --workspace agent-runtime-01

Issue: Agent Can't Connect to NAS Services

Symptoms:

Agent logs show connection errors
ECONNREFUSED errors

Solutions:

# 1. Verify Cloudflare Tunnel is running
# On NAS or GL-iNet router:
docker ps | grep cloudflared

# 2. Check service URLs
curl -I https://mesh.bluefly.internal/health
curl -I https://brain.bluefly.internal/health

# 3. Verify Tailscale (if using)
# In workspace:
tailscale status
ping blueflynas.tailcf98b3.ts.net

# 4. Check firewall rules
# Ensure NAS services allow connections from GitLab IPs

Issue: Agent Exits Immediately

Symptoms:

Agent starts but exits within seconds
No obvious errors

Solutions:

# 1. Check agent logs
buildkit agents logs --workspace agent-runtime-01 --agent merge-request-reviewer

# 2. Verify environment variables
buildkit workspace ssh --workspace agent-runtime-01
env | grep -E "AGENT_|GITLAB_"

# 3. Test manually
cd /projects/platform-agents
npm run agent:start -- merge-request-reviewer

# 4. Check for missing dependencies
npm install

📖 Examples

Example 1: Deploy Single Agent

# Deploy merge-request-reviewer
buildkit agents deploy \
  --agent merge-request-reviewer \
  --target gitlab-workspace \
  --workspace agent-runtime-01 \
  --gitlab-token $GITLAB_TOKEN

# Verify
buildkit agents status --workspace agent-runtime-01

Example 2: Deploy Multiple Agents to Same Workspace

# Deploy 3 agents to one workspace
buildkit agents deploy \
  --agents merge-request-reviewer,pipeline-remediation,code-quality-reviewer \
  --target gitlab-workspace \
  --workspace agent-runtime-01 \
  --gitlab-token $GITLAB_TOKEN

# Check status
buildkit agents list --workspace agent-runtime-01

# Expected output:
# AGENT                      STATUS    UPTIME    LAST_ACTIVITY
# merge-request-reviewer     RUNNING   10m       30s ago
# pipeline-remediation       RUNNING   10m       1m ago
# code-quality-reviewer      RUNNING   10m       45s ago

Example 3: Deploy Agent with Custom Config

# Create custom config
cat > agent-custom-config.yaml <<EOF
agent:
  name: merge-request-reviewer
  parallel: 3  # Run 3 instances in parallel

execution:
  resources:
    cpu: 2000m
    memory: 4Gi

services:
  mesh:
    url: https://mesh.bluefly.internal
    timeout: 30s
EOF

# Deploy with config
buildkit agents deploy \
  --agent merge-request-reviewer \
  --target gitlab-workspace \
  --workspace agent-runtime-01 \
  --config ./agent-custom-config.yaml

Example 4: Scale Agent (Multiple Instances)

# Scale to 5 instances
buildkit agents scale \
  --agent merge-request-reviewer \
  --workspace agent-runtime-01 \
  --replicas 5

# Check status
buildkit agents list --workspace agent-runtime-01

# Expected output:
# AGENT                         STATUS    UPTIME    LAST_ACTIVITY
# merge-request-reviewer-1      RUNNING   5m        10s ago
# merge-request-reviewer-2      RUNNING   5m        15s ago
# merge-request-reviewer-3      RUNNING   5m        8s ago
# merge-request-reviewer-4      RUNNING   5m        12s ago
# merge-request-reviewer-5      RUNNING   5m        20s ago

Example 5: Stop and Remove Agent

# Stop agent (keep workspace)
buildkit agents stop \
  --agent merge-request-reviewer \
  --workspace agent-runtime-01

# Remove agent from workspace
buildkit agents remove \
  --agent merge-request-reviewer \
  --workspace agent-runtime-01

# Delete entire workspace (including all agents)
buildkit workspaces delete --workspace agent-runtime-01

🎓 Best Practices

1. Use Dedicated Workspaces

# ✅ GOOD: Separate workspaces for different purposes
agent-runtime-01      # Production agents
agent-runtime-02      # Testing agents
agent-dev-01          # Development/debugging
agent-gpu-01          # GPU-intensive agents

2. Monitor Resource Usage

# Check workspace resource usage
buildkit workspaces metrics --workspace agent-runtime-01

# Expected output:
# WORKSPACE          CPU      MEMORY    STORAGE   AGENTS
# agent-runtime-01   45%      1.2G/4G   2.1G/10G  3

3. Regular Log Rotation

# In .devfile.yaml
commands:
  - id: rotate-logs
    exec:
      component: agent-runtime
      commandLine: |
        find /app/storage/logs -name "*.log" -mtime +7 -delete
        echo "Logs older than 7 days deleted"

4. Use Environment Secrets

# Never hardcode secrets in .devfile.yaml
# Instead, use GitLab CI/CD variables

# ❌ BAD:
env:
  - name: GITLAB_TOKEN
    value: "glpat-xxxxxxxxxxxxx"

# ✅ GOOD:
env:
  - name: GITLAB_TOKEN
    value: ${GITLAB_TOKEN}  # From GitLab secrets

5. Implement Health Checks

// In agent code
export async function healthCheck(): Promise<boolean> {
  try {
    // Check connection to agent-mesh
    await fetch('https://mesh.bluefly.internal/health');

    // Check connection to agent-brain
    await fetch('https://brain.bluefly.internal/health');

    // Check connection to compliance-engine
    await fetch('https://compliance.bluefly.internal/health');

    return true;
  } catch (error) {
    console.error('Health check failed:', error);
    return false;
  }
}

// Run health check every 30 seconds
setInterval(async () => {
  const healthy = await healthCheck();
  if (!healthy) {
    console.error('Agent is unhealthy, exiting...');
    process.exit(1);
  }
}, 30000);

📝 Checklist

Pre-Deployment

GitLab Workspace created
.devfile.yaml added to agent project
GitLab token configured (as secret)
Tailscale auth key configured (if using)
NAS services accessible (test URLs)
buildkit CLI installed and configured

Deployment

Run buildkit agents deploy command
Verify agent status
Check agent logs
Test agent functionality

Post-Deployment

Monitor resource usage
Set up log rotation
Configure alerting
Document any custom configurations

Document Version: 1.0 Last Updated: 2026-02-05 Status: PRODUCTION-READY

GitLab Workspaces - Agent Deployment Guide

GitLab Workspaces: Agent Deployment Guide

🎯 Overview

What Are GitLab Workspaces?

🏗️ Architecture

Where Agents Execute

🚀 Quick Start

Step 1: Access GitLab Workspaces

Step 2: Deploy Agent from buildkit CLI

Step 3: Verify Agent is Running

📋 Deployment Methods

Method 1: buildkit CLI (Recommended)

Method 2: agent-studio IDE

Method 3: Drupal UI

Method 4: AI CLI Tools

🔧 Configuration

Workspace Configuration (.devfile.yaml)

Agent Configuration (agent-config.yaml)

buildkit Configuration

🔐 Security & Access

Tailscale Integration (Optional)

GitLab Access Token

📊 Monitoring & Debugging

Check Agent Logs

Agent Status Dashboard

Debug Agent

🚨 Troubleshooting

Issue: Agent Not Starting

Issue: Agent Can't Connect to NAS Services

Issue: Agent Exits Immediately

📖 Examples

Example 1: Deploy Single Agent

Example 2: Deploy Multiple Agents to Same Workspace

Example 3: Deploy Agent with Custom Config

Example 4: Scale Agent (Multiple Instances)

Example 5: Stop and Remove Agent

🎓 Best Practices

1. Use Dedicated Workspaces

2. Monitor Resource Usage

3. Regular Log Rotation

4. Use Environment Secrets

5. Implement Health Checks

📝 Checklist

Pre-Deployment

Deployment

Post-Deployment

🔗 Related Resources