> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

GitLab integration troubleshooting

Answers to common bugs and edge cases when using the GitLab Ocean integration.

Why are projects not visible after setting up a group access token?​

Answer (click to expand)

After creating a GitLab group access token and installing the integration, fewer projects appear than expected or none at all.

Cause: Group access tokens have scope-based visibility. A token created without the read_api scope, or created at the wrong group level, will return an empty or partial project list without error.

Fix:

  1. Verify the token has read_api scope (minimum required).
  2. Verify the token is created at the top-level group, not a subgroup, if you want to ingest projects across the full group hierarchy.
  3. If you only see projects from one subgroup, the token is scoped to that subgroup only.

What are common GitLab integration version compatibility issues?​

Answer (click to expand)

When upgrading a self-hosted GitLab integration, breaking changes between minor versions can cause silent failures or incomplete syncs. Always check the integration's changelog before upgrading.

Common version-specific issues:

  • v0.6.1: Missing ref parameter causes file-kind mapping failures. Upgrade to v0.6.3 or later.
  • v2 sandbox: Integration may fail in sandbox environments due to stricter SSL verification defaults. Set SSL_VERIFY=false in the integration config for non-production environments only.