Deployment - AI Agent Instructions

Quick reference for AI agents working with deployment infrastructure

🤖 Deployment - AI Agent Instructions

Quick reference for AI agents working with deployment infrastructure

🎯 Key Concepts

Two Separate Pipelines

  1. Internal Services → Railway (our backend APIs)
  2. User Platforms → GitLab CI + Cloudflare Pages (generated client apps)

These are completely separate systems - don't confuse them!

📁 Documentation Structure

docs/english/Deployment/
├── README.md                    # Start here - overview
├── AGENTS.md                    # This file
├── Internal/
│   └── Railway/
│       └── README.md            # Railway deployment guide
├── Platform-Users/
│   ├── README.md                # User pipeline overview
│   ├── GitLab/
│   │   └── README.md            # GitLab integration
│   └── Cloudflare/
│       └── README.md            # Cloudflare Pages
└── Reference/
    ├── quick-commands.md        # Copy-paste commands
    ├── environment-variables.md # All env vars
    └── e2e-testing.md           # Pipeline testing

⚡ Quick Commands

# Test infrastructure connections
yarn test:gitlab
yarn test:cloudflare
yarn e2e:pipeline

# Deploy internal services
yarn railway:deploy:backend
yarn railway:deploy:ai
yarn railway:deploy:all

# Health checks
curl https://api.gograb.space/api/health
curl https://ai-api.gograb.space/ai-api/health

🔑 Credentials

Located in .env.local (never commit):

GITLAB_URL=https://gitlab.com
GITLAB_API_TOKEN=glpat-xxxxx
CLOUDFLARE_ACCOUNT_ID=xxxxx
CLOUDFLARE_API_TOKEN=xxxxx

📋 Decision Log (Session 64)

Decision Choice Confidence
Deployment architecture Separate pipelines: Railway internal, GitLab+CF users 95%
User platform pipeline GitLab CI → Cloudflare Pages 95%
Pipeline verification E2E tests against real infrastructure 95%
Railway deployment Dedicated deploy branches per service 95%
Credential management .env.local + env-loader.js 95%

🔗 Key Files

File Purpose
apis/backend-ai-api/src/app/workflow/services/git-sync.service.ts Pushes to GitLab
apis/backend-ai-api/src/app/workflow/generators/gitlab-ci-generator.service.ts Generates CI config
apis/backend-api/src/app/git-provider/gitlab-provider.service.ts GitLab API client
apis/backend-ai-api/src/app/workflow/tests/pipeline-e2e.spec.ts E2E tests
tools/scripts/test-gitlab-connection.js Connection test
tools/scripts/test-cloudflare-connection.js Connection test

⚠️ Important Notes

  1. GitLab Identity Verification: Required for CI pipelines. Do once at https://gitlab.com/-/identity_verification

  2. Never use direct deploy to bypass CI - It's only for emergencies

  3. Railway uses deploy branches - Don't expect auto-deploy from main

  4. E2E tests clean up automatically - Test resources are deleted after runs

🆘 Troubleshooting Quick Reference

Issue Fix
GitLab 403 Forbidden Token lacks permissions or identity not verified
Pipeline not triggering Complete GitLab identity verification
Cloudflare 404 Project doesn't exist - create first
Railway 502 Check health endpoint and logs
CORS errors Add origin to ALLOWED_ORIGINS

Full Documentation: Deployment README