1. Introduction
Connecting GitLab On-Premise allows users to integrate their private GitLab instances with the platform to create code graphs. This functionality is especially useful for organizations that use self-managed GitLab on their own servers instead of the cloud version.
2. Prerequisites
2.1 GitLab Requirements
GitLab Version: It is recommended to use versions later than 14 to ensure compatibility with all functionalities.
API Access: The GitLab instance must have API access enabled.
GitLab URL: You will need the base URL of your GitLab On-Premise instance.
2.2 Required Permissions
To establish a connection with GitLab On-Premise, a personal access token with the following permissions is required:
api: To access the GitLab API.
read_user: To read user information.
read_repository: To access repositories.
read_api: To make API calls.
Ideally, these permissions should be granted by a user with root privileges on the GitLab instance to ensure full access to all necessary resources.
3. Creating a Personal Access Token in GitLab
To obtain the personal access token needed for the connection:
Log in to your GitLab On-Premise instance.
Go to your user profile (icon in the upper right corner).
Select "Preferences" or "Settings".
In the side menu, find and select "Access Tokens".
Create a new token with a descriptive name (e.g., "Graphs Connection").
Select the following permissions:
api
read_user
read_repository
read_api
Set an expiration date (optional, but recommended for security).
Click "Create personal access token".
IMPORTANT: Copy and save the generated token securely, as you cannot view it again.
4. Configuring the GitLab On-Premise Connection
4.1 Creating a New Connection
Access the "Connections" section on the platform.
Select "Add new connection" or a similar button.
Choose "GitLab On-Premise" as the connection type.
Complete the form with the following information:
Name: A descriptive name to identify this connection.
GitLab URL: The base URL of your GitLab On-Premise instance (e.g., https://gitlab.yourcompany.com).
Personal Access Token: The token you generated in the previous step.
Click "Create connection".
The system will store the token in an encrypted form for added security.
5. Using GitLab On-Premise to Create Graphs
Once the connection is configured, you can create graphs from repositories in your GitLab On-Premise instance:
5.1 Graph Creation Process
Navigate to the "Create Graph" section on the platform.
Select "GitLab On-Premise" as the repository source.
Select the connection you configured earlier.
The system will load the available groups and personal accounts in your GitLab instance.
Select a group or personal account.
Search and select the specific repository from which you want to create a graph.
Select the branch of the repository you want to use.
Click "Create Graph".
5.2 Data Flow
The process of creating a graph with GitLab On-Premise follows these steps:
The platform authenticates with your GitLab instance using the personal access token.
Retrieves the information of the selected repository and branch.
Initiates the graph creation process, which includes:
Cloning the repository.
Analyzing the code.
Generating documentation (if enabled).
Building the code graph.
5.3 Parameters Used
When creating a graph from GitLab On-Premise, the following parameters are used:
git_provider: 'gitlab_op' (identifier for GitLab On-Premise).
repo_org: Organization or namespace of the repository.
repo_name: Name of the repository.
branch: Selected branch.
connection_id: ID of the configured connection.
gitlab_repo_id: Numeric ID of the repository in GitLab.
generate_documentation: Boolean to enable documentation generation.
6. Technical Considerations
6.1 Security
Access tokens are stored encrypted in the database.
It is recommended to use tokens with the minimum necessary permissions.
It is advisable to set an expiration date for the tokens.
6.2 Performance
The speed of graph creation will depend on the size of the repository and the connection speed between the platform and your GitLab instance.
For very large repositories, the process may take longer.
6.3 Compatibility
It is recommended to use GitLab versions later than 14 to ensure compatibility with all API functionalities.
If you experience issues, verify that your GitLab instance has API access enabled and that the token has the correct permissions.
7. Troubleshooting
7.1 Common Issues
Authentication Error: Verify that the access token is valid and has the correct permissions.
Groups or Repositories Not Found: Ensure that the token has access to the groups and repositories you want to use.
Error Creating Graph: Verify that the selected branch exists and that the repository contains valid code.
7.2 Verifying Permissions
If you experience issues, you can verify your token's permissions:
Make a test call to the GitLab API using your token:
bashcurl -H "PRIVATE-TOKEN: your_token" https://your-gitlab.com/api/v4/projects
If the call returns a list of projects, the token has the correct basic permissions.
7.2.1 Verifying Repository Download Capability
To verify if the token has permissions to download a complete repository, you can use the following command:
bashcurl -H "PRIVATE-TOKEN: your_token" https://your-gitlab.com/api/v4/projects/PROJECT_ID/repository/archive.zip -o repo_test.zip
If the command executes successfully and downloads the repository zip file, then the token has the necessary permissions to access and download the complete repository content.
8. Best Practices
Token Security: Use a specific token for this integration and do not share it.
User Permissions: Ideally, the token should be generated by a user with root privileges to ensure access to all necessary repositories.
Regular Updates: Periodically renew the access token to maintain security.
GitLab Version: Keep your GitLab instance updated to take advantage of API and security improvements.
9. Special Considerations for GitLab On-Premise
9.1 Custom Instance Particularities
GitLab On-Premise instances may have specific configurations due to:
Customization: Each organization may have particular configurations adapted to their needs.
Modularity: Some GitLab modules or functionalities may be enabled or disabled according to the configuration.
Modified Versions: Some organizations use modified versions of GitLab with specific behaviors.
Network Configurations: Firewall restrictions, proxies, or VPNs that may affect connectivity.
Custom Security Policies: Additional restrictions implemented by the organization's security team.
9.2 Support for Specific Cases
Due to these particularities, in some specific cases the connection may present challenges not covered in this documentation. If after following all the steps and verifications you still experience issues:
Contact our support team: We can help you with specific GitLab On-Premise configurations.
Provide detailed information: When contacting support, include:
The exact version of GitLab you are using.
Any specific errors you are receiving.
Results of the permission verifications you have performed.
Details about any relevant customizations in your instance.
Our support team will work with you to resolve any specific issues related to your GitLab On-Premise instance and make sure that we successfully integrate our platform.