Skip to main content
For what differs between this platform and the others, see Platform Support.
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 Self-Managed 18.11 or later on any tier, or GitLab Premium or Ultimate on version 16.0 or later. Gitar authenticates as a service account, and service accounts became available on Free with 18.11.
  • 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.
Gitar registers a webhook on each project as you connect it, on every tier, and never on the group. A project webhook carries every event Gitar consumes and needs only the Maintainer role. One consequence: connect projects you add later from the project browser, since a per-project webhook cannot cover a project that does not exist yet.

​
Setup Instructions

1

Create a service account

  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-<org-name>, for example 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.
2

Generate a service account token

  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, as 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:
3

Invite the service account to your group

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
Maintainer is enough for the webhooks, the reviews, and the fix branches Gitar pushes. Owner adds one thing: reading the group’s merge request approval settings, which is how Gitar tells whether your instance enforces approval rules before it holds a merge with one.At Maintainer that read is refused, so Gitar treats merge blocking as unavailable and says so on the connection.
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. Inviting it to a subgroup gives it no access to the parent.
4

Connect in Gitar

Use the generated token to configure the connection with the following fields:
  • GitLab Host: The hostname of your GitLab instance, for example gitlab.com or gitlab.example.com
  • Group/Namespace Path: The full path of the group, including any parent groups. 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.

​
Merge Blocking

When Gitar’s review finds unresolved blocking findings, it creates a merge-request approval rule requiring its own approval, which GitLab enforces on the merge button. Approval rules are enforced on Premium and Ultimate only. An instance without them accepts the rule and then ignores it, so Gitar checks which kind of instance yours is when you connect and on every refresh. Where rules are not enforced, Gitar skips the rule and does not claim a block that is not there. The connection in Settings → Configuration → Connections says merge blocking is unavailable. Reviews and findings are unaffected. To gate merges without approval rules, add a job that calls the merge-request status endpoint and fails when Gitar reports the merge request as blocked. See Get MR Status for the endpoint and an example job.

​
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 as the committer email when pushing changes, including fix requests and automated commits. If this email is not allowed, Gitar cannot push and those operations 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:
  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 Add noreply@gitar.ai to the Gitar service account in GitLab as one of its verified emails.

​
Firewall / IP Allowlisting

If your GitLab group or instance enforces an IP allowlist, add every address listed in Network Access, including the IPv6 range. GitLab.com supports IPv6, so adding only the IPv4 addresses can leave project access and webhook registration blocked. After changing the allowlist, open Settings → Configuration in Gitar and click Refresh in the Repositories card to retry webhook registration.

​
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.