Gitlab

GitLab integration allows your product to connect with GitLab repositories to fetch repository metadata, create or manage issues, monitor merge requests (pull requests), and analyze commits or pipelines. This integration is essential for enabling features such as vulnerability scanning, CI/CD monitoring, code inventory, and developer collaboration within your platform.

Credentials Needed

To integrate with GitLab, you need either a Personal Access Token (PAT) or an OAuth2 Application Token (for multi-user authentication).

For Personal Access Token (Recommended for direct integrations):

• GitLab Username or Email
• Personal Access Token (PAT)

For OAuth2 Application (Recommended for multi-user or org-level integration):

• Application ID (Client ID)
• Client Secret
• Redirect URI (for callback)

Permissions Needed / API Scopes

Depending on what your integration needs to do (read repos, create issues, manage merge requests), the following scopes are required:

Functionality	Scope	Type
Read repositories and metadata	read_api	PAT / OAuth
Create or update issues	api	PAT / OAuth
Manage merge requests	api	PAT / OAuth
Read user information	read_user	PAT / OAuth
Read project webhooks	read_api	PAT / OAuth

Minimal scopes for issue/merge request access: read_api, api, read_user

Creating Users / Access Tokens

Step 1: Generate a Personal Access Token (PAT)

1. Log in to your GitLab account.
2. Go to User Settings → Access Tokens or visit:

https://gitlab.com/-/profile/personal_access_tokens

3. Enter a Token Name (e.g., GitLabIntegrationToken).
4. Set Expiration Date (optional but recommended).
5. Under Scopes, select:
   • api (full API access — required for issues, merges, and repos)
   • read_user (to read user info)
   • read_api (to read repository/project details)
6. Click Create personal access token.
7. Copy and securely store the token — it will only be shown once.

Step 2 (Optional): Create an OAuth Application

If your platform allows multiple GitLab users to integrate their accounts:

1. Go to Admin Area → Applications or User Settings → Applications (for self-managed GitLab).
2. Click New Application.
3. Fill in:
   • Name: Your product name
   • Redirect URI: The callback endpoint of your product
4. Select the scopes:
   • api
   • read_user
5. Click Save Application.
6. Copy Application ID (Client ID) and Client Secret for use in your product.

Test Connectivity

You can test GitLab connectivity using curl or any REST client:

# Replace <TOKEN> with your PAT
curl --header "PRIVATE-TOKEN: <TOKEN>" https://gitlab.com/api/v4/user

# List projects accessible by the user
curl --header "PRIVATE-TOKEN: <TOKEN>" https://gitlab.com/api/v4/projects?membership=true

# Create a test issue
curl --request POST \
     --header "PRIVATE-TOKEN: <TOKEN>" \
     --data "title=Test Issue from Integration&description=This is a test issue" \
     "https://gitlab.com/api/v4/projects/<PROJECT_ID>/issues"

If you receive valid JSON responses or a new issue is created, your credentials and permissions are correctly configured.

Save the Results in the Platform and Create Connection

1. In your product's integration configuration, securely store:
   • GITLAB_TOKEN (for PAT-based integration)
   • or CLIENT_ID, CLIENT_SECRET, REDIRECT_URI (for OAuth-based integration).
2. Create a new connector labeled GitLab Integration.
3. Test the connection by fetching repositories or creating a test issue.

Best Practices

• Use Personal Access Tokens for simple single-user integrations; use OAuth2 for multi-user setups.
• Assign only necessary scopes — avoid full sudo or admin privileges.
• Rotate tokens regularly and remove old or unused tokens.
• Store tokens securely in your platform's encrypted vault or secret manager.
• For self-hosted GitLab, replace https://gitlab.com with your instance's base URL.
• Use pagination when fetching large project lists via the GitLab API.
• Respect GitLab API rate limits and cache repository metadata when possible.