GitLab Components Runbook

Separation of Duties: See Separation of Duties - gitlab_components is responsible for CI/CD components. It does NOT own agent manifests, execution, or OSSA spec.

Vast.ai Integration: See BULLETPROOF_VASTAI_PLAN.md - Vast.ai deploy component with Tailscale + Cloudflare Tunnel integration.

Overview

• Purpose: Reusable GitLab CI/CD components library providing 60+ production-ready pipeline components for npm, Drupal, AI/ML projects with OSSA compliance. Includes golden workflows, git-flow automation, security scanning, and deployment strategies.
• Port: N/A (CI/CD components, optional MCP server on 3012)
• Health endpoint: N/A (pipeline validation via CI)
• Namespace: N/A (GitLab CI/CD catalog)
• Technology: YAML templates, Node.js/TypeScript for MCP server

Dependencies

• GitLab CI/CD Runner
• Node.js >= 18.0.0 (for MCP server and tooling)
• Docker (for container-based jobs)
• Kubernetes (for deployment components)
• semantic-release (for versioning)

Core Components

Common Issues

Issue 1: Component Include Failure

• Symptoms:

  • "Component not found" error in pipeline
  • "Invalid component reference" messages
  • Pipeline fails at validation stage

• Cause:

  • Incorrect component path or version
  • Component registry not accessible
  • Version mismatch

• Resolution:

  # Verify component reference format
  include:
    # Correct format:
    - component: gitlab.com/blueflyio/agent-platform/gitlab_components/workflow/golden@0.1.32
      inputs:
        node_version: '20'
    
    # NOT:
    - component: gitlab.com/blueflyio/gitlab_components/workflow/golden  # Missing version

  # Check component catalog
  curl https://gitlab.com/api/v4/projects/blueflyio%2Fagent-platform%2Fgitlab_components/releases
  
  # Verify component exists
  curl https://gitlab.com/blueflyio/agent-platform/gitlab_components/-/raw/main/templates/workflow/golden/template.yml
  
  # Check current version
  cat package.json | jq '.version'

Issue 2: Golden Workflow Test Failures

• Symptoms:

  • Tests passing locally but failing in CI
  • Coverage threshold not met
  • Test timeout errors

• Cause:

  • Different Node.js version
  • Missing environment variables
  • Resource constraints

• Resolution:

  # Specify correct inputs
  include:
    - component: gitlab.com/blueflyio/agent-platform/gitlab_components/workflow/golden@0.1.32
      inputs:
        node_version: '20'
        test_coverage_threshold: 70  # Lower if needed
        enable_comprehensive_testing: true

  # Check runner resources
  cat .gitlab-ci.yml | grep -A5 "tags:"
  
  # Add timeout extension
  variables:
    TEST_TIMEOUT: "300s"
  
  # Verify Node.js version in pipeline
  node --version
  npm --version

Issue 3: Git-Flow Branch Strategy Issues

• Symptoms:

  • Auto-merge not working
  • Tags not being created
  • Release branches not detected

• Cause:

  • Branch protection rules conflict
  • Missing merge permissions
  • Incorrect branch naming

• Resolution:

  # Correct git-flow configuration
  include:
    - component: gitlab.com/blueflyio/agent-platform/gitlab_components/workflow/git-flow@0.1.32
      inputs:
        component_version: '0.1.32'
        project_version: '1.0.0'
        project_type: 'npm'
        enable_auto_merge: true

  # Verify branch naming
  git branch --list | grep -E "^(feature/|bugfix/|hotfix/|release/)"
  
  # Check protected branch settings in GitLab UI
  # Settings > Repository > Protected branches
  
  # Verify CI/CD permissions
  # Settings > CI/CD > General pipelines > Token access

Issue 4: Security Scan False Positives/Failures

• Symptoms:

  • Pipeline blocked by security findings
  • False positive vulnerabilities
  • Secret detection flagging non-secrets

• Cause:

  • Overly strict scan configuration
  • Test fixtures being scanned
  • Known vulnerabilities not excluded

• Resolution:

  # Configure security scanning
  include:
    - component: gitlab.com/blueflyio/agent-platform/gitlab_components/security/ultimate-scanning@0.1.32
      inputs:
        enable_sast: true
        enable_secret_detection: true
        fail_on_critical: false  # Set to true in production
  
  # Add exclusions for false positives
  variables:
    SECRET_DETECTION_EXCLUDED_PATHS: "tests/fixtures/,examples/"
    SAST_EXCLUDED_PATHS: "node_modules/,dist/"

  # Review security report
  cat gl-sast-report.json | jq '.vulnerabilities[]'
  
  # Add to vulnerability allowlist (in GitLab UI)
  # Security & Compliance > Vulnerability Report > Create exclusion

Issue 5: Deployment Component Failures

• Symptoms:

  • Kubernetes deployment failing
  • Review apps not created
  • Terraform apply errors

• Cause:

  • Missing credentials/tokens
  • Cluster unreachable
  • Resource quotas exceeded

• Resolution:

  # Verify deployment configuration
  include:
    - component: gitlab.com/blueflyio/agent-platform/gitlab_components/deployment/review-apps@0.1.32
      inputs:
        review_app_domain: "review.example.com"
        ttl_days: 7
        cleanup_on_merge: true

  # Check Kubernetes connectivity
  kubectl cluster-info
  
  # Verify GitLab agent registration
  kubectl get gitlabagent -A
  
  # Check CI/CD variables
  # Settings > CI/CD > Variables
  # Required: KUBE_CONFIG, REVIEW_APP_DOMAIN
  
  # Check resource quotas
  kubectl describe quota -n review-apps

