GitLab Integration for Ambient Code Platform

Ambient Code Platform now supports GitLab repositories alongside GitHub, enabling you to use your GitLab projects with AgenticSessions. This guide covers everything you need to know about using GitLab with Ambient Code Platform.

Overview

What's Supported:

✅ GitLab.com (public SaaS)
✅ Self-hosted GitLab instances (Community & Enterprise editions)
✅ Personal Access Token (PAT) authentication
✅ HTTPS and SSH URL formats
✅ Public and private repositories
✅ Clone, commit, and push operations
✅ Multi-repository projects (mix GitHub and GitLab)

Requirements:

GitLab Personal Access Token with appropriate scopes
Repository with write access (for AgenticSessions)
Ambient Code Platform backend v1.1.0 or higher

Quick Start

1. Create GitLab Personal Access Token

Log in to GitLab: https://gitlab.com (or your self-hosted instance)
Navigate to Access Tokens:
- Click your profile icon (top right)
- Select "Preferences" → "Access Tokens"
- Or visit: https://gitlab.com/-/profile/personal_access_tokens
Create Token:
- Token name: Ambient Code Platform Integration
- Expiration: Set 90+ days from now
- Select scopes:
  - ✅ api - Full API access (required)
  - ✅ read_api - Read API access
  - ✅ read_user - Read user information
  - ✅ write_repository - Push to repositories
Copy Token: Save the token starting with glpat-... securely

Detailed instructions: See GitLab PAT Setup Guide

2. Connect GitLab Account to Ambient Code Platform

Via Ambient Code Platform UI (if available):

Navigate to Settings → Integrations
Click "Connect GitLab"
Paste your Personal Access Token
(Optional) For self-hosted: Enter instance URL (e.g., https://gitlab.company.com)
Click "Connect"

Via API:

curl -X POST http://vteam-backend:8080/api/auth/gitlab/connect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-acp-auth-token>" \
  -d '{
    "personalAccessToken": "glpat-your-token-here",
    "instanceUrl": ""
  }'

For self-hosted GitLab, include the instance URL:

{
  "personalAccessToken": "glpat-your-token-here",
  "instanceUrl": "https://gitlab.company.com"
}

Success Response:

{
  "userId": "user-123",
  "gitlabUserId": "456789",
  "username": "yourname",
  "instanceUrl": "https://gitlab.com",
  "connected": true,
  "message": "GitLab account connected successfully"
}

3. Configure Project with GitLab Repository

Option A: Via Ambient Code Platform UI

Open your Ambient Code Platform project
Navigate to Project Settings
Under "Repositories", click "Add Repository"
Enter GitLab repository URL:
- HTTPS: https://gitlab.com/owner/repo.git
- SSH: git@gitlab.com:owner/repo.git
Enter default branch (e.g., main)
Save settings

Option B: Via Kubernetes

Edit your ProjectSettings custom resource:

kubectl edit projectsettings -n <your-project-namespace>

Add GitLab repository to spec:

apiVersion: ambient-code.io/v1
kind: ProjectSettings
metadata:
  name: projectsettings
  namespace: my-project
spec:
  repositories:
    - url: "https://gitlab.com/myteam/myrepo.git"
      branch: "main"
      provider: "gitlab"  # Auto-detected, optional

Multiple Repositories (GitHub + GitLab):

spec:
  repositories:
    - url: "https://github.com/myteam/frontend.git"
      branch: "main"
    - url: "https://gitlab.com/myteam/backend.git"
      branch: "develop"

4. Create AgenticSession with GitLab Repository

Once your GitLab account is connected and repository configured, create sessions normally:

Example AgenticSession CR:

apiVersion: ambient-code.io/v1alpha1
kind: AgenticSession
metadata:
  name: add-feature-x
  namespace: my-project
spec:
  description: "Add feature X to the backend service"
  outputRepo:
    url: "https://gitlab.com/myteam/backend.git"
    branch: "feature/add-feature-x"

What Happens:

Session pod starts with your task description
Repository clones using your GitLab PAT (automatic authentication)
Claude Code agent makes changes
Changes committed to local repository
Branch pushed to GitLab with your commits
Completion notification includes GitLab branch link

Completion Notification:

AgenticSession completed successfully!

View changes in GitLab:
https://gitlab.com/myteam/backend/-/tree/feature/add-feature-x

Supported URL Formats

Ambient Code Platform automatically detects and normalizes GitLab URLs:

HTTPS URLs (Recommended)

