How to Connect to GitLab Server (On-Premise)

This guide will help you connect your GitLab on-premise server to Apideck's Unified API. GitLab Server allows you to manage projects, issues, groups, and other resources through the GitLab API. Through this integration, you can programmatically access your GitLab data including projects, issues, groups, and project members.

Prerequisites

Before you begin, make sure you have:

• Access to your GitLab on-premise server instance
• A GitLab user account with appropriate permissions
• Admin or maintainer access to the group you want to connect

Configuration Settings

To connect your GitLab Server instance to Apideck, you'll need to provide three pieces of information:

1. Server Base URL - The URL where your GitLab instance is hosted
2. Personal Access Token (PAT) - An API token for authentication
3. Group ID - The ID of the group you want to access

Step 1: Find Your Server Base URL

The Server Base URL is the URL via which users access your GitLab server. This is typically the same URL you use to log into GitLab in your web browser.

1. Open your GitLab instance in a web browser
2. Look at the URL in your browser's address bar
3. Copy the base URL - this should be in the format: https://gitlab.mycompany.com

Important Notes:

• Always include the protocol (https:// or http://)
• Do not include any path after the domain (e.g., /users/sign_in)
• If your GitLab instance uses a custom port, include it: https://gitlab.mycompany.com:8443
• Make sure your instance has a valid SSL/TLS certificate if using https://

Example Server Base URLs:

• https://gitlab.mycompany.com
• https://gitlab.internal.company.com
• http://gitlab.local:8080 (if using HTTP and custom port)

Step 2: Create a Personal Access Token (PAT)

Personal Access Tokens (PATs) are used to authenticate API requests to your GitLab instance. You'll need to create a token with the api scope to allow full API access.

1. Log in to your GitLab instance with your user account
2. Click your profile picture at the top right corner of the page
3. Select "Preferences"

4. In the left sidebar, look for "Personal Access Tokens" and click on "Add new token"

5. Enter a token name - Choose a descriptive name like "Apideck Integration" or "API Access Token"
6. Set an expiration date (optional but recommended) - Select when the token should expire for security purposes
7. Select the required scopes - Check the api scope to grant full API access (read and write)
8. Click "Create personal access token"

9. Copy the token value that appears on the screen - ⚠️ Important: GitLab will display the token only once. You must copy it immediately and store it securely.

Step 3: Find Your Group ID

The Group ID can be either a numeric identifier or the group's path/name. GitLab accepts both formats. You can find it using one of the following methods:

Method 1: From the Group Page (Recommended)

1. Navigate to your GitLab group by clicking on it from the dashboard or groups list
2. Look at the URL in your browser's address bar
3. The Group ID may appear in the URL, or you can find it by:
   • Clicking the Actions menu (three dots or ellipsis icon) in the upper-right corner of the group page
   • Selecting "Copy Group ID" if available in your GitLab version

Method 2: From the Group URL

You can find the group identifier directly in the URL:

• If you see a URL like: https://gitlab.mycompany.com/groups/my-group-name - you can use my-group-name as the Group ID
• Or: https://gitlab.mycompany.com/-/g/123 (where 123 is the numeric Group ID) - you can use 123 as the Group ID

Note: GitLab accepts both the numeric ID (e.g., 122352741) and the group path/name (e.g., Apideck-group) as valid Group ID values.

Step 3: Configure in Apideck Vault

Now that you have all three required pieces of information, you're ready to connect your GitLab Server instance to Apideck.

Enter Your Configuration Settings

1. Navigate to the Apideck Vault and find the GitLab Server connector

2. Enter the following settings:

   • Server Base Url: Enter your GitLab server base URL (e.g., https://gitlab.mycompany.com)
   • Personal Access Token (PAT): Paste the personal access token you created in Step 2
   • Group ID: Enter the Group ID you found in Step 3 (can be numeric like 122352741 or the group path/name like Apideck-group)

3. Click Save settings to save your configuration and establish the connection

• Once connected, you can start using the integration to access your GitLab data

Troubleshooting

Error: Invalid Server Base URL

If you receive an error about the server base URL:

• Verify that the URL includes the protocol (https:// or http://)
• Ensure there are no trailing slashes in the URL
• Check that the URL is accessible from your network
• Verify that your GitLab instance is running and accessible

Error: Authentication Failed

If you receive an authentication error:

• Verify that your Personal Access Token is correct and hasn't expired
• Ensure the token has the api scope enabled
• Check that the token hasn't been revoked in GitLab
• Try creating a new token if the issue persists

Error: Group Not Found

If you receive an error about the group:

• Verify that the Group ID is correct (can be numeric like 122352741 or the group path/name like Apideck-group)
• Ensure you have access permissions to the specified group
• Check that the group exists and is accessible with your user account
• If using a group path/name, ensure it matches exactly (case-sensitive) and doesn't include special characters that need URL encoding
• Try using the API method to verify the Group ID or try the alternative format (numeric ID vs group path)

Error: Connection Timeout

If the connection times out:

• Verify that your GitLab server is accessible from the network where Apideck is running
• Check firewall rules to ensure API access is allowed
• Verify that your GitLab instance is not behind a VPN or private network that blocks external access
• Contact your GitLab administrator to verify network connectivity