Issue 6: OSSA Validation Failures

• Symptoms:

  • "OSSA validation failed" in pipeline
  • Schema validation errors
  • Missing required fields

• Cause:

  • Manifest not compliant with OSSA v0.1.9
  • Missing security metadata
  • Invalid capability definitions

• Resolution:

  # Configure OSSA validation
  include:
    - component: gitlab.com/blueflyio/agent-platform/gitlab_components/policies/ossa-validate@0.1.32
      inputs:
        version: '0.1.9'
        strict_mode: true
        security_threshold: 9.0

  # Validate manifest locally
  buildkit ossa:validate
  
  # Check manifest structure
  cat .ossa/manifest.json | jq '.version, .capabilities'
  
  # Run compliance check
  npm run ossa:compliance
  
  # Fix common issues
  buildkit ossa:fix --auto

Issue 7: MCP Server Connection Issues

• Symptoms:
  • Claude Desktop cannot connect to GitLab MCP
  • Tool calls failing
  • "Server not responding" errors
• Cause:
  • MCP server not running
  • Configuration mismatch
  • Network issues
• Resolution:

  # Build and start MCP server
  npm run build
  npm run mcp:start
  
  # Check MCP configuration in Claude Desktop
  cat ~/.config/claude/claude_desktop_config.json | jq '.mcpServers["gitlab-components"]'
  
  # Test MCP server
  echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/mcp-server.js
  
  # Fix Claude configuration
  npm run fix:mcp
  npm run restore:claude

Pipeline Stages

All components use these standard stages:

stages:
  - validate    # Syntax and structure validation
  - test        # Component testing
  - publish     # Documentation generation
  - release     # Semantic versioning
  - deploy      # Catalog publishing

Restart Procedure

MCP Server Restart

# Stop MCP server
pkill -f "mcp-server" || true

# Rebuild
npm run build

# Start MCP server
npm run mcp:start

# Verify health
curl http://localhost:3012/health

Development Mode

# Start in watch mode
npm run dev

# Run with auto-reload
ts-node-dev --respawn --transpile-only src/mcp-server.ts

Deploy Components

# Deploy swarm (if using agent swarm)
npm run swarm:deploy

# Deploy pipeline automation
npm run pipeline:deploy

# Deploy to development
npm run deploy:dev

# Deploy to production
npm run deploy:prod

Logs Location

CI/CD Pipeline Logs

# View pipeline logs in GitLab UI
# CI/CD > Pipelines > Select pipeline > View jobs

# Download job artifacts
curl --header "PRIVATE-TOKEN: $(cat ~/.tokens/gitlab)" \
  "https://gitlab.com/api/v4/projects/{project_id}/jobs/{job_id}/artifacts" \
  --output artifacts.zip

# View job trace
curl --header "PRIVATE-TOKEN: $(cat ~/.tokens/gitlab)" \
  "https://gitlab.com/api/v4/projects/{project_id}/jobs/{job_id}/trace"

MCP Server Logs

# Console output
npm run mcp:start 2>&1 | tee mcp-server.log

# Docker logs (if containerized)
docker logs gitlab-components-mcp

# Filter errors
grep -i error mcp-server.log

Component Validation Logs

# Validate CI configuration
gitlab-ci-lint .gitlab-ci.yml

# Validate all templates
npm run validate:ci:all

# View validation output
ts-node scripts/validate-ci-pre-commit.ts 2>&1

Version Management

Check Version

# Current version
cat package.json | jq '.version'

# Check sync status
npm run version:check

# Available releases
curl https://gitlab.com/api/v4/projects/blueflyio%2Fagent-platform%2Fgitlab_components/releases | jq '.[].tag_name'

Create Release

# Dry run release
npm run release:dry

# Create release
npm run release

# Sync versions across ecosystem
npm run sync:versions

Alerts

Critical Alerts (PagerDuty)

Warning Alerts (Slack)

Monitoring

Component Usage

# Check component adoption
curl --header "PRIVATE-TOKEN: $(cat ~/.tokens/gitlab)" \
  "https://gitlab.com/api/v4/projects/blueflyio%2Fagent-platform%2Fgitlab_components/ci/catalog/components/usage"

Pipeline Metrics

# View pipeline analytics
# GitLab UI: Analytics > CI/CD Analytics

# Export metrics
curl --header "PRIVATE-TOKEN: $(cat ~/.tokens/gitlab)" \
  "https://gitlab.com/api/v4/projects/{project_id}/pipelines?per_page=100" | \
  jq '[.[] | {status, created_at, duration}]'

Merge Settings Management

Configure Merge Settings

# View help
npm run merge-settings:help

# Dry run (preview changes)
npm run merge-settings:dry-run

# Apply to pilot projects
npm run merge-settings:pilot

# Apply to all projects
npm run merge-settings:apply

# Generate documentation
npm run merge-settings:docs

# Sync to wiki
npm run merge-settings:wiki

# Audit report
npm run merge-settings:audit

Contacts

• On-call: PagerDuty rotation
• Slack: #platform-incidents, #cicd-support
• Owner: Platform Team
• Repository: https://gitlab.com/blueflyio/agent-platform/gitlab_components
• Catalog: https://gitlab.com/explore/catalog/blueflyio

Related Runbooks

• Agent BuildKit Runbook - CLI tools
• Workflow Engine Runbook - Workflow execution
• Agent Mesh Runbook - Agent coordination

Quick Reference

Include Component

include:
  - component: gitlab.com/blueflyio/agent-platform/gitlab_components/{category}/{name}@{version}
    inputs:
      key: value

Common Component Paths