✅ https://gitlab.com/owner/repo.git
✅ https://gitlab.com/owner/repo
✅ https://gitlab.company.com/group/project.git
✅ https://gitlab.company.com/group/subgroup/project.git

SSH URLs

✅ git@gitlab.com:owner/repo.git
✅ git@gitlab.company.com:group/project.git

Provider Auto-Detection:

URLs containing gitlab.com → Detected as GitLab.com
URLs containing other hosts with gitlab pattern → Detected as self-hosted GitLab
Provider field is optional in ProjectSettings (auto-detected from URL)

Repository Access Validation

Ambient Code Platform validates your access to GitLab repositories before allowing operations:

Validation Checks:

✅ Token is valid and not expired
✅ User has access to repository
✅ Token has sufficient permissions (read + write)
✅ Repository exists and is accessible

When Validation Occurs:

When connecting GitLab account (token validation)
When configuring project repository (repository access check)
Before starting AgenticSession (pre-flight validation)

Common Validation Errors:

Error	Cause	Solution
Invalid token	Token expired or revoked	Reconnect with new PAT
Insufficient permissions	Token lacks `write_repository`	Recreate token with required scopes
Repository not found	Private repo or no access	Verify URL and repository permissions
Rate limit exceeded	Too many API calls	Wait a few minutes, then retry

Managing GitLab Connection

Check Connection Status

Via API:

curl -X GET http://vteam-backend:8080/api/auth/gitlab/status \
  -H "Authorization: Bearer <your-acp-token>"

Response (Connected):

{
  "connected": true,
  "username": "yourname",
  "instanceUrl": "https://gitlab.com",
  "gitlabUserId": "456789"
}

Response (Not Connected):

{
  "connected": false
}

Disconnect GitLab Account

Via API:

curl -X POST http://vteam-backend:8080/api/auth/gitlab/disconnect \
  -H "Authorization: Bearer <your-acp-token>"

This removes:

Your GitLab PAT from Ambient Code Platform secrets
Connection metadata
Access to GitLab repositories (AgenticSessions will fail)

Note: Your repositories and GitLab account are not affected.

Update GitLab Token

To update your token (when expired or scopes changed):

Disconnect current account
Create new token in GitLab with updated scopes
Reconnect with new token

Self-Hosted GitLab

Ambient Code Platform fully supports self-hosted GitLab instances (Community and Enterprise editions).

Requirements

GitLab instance accessible from Ambient Code Platform backend pods
Personal Access Token from your GitLab instance
Network connectivity to GitLab API (default: port 443)

Configuration

When connecting, provide your instance URL:

curl -X POST http://vteam-backend:8080/api/auth/gitlab/connect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <acp-token>" \
  -d '{
    "personalAccessToken": "glpat-xxx",
    "instanceUrl": "https://gitlab.company.com"
  }'

Instance URL Format:

✅ Include https:// protocol
✅ No trailing slash
❌ Don't include /api/v4 path

Examples:

✅ https://gitlab.company.com
✅ https://git.myorg.io
❌ gitlab.company.com (missing protocol)
❌ https://gitlab.company.com/ (trailing slash)
❌ https://gitlab.company.com/api/v4 (includes API path)

API URL Construction

Ambient Code Platform automatically constructs the correct API URL:

Instance URL	API URL
`https://gitlab.com`	`https://gitlab.com/api/v4`
`https://gitlab.company.com`	`https://gitlab.company.com/api/v4`
`https://git.myorg.io`	`https://git.myorg.io/api/v4`

Troubleshooting Self-Hosted

Issue: Connection fails with "connection refused"

Solutions:

Verify instance URL is correct and accessible

Check network connectivity from backend pods:

kubectl exec -it <backend-pod> -n vteam-backend -- curl https://gitlab.company.com

Verify SSL certificate is valid (or configure trust for self-signed)
Check firewall rules allow traffic from Kubernetes cluster

Issue: Token validation fails

Solutions:

Verify token is from correct GitLab instance (not GitLab.com)
Check token hasn't expired
Verify admin hasn't revoked token

Test token manually:

curl -H "Authorization: Bearer glpat-xxx" \
  https://gitlab.company.com/api/v4/user

Detailed guide: See Self-Hosted GitLab Configuration

Security & Best Practices

Token Security

How Tokens Are Stored:

✅ Stored in Kubernetes Secrets (encrypted at rest)
✅ Never logged in plaintext
✅ Redacted in all log output (glpat-***)
✅ Not exposed in API responses
✅ Injected into git URLs only in memory

Token Redaction Examples:

