Skip to main content

GitLab Integration

Connect your GitLab repositories to ArchiCore for automatic analysis.

Features​

  • Self-hosted support — Connect gitlab.com or your own GitLab instance
  • Multiple instances — Connect several GitLab servers simultaneously
  • Private repositories — Full access to private projects
  • Branch selection — Choose which branch to analyze
  • Auto-analysis — Automatic analysis on push events
  • Merge Request reviews — AI-powered code reviews on MRs

Setup​

Step 1: Create a Personal Access Token​

  1. Go to your GitLab → Settings → Access Tokens
  2. Create a new token with these required scopes:
    • api — Required for full API access (private repositories, webhooks, MR comments)
    • read_repository — Required for reading repository content
Required Scopes

For private repositories, the api scope is mandatory. Without it, ArchiCore cannot access private projects even if you're the repository owner or admin.

  1. Copy the token (you won't see it again!)

Step 2: Connect GitLab Instance​

Via Web Interface:

  1. Go to ArchiCore → Settings → Integrations
  2. Click Add GitLab
  3. Enter your GitLab URL (e.g., https://gitlab.com or https://gitlab.company.com)
  4. Paste your Personal Access Token
  5. Click Connect

Via API:

curl -X POST https://api.archicore.io/api/gitlab/instances \
  -H "Authorization: Bearer YOUR_ARCHICORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceUrl": "https://gitlab.company.com",
    "accessToken": "YOUR_GITLAB_PAT",
    "name": "Company GitLab"
  }'

Step 3: Connect a Repository​

  1. After connecting your GitLab instance, click Add Project
  2. Select the GitLab instance
  3. Browse or search for your repository
  4. Select a branch
  5. Click Connect

Self-Hosted GitLab​

ArchiCore fully supports self-hosted GitLab instances.

SSL Certificates​

If your GitLab uses a self-signed certificate:

  1. When connecting, enable "Allow self-signed certificates"
  2. Or set rejectUnauthorizedSSL: false in the API call

Network Access​

For webhooks to work, your GitLab instance must be able to reach ArchiCore's webhook endpoint:

https://api.archicore.io/api/gitlab/webhook

If ArchiCore is also self-hosted, configure GITLAB_WEBHOOK_URL in your environment.

Multiple Instances​

You can connect multiple GitLab instances:

  • gitlab.com (public)
  • gitlab.company.com (corporate)
  • gitlab.client.com (client projects)

Each instance is managed separately with its own credentials.

Webhooks​

ArchiCore can automatically create webhooks for:

  • Push events — Trigger analysis when code is pushed
  • Merge Request events — Add AI review comments to MRs

Webhook Setup​

Webhooks are created automatically when you connect a repository with "Auto-analyze" enabled.

Manual webhook configuration:

  1. Go to your GitLab project → Settings → Webhooks
  2. Add URL: https://api.archicore.io/api/gitlab/webhook
  3. Secret Token: (provided by ArchiCore)
  4. Enable: Push events, Merge request events

API Reference​

List Instances​

GET /api/gitlab/instances

Add Instance​

POST /api/gitlab/instances
Content-Type: application/json

{
  "instanceUrl": "https://gitlab.company.com",
  "accessToken": "glpat-xxxxxxxxxxxx",
  "name": "My GitLab",
  "rejectUnauthorizedSSL": true
}

List Projects​

GET /api/gitlab/instances/{instanceId}/projects?search=myproject

List Branches​

GET /api/gitlab/instances/{instanceId}/projects/{projectId}/branches

Connect Repository​

POST /api/gitlab/repositories/connect
Content-Type: application/json

{
  "instanceId": "uuid",
  "projectId": 123,
  "autoAnalyze": true,
  "analyzeMRs": true,
  "branch": "main"
}

Disconnect Repository​

DELETE /api/gitlab/repositories/{repoId}

Troubleshooting​

"Invalid token"​

  • Check expiration — Ensure your PAT hasn't expired
  • Verify scopes — The token must have api and read_repository scopes
  • Check URL — For self-hosted GitLab, ensure the URL is correct (include https://)
  • Regenerate token — If issues persist, create a new token with the correct scopes

"SSL certificate error"​

  • Enable "Allow self-signed certificates" when connecting
  • Or add your CA certificate to the system trust store

"Webhook not receiving events"​

  • Verify your GitLab can reach the webhook URL
  • Check GitLab → Project → Settings → Webhooks → Recent deliveries
  • Ensure the webhook secret matches

"Repository not found"​

  • Check token scopes — For private repositories, your PAT must have the api scope. The read_api scope alone is not sufficient.
  • Verify token permissions — Even if you're a repository admin or owner, an improperly scoped token cannot access private projects.
  • Enter the full path — When connecting, use the full repository path (e.g., group/subgroup/project-name), not just the project name.
  • Check if the repository is archived — Archived repositories may not appear in search results.
  • Ensure correct GitLab instance — Make sure you're looking at the correct GitLab server (gitlab.com vs self-hosted).