GitLab Self-Hosting

Self-Hosted GitLab Integration Guide

Connect your self-hosted GitLab instance to Entelligence for intelligent, automated code reviews while maintaining complete control over your code and infrastructure. This comprehensive guide covers both the setup process and the login procedure to get you started quickly.

Prerequisites Setup

Before connecting to Entelligence, you'll need to configure your GitLab instance with the necessary OAuth applications and user accounts.

Step 1: Create an OAuth Application

OAuth applications allow Entelligence to authenticate with your GitLab instance securely.

  1. Access Application Settings
    • Log in to your GitLab instance with an administrator account
    • Navigate to User Settings > Applications (from the top-right user menu)
    • Click Add new application
  2. Configure Application Details
    • Name: Enter "EntelligenceAI" (or your preferred name)
    • Redirect URI: https://www.entelligence.ai/api/auth/callback/your-org-name
    • Confidential: Check this box for secure server applications
  3. Select Required Scopes
    • api — Complete read/write access to the API
    • read_api — Read access to the API
    • read_user — Read-only access to user profile information
    • read_repository — Read-only access to repositories
    • profile — Read-only access to user profile data
    • email — Read-only access to primary email address
    • write_repository — Read-write access to repositories
  4. Save and Record Credentials
    • Click Save application
    • Copy the Client ID and Client Secret immediately — the secret is only shown once

If you lose the Client Secret, you'll need to regenerate it by editing the application

Step 2: Create a Service User

Create a dedicated user account for the Entelligence integration:

  1. Create New User
    • Navigate to Admin Area > Users (wrench icon in top menu)
    • Click New user
    • Fill in details:
      • Name: A descriptive name (e.g., "Entelligence-AI")
      • Username: A unique username (e.g., "entelligence-ai")
      • Email: Valid email address
      • Access level: Regular (usually sufficient)
    • Click Create user
  2. Configure User Account
    • Set or reset the password if needed
    • Confirm the email address
    • Assign to relevant groups and projects

Best Practice: Use a dedicated service account rather than personal accounts for clearer permission management and continuity.

Step 3: Generate Personal Access Token

Create a Personal Access Token (PAT) for API authentication:

  1. Impersonate the Service User (if needed)
    • As admin, go to Admin Area > Users
    • Find the service user and click Impersonate
  2. Create Access Token
    • Navigate to User Settings > Access Tokens
    • Configure token details:
      • Token name: A descriptive name (e.g., "entelligence_bot")
      • Expiration date: Set appropriate date or leave blank
      • Select all required scopes:
        • api, read_api, read_user, read_repository, profile, email, write_repository
    • Click Create personal access token
    • Copy the token immediately — it's only shown once

Step 4: Find User ID

To locate the User ID:

  1. In Admin Area > Users, click on the user
  2. The User ID is displayed in the account information section (labeled as "ID:")
  3. Record this numeric ID for the connection process

Connecting to Entelligence

Once your GitLab instance is configured, follow these steps to establish the connection:

Step 1: Access the Login Screen

Navigate to Entelligence and access the Self-Hosted GitLab Login screen.

Don't have a self-hosted GitLab instance? Click the Sign in link at the bottom of the login screen to use other authentication methods.

Step 2: Enter GitLab Instance URL

  1. Enter your complete GitLab instance URL (e.g., https://gitlab.yourcompany.com)
  2. Click the Search button

Note: Include the full URL with https:// prefix for proper connection.

Step 3: Complete Connection Form

After searching, you'll see the detailed connection form:

Fill in the required information:

GitLab Connection

  • Hosted GitLab URL: Auto-populated from Step 2, or enter your complete GitLab instance URL
  • Organization Name: Your organization's name as it appears in GitLab

User Information

  • User ID: Numeric ID of the service user (from prerequisites)
  • Access Token: Personal access token (format example: glpat-12345678)

OAuth App

  • Pre-configured section — no additional input needed

Step 4: Establish Connection

  1. Click Connect GitLab
  2. Wait for connection establishment
  3. Upon success, you'll be redirected to the Entelligence dashboard

Required Information Checklist

Ensure you have all the following before starting the connection process:

  • ✅ GitLab Instance URL: Base URL of your GitLab instance
  • ✅ Organization Name: Your organization's name in GitLab
  • ✅ User ID: Numeric ID of the service user
  • ✅ Access Token: PAT with all required scopes
  • ✅ OAuth Client ID: From the OAuth application
  • ✅ OAuth Client Secret: From the OAuth application (keep secure)

Troubleshooting

Common Connection Issues

"Your organization is not registered with us"

  • This message is normal for first-time setup
  • Complete the form with all required information to register

Authorization Errors

  • Verify all required scopes are selected for both OAuth app and PAT
  • Confirm the callback URL matches exactly: https://www.entelligence.ai/api/auth/callback/your-org-name

Connection Failures

  • Ensure GitLab instance is accessible from the internet
  • Verify URL format includes https://
  • Check that User ID and Access Token are correct
  • Confirm GitLab instance is running and healthy

Permission Denied

  • Ensure service user has appropriate repository access
  • Check group and project permissions
  • Verify token hasn't expired

Token Management

Token Expiration

  • Check expiration dates and regenerate as needed
  • Set calendar reminders for token renewal

Invalid Redirect URI

  • Callback URL must exactly match Entelligence specifications
  • Check for typos or missing URL components

Security Best Practices

  • Dedicated Service Accounts: Use dedicated users rather than personal accounts
  • Principle of Least Privilege: Grant only necessary scopes and permissions
  • Secure Credential Storage: Never commit secrets to version control
  • Regular Token Rotation: Implement periodic token renewal
  • Audit Logging: Monitor impersonation and admin actions
  • Network Security: Ensure GitLab instance has appropriate firewall rules

Getting Help

If you encounter issues not covered in this guide:

  1. Check the GitLab documentation for your specific version
  2. Contact your GitLab administrator
  3. Reach out to Entelligence support with specific error messages and screenshots at support@entelligence.ai or Discord (opens in a new tab)

Summary

Self-Hosted GitLab Integration provides secure, controlled access to Entelligence's intelligent code review capabilities while keeping your code and infrastructure under your complete control. By following this comprehensive setup process, you'll have a robust, secure integration that enhances your development workflow with AI-powered code reviews.

The integration maintains your existing security policies while adding powerful automation that learns from your team's coding standards and review practices, ultimately improving code quality and accelerating development velocity.

Other IntegrationsAWS Marketplace Deployment Guide