# In logs, you'll see:
[GitLab] Using token glpat-*** for user john
[GitLab] Cloning https://oauth2:***@gitlab.com/team/repo.git

# Never:
[GitLab] Using token glpat-abc123xyz456

Token Scopes

Minimum Required Scopes:

api - Full API access
read_repository - Clone repositories
write_repository - Push changes

Recommended Scopes:

api - Covers all operations
read_api - Read-only API access
read_user - User information
write_repository - Push to repos

Avoid:

sudo - Not needed, grants excessive privileges
admin_mode - Not needed

Token Rotation

Recommendation: Rotate tokens every 90 days

Process:

Create new token in GitLab with same scopes
Test new token works (curl to GitLab API)
Disconnect Ambient Code Platform GitLab connection
Reconnect with new token
Revoke old token in GitLab

Repository Permissions

Required Permissions:

Read access for cloning
Write access for pushing changes
For private repos: Must be member with at least Developer role

GitLab Role Requirements:

Role	Can Clone	Can Push	Recommended For
Guest	❌	❌	Not supported
Reporter	✅	❌	Read-only use cases
Developer	✅	✅	✅ AgenticSessions
Maintainer	✅	✅	✅ AgenticSessions
Owner	✅	✅	✅ AgenticSessions

Troubleshooting

Connection Issues

Problem: "Invalid token" error when connecting

Solutions:

Verify token is copied correctly (no extra spaces)
Check token hasn't expired in GitLab
For self-hosted: Ensure instanceUrl is correct

Test token manually:

curl -H "Authorization: Bearer glpat-xxx" \
  https://gitlab.com/api/v4/user

Problem: "Insufficient permissions" error

Solutions:

Verify token has all required scopes:
- api ✅
- read_repository ✅
- write_repository ✅
Recreate token with correct scopes
Reconnect Ambient Code Platform with new token

Repository Configuration Issues

Problem: Provider not auto-detected

Solutions:

Verify URL contains gitlab.com or matches GitLab pattern

Manually specify provider in ProjectSettings:

spec:
  repositories:
    - url: "https://gitlab.company.com/team/repo.git"
      provider: "gitlab"

Problem: Repository validation fails

Solutions:

Check you're connected to GitLab (/auth/gitlab/status)
Verify you have access to repository (try cloning manually)
For private repos: Ensure you're a member with Developer+ role
Check repository URL is correct

AgenticSession Issues

Problem: Session fails to clone repository

Solutions:

Verify GitLab account is connected

Check token stored in secret:

kubectl get secret gitlab-user-tokens -n vteam-backend

Verify repository URL is correct

Check session logs:

kubectl logs <session-pod> -n <project-namespace>

Problem: Clone succeeds but push fails (403 Forbidden)

Solutions:

Token lacks write_repository scope → Recreate token
You don't have push access → Contact repo owner
Branch is protected → Use different branch or update protection rules

Error Message:

GitLab push failed: Insufficient permissions. Ensure your GitLab token
has 'write_repository' scope. You can update your token by reconnecting
your GitLab account with the required permissions.

Problem: Self-hosted GitLab URL not working

Solutions:

Verify instance URL format (must include https://)
Check API URL construction in logs
Test connectivity from backend pod
Verify SSL certificate is valid

Limits & Quotas

GitLab.com Rate Limits

API Rate Limits (GitLab.com):

300 requests per minute per user
10,000 requests per hour per user

How Ambient Code Platform Handles Rate Limits:

Errors returned with clear message
Recommended wait time provided
No automatic retry (to avoid making it worse)

Error Message:

GitLab API rate limit exceeded. Please wait a few minutes before
retrying. GitLab.com allows 300 requests per minute.

Self-Hosted Rate Limits

Self-hosted instances may have different limits configured by admins. Check with your GitLab administrator.

Mixing GitHub and GitLab

Ambient Code Platform supports projects with both GitHub and GitLab repositories.

Example Multi-Provider Project:

spec:
  repositories:
    - url: "https://github.com/team/frontend.git"
      branch: "main"
      provider: "github"

    - url: "https://gitlab.com/team/backend.git"
      branch: "develop"
      provider: "gitlab"

    - url: "https://gitlab.company.com/team/infrastructure.git"
      branch: "main"
      provider: "gitlab"

How It Works:

Provider auto-detected from URL
Correct authentication method used automatically:
- GitHub: Uses GitHub App or GIT_TOKEN
- GitLab: Uses GitLab PAT
Each repo operates independently
Errors are provider-specific and clear

AgenticSession with Multiple Repos:

Session can work with multiple repos in one task
Each repo cloned with appropriate authentication
Changes pushed to correct providers

API Reference

Connect GitLab Account

POST /api/auth/gitlab/connect
Content-Type: application/json
Authorization: Bearer <acp-token>

{
  "personalAccessToken": "glpat-xxx",
  "instanceUrl": "https://gitlab.com"  # Optional, defaults to gitlab.com
}

Response (200 OK):

{
  "userId": "user-123",
  "gitlabUserId": "456789",
  "username": "yourname",
  "instanceUrl": "https://gitlab.com",
  "connected": true,
  "message": "GitLab account connected successfully"
}

Get Connection Status

GET /api/auth/gitlab/status
Authorization: Bearer <acp-token>

Response (200 OK - Connected):

{
  "connected": true,
  "username": "yourname",
  "instanceUrl": "https://gitlab.com",
  "gitlabUserId": "456789"
}

Response (200 OK - Not Connected):

{
  "connected": false
}

Disconnect GitLab Account

POST /api/auth/gitlab/disconnect
Authorization: Bearer <acp-token>

Response (200 OK):

{
  "message": "GitLab account disconnected successfully",
  "connected": false
}

FAQ

Q: Can I use the same token for multiple Ambient Code Platform users? A: No. Each Ambient Code Platform user should connect their own GitLab account with their own PAT. This ensures:

Audit trail shows real user
Correct permissions enforcement
Individual token rotation

Q: What happens if my token expires? A: AgenticSessions will fail with "Authentication failed" error. Reconnect with a new token.

Q: Can I use SSH URLs? A: Yes, Ambient Code Platform accepts SSH URLs and automatically converts them to HTTPS for authentication.

Q: Do I need to configure SSH keys? A: No. Ambient Code Platform uses HTTPS + Personal Access Token authentication exclusively.

Q: Can I use Deploy Tokens instead of PATs? A: Not currently. Only Personal Access Tokens are supported.

Q: Does Ambient Code Platform support GitLab Groups/Subgroups? A: Yes. URLs like https://gitlab.com/group/subgroup/project.git work correctly.

Q: What if I don't have a GitLab account? A: Create one at https://gitlab.com - it's free for public and private repositories.

Q: Can I use Ambient Code Platform with GitLab Enterprise? A: Yes. Self-hosted GitLab Enterprise Edition is fully supported.

Q: How do I know if my token has the right scopes? A: Test it:

curl -H "Authorization: Bearer glpat-xxx" \
  https://gitlab.com/api/v4/personal_access_tokens/self

Q: Will GitHub stop working after I add GitLab? A: No. GitHub and GitLab integrations are independent and work side-by-side.

Support & Resources

Documentation:

GitLab Resources:

Troubleshooting:

Check backend logs: kubectl logs -l app=vteam-backend -n vteam-backend
Check session logs: kubectl logs <session-pod> -n <project-namespace>
Verify GitLab status: https://status.gitlab.com (for GitLab.com)

Getting Help:

Ambient Code Platform GitHub Issues: Create an issue
Ambient Code Platform Documentation: Main README

Changelog

v1.1.0 - 2025-11-05

✨ Initial GitLab integration release
✅ GitLab.com support
✅ Self-hosted GitLab support
✅ Personal Access Token authentication
✅ AgenticSession clone/commit/push operations
✅ Multi-provider support (GitHub + GitLab)

FilesExpand file tree

gitlab-integration.md

Latest commit

History

gitlab-integration.md

File metadata and controls

GitLab Integration for Ambient Code Platform

Overview

Quick Start

1. Create GitLab Personal Access Token

2. Connect GitLab Account to Ambient Code Platform

3. Configure Project with GitLab Repository

4. Create AgenticSession with GitLab Repository

Supported URL Formats

HTTPS URLs (Recommended)

SSH URLs

Repository Access Validation

Managing GitLab Connection

Check Connection Status

Disconnect GitLab Account

Update GitLab Token

Self-Hosted GitLab

Requirements

Configuration

API URL Construction

Troubleshooting Self-Hosted

Security & Best Practices

Token Security

Token Scopes

Token Rotation

Repository Permissions

Troubleshooting

Connection Issues

Repository Configuration Issues

AgenticSession Issues

Limits & Quotas

GitLab.com Rate Limits

Self-Hosted Rate Limits

Mixing GitHub and GitLab

API Reference

Connect GitLab Account

Get Connection Status

Disconnect GitLab Account

FAQ

Support & Resources

Changelog