Connecting GitLab
Connect your GitLab repositories to Gitar
GitLab repositories can be connected to Gitar using two methods: OAuth authentication or manual setup with personal access tokens via service accounts.
Connection Methods
OAuth
Quick and secure one-click connection through our secure API endpoint.
- →Automatic authorization flow
- →Seamless repository access
- →No manual token management
Manual (Service Account User)
Advanced configuration for custom GitLab instances and specific access control.
- →Custom GitLab hostnames
- →Specific group/namespace targeting
- →Project-level access control
Setup Instructions
OAuth Connection
The OAuth method provides the simplest setup experience. When you click Connect GitLab, you'll be:
- 1Redirected through our secure API endpoint
- 2Taken to GitLab for authorization
- 3Brought back to complete the integration
- 4Automatically set up with your repositories
Manual (Service Account User)
For custom GitLab instances or when you need more control over the connection, use manual setup. First, create a service account and generate a Service Account Personal Access Token:
Step 1: Create a Service Account
Create a dedicated service account for Gitar integration to maintain security and isolation:
- 1Go to your GitLab instance admin area
- 2Create a new user account (e.g., "gitar-service")
- 3Grant appropriate permissions to repositories
Step 2: Generate Personal Access Token
Generate a Personal Access Token with the required scopes for the service account:
- 1Log in as the service account
- 2Go to User Settings → Access Tokens
- 3Click "Add New Token"
- 4Enter token name and set expiration
Step 3: Provide required scopes
Required Scopes Selection
Select the following scopes for Gitar integration:
read_userRequired for user authentication and OAuth integration with Gitar
read_repositoryAllows Gitar to read repository contents, branches, and metadata
read_apiEnables reading GitLab API data for project information and settings
write_repositoryRequired for creating pull requests and pushing code changes
apiEnables automatic webhook setup and project discovery
Click "Create personal access token" to generate the token
Save the generated token securely - you won't be able to see it again
Step 4: Add Service Account to Projects
Before configuring the connection, you must add the service account as a member to each project that you want to enable with Gitar. The service account requires Maintainer role or higher to configure webhook events for Gitar's merge requests, including CI logs and ingesting conversations made with Gitar.
- 1Navigate to your GitLab project
- 2Go to Settings → Members
- 3Click "Invite members"
- 4Search for your service account user
- 5Assign Maintainer role or higher
Important Note
You must add the service account to each project individually that you want to enable with Gitar. Projects where the service account is not a member will not be available for selection in the final configuration step.
Step 5: Configure Connection
Use the generated token to configure the connection with the following fields:
GitLab Host
The hostname of your GitLab instance (e.g., gitlab.com, gitlab.example.com)
Group/Namespace Path
The group or namespace path (e.g., "gitarcode" for gitlab.com/gitarcode)
Project ID (Optional)
Find your project ID in GitLab project settings
Personal Access Token
Token needs 'read_user', 'read_repository', 'read_api', 'write_repository', 'api' scopes
Configure Repository Access
After connecting GitLab, you can configure which repositories should receive Gitar webhook notifications.
Repository Configuration
Click the Configure button for GitLab to select which repositories you want to enable for webhook notifications.
