> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# GitLab
> Connect your GitLab repositories to Gitar
export const ThemeImage = ({src, alt}) => {
let lightSrc, darkSrc;
if (src.includes("-light.")) {
lightSrc = src;
darkSrc = src.replace("-light.", "-dark.");
} else if (src.includes("-dark.")) {
darkSrc = src;
lightSrc = src.replace("-dark.", "-light.");
} else {
lightSrc = src;
darkSrc = src;
}
return
;
};
Gitar connects to GitLab using a **service account** and a **service account token**. You create the service account in your group, generate a token for it, then invite it to the group you want Gitar to work in.
## Prerequisites
* GitLab Premium or Ultimate. Service accounts are available on every tier, but Gitar registers a group webhook during setup and GitLab does not offer group webhooks on Free.
* The Owner role on the group where you create the service account. On GitLab Self-Managed and Dedicated, group Owners must also be allowed to create service accounts, otherwise an administrator has to create the account for you.
## Setup Instructions
1. Go to your group in GitLab
2. On the left sidebar, select **Settings → Service accounts**
3. Select **Add service account**
4. Enter a name and username, then select **Create**
Service account usernames must be globally unique across GitLab, so use a naming convention like `gitar-service-` (e.g., `gitar-service-acme`).
A service account can only be invited to the group or project that created it, and to anything beneath it. Creating the account in your **top-level group** keeps every subgroup and project available to you, including any you decide to connect later.
In GitLab 18.11 and later, subgroups and projects can create their own service accounts, but those accounts are confined to that subgroup or project. On earlier versions, only top-level groups and instance administrators can create them.
On GitLab Self-Managed and Dedicated, an administrator can instead create an instance service account from the Admin area, which can be invited to any group on the instance.
1. Select the vertical ellipsis (**⋮**) next to your new service account, then select **Manage access tokens**
2. Select **Add new token**
3. Enter a token name and set an expiration date — note this date so you can rotate the token before it expires
4. Select the scopes listed below, then select **Generate token**
5. Copy the token immediately — GitLab will not show it again
A service account token is generated from the service account's **Manage access tokens** page, not from a user's profile settings. Gitar rejects personal access tokens and group or project access tokens during validation, so make sure you generate the token from the service account itself.
Required scopes:
* `read_user` - Required for user authentication and integration with Gitar
* `read_repository` - Allows Gitar to read repository contents, branches, and metadata
* `read_api` - Enables reading GitLab API data for project information and settings
* `write_repository` - Required for creating pull requests and pushing code changes
* `api` - Enables automatic webhook setup and project discovery
Creating the service account does not give it access to anything. Invite it to the group you want Gitar to work in:
1. Go to that group in GitLab
2. On the left sidebar, select **Manage → Members**
3. Select **Invite members**
4. Search for your service account, assign the **Owner** role, then select **Invite**
Gitar needs the Owner role because it creates a group webhook during setup, and GitLab only permits webhook management for group Owners. Maintainer is enough for project webhooks but not for group webhooks.
If your organization cannot grant Owner to a service account, GitLab Ultimate customers can assign a custom role instead. Custom roles support the **Manage web hooks** (`admin_web_hook`) permission in GitLab 17.0 and later, which you can add to a lower base role such as Maintainer.
Invite the service account to the group whose path you enter in the next step. Membership inherits downwards, so inviting it to a parent group also covers every subgroup and project beneath it — but inviting it to a subgroup gives it no access to the parent.
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 full path of the group, including any parent groups (e.g., `acme` for gitlab.com/acme, or `acme/platform` for a subgroup)
* **Project ID (Optional)**: Find your project ID in GitLab project settings
* **Service Account Token**: The token you generated above, with all the scopes listed
Gitar validates the token as you enter it and reports any problem with the host, the token, or access to the group.
You can update the group, token, or other connection settings after onboarding by going to **Settings → Configuration** in your Gitar dashboard.
## Configure Repository Access
After connecting GitLab, you can configure which repositories should receive Gitar webhook notifications.
Select the **Configure** button for GitLab, then choose individual projects or whole groups to connect. You can search by project name or paste a full project path for a direct lookup.
## Self-Hosted GitLab: Git Hooks Configuration
If your self-hosted GitLab instance uses server-side git hooks to validate committer emails (push rules or custom hooks), you must allow Gitar's committer email address.
Gitar uses **[noreply@gitar.ai](mailto:noreply@gitar.ai)** as the committer email when pushing changes (e.g., fix requests, automated commits). If this email is not allowed, Gitar will be unable to push changes and operations will fail.
### Adding the Gitar Committer Email
Depending on your GitLab configuration, add `noreply@gitar.ai` to your allowed committer list:
**Option 1: GitLab Push Rules (Recommended)**
1. Go to **Admin Area → Push Rules** (for instance-wide rules) or **Project Settings → Repository → Push Rules** (for project-specific rules)
2. In the "Commit author's email" field, add a regex pattern that includes Gitar's email:
```
@yourcompany\.com$|^noreply@gitar\.ai$
```
3. Save the push rules
**Option 2: Custom Server-Side Hooks**
If you use custom `pre-receive` or `update` hooks that validate committer emails, add `noreply@gitar.ai` to your allowed email list in the hook script.
**Option 3: Service Account Email Configuration**
Alternatively, ensure the Gitar service account in GitLab has `noreply@gitar.ai` configured as one of its verified emails.
### Firewall / IP Allowlisting
If your GitLab instance enforces an IP allowlist, add Gitar's public IP addresses to it. See [Network Access](/connecting-code/network-access) for the addresses and details.
## Troubleshooting
**"The group or namespace was not found"**
Gitar could not read the group with the token you supplied. GitLab returns the same response whether the group does not exist or the token cannot see it, so check both:
* The path is the group's **full path**, including any parent groups. A subgroup is `parent-group/subgroup`, not `subgroup`.
* The service account is a member of that group or of one of its parent groups. Creating the account inside a group grants it no access on its own — only an invitation does.
**"Personal access tokens are not supported" or "Group or project access tokens are not supported"**
The token was not generated from a service account. Go to **Settings → Service accounts**, select the vertical ellipsis (**⋮**) next to the account, and generate a token from **Manage access tokens**.