Skip to main content
For what differs between this platform and the others, see Platform Support.
Gitar connects to GitLab using a personal access token (PAT). A GitLab service account is the preferred way to generate this token; a dedicated user’s PAT works as a fallback, but that approach occupies a seat on your GitLab instance and its token stops working if that user ever leaves. Gitar posts comments and pushes changes under that account’s identity, so use an account reserved for Gitar.

​
Prerequisites

  • GitLab.com, or GitLab Self-Managed or Dedicated version 16.0 or later. Community Edition and GitLab Free have no service account feature and must use a dedicated user’s PAT instead.
  • A service account (preferred) or dedicated user, with access to the group and the Maintainer or Owner role on the projects being connected.
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

Choose an account

Use this path only when the instance has no Service accounts menu, since a dedicated user works without GitLab’s service account feature. Create a regular GitLab user reserved for Gitar, such as gitar-bot-acme.This approach is a fallback, not the preferred option: a dedicated user occupies a normal seat on the GitLab instance, and its PAT becomes invalid if that user’s account is ever removed or deactivated. Prefer a service account whenever your GitLab edition and version support one.Keep this account separate from daily development. Gitar treats comments from the connected account as its own and does not respond to them.
2

Generate a personal access token

For a service account, open Settings → Service accounts, then select Manage access tokens next to the account. For a dedicated user, sign in as that user and open its personal access tokens page instead.
  1. Open the account’s access token page
  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 api scope, then select Generate token
  5. Copy the token immediately, as GitLab will not show it again
Group and project access tokens are not supported. Generate the PAT from the service account (preferred) or dedicated user that Gitar will act as.
The api scope covers repository access and API reads and writes, including posting comments and setting up webhooks. Read-only scopes combined with write_repository do not permit these API writes.
3

Invite the account to your group

Invite the service account or dedicated user to the group Gitar will work in:
  1. Go to that group in GitLab
  2. On the left sidebar, select Manage → Members
  3. Select Invite members
  4. Search for the account, assign the Maintainer or Owner role, then select Invite
Maintainer is enough for project webhooks and review actions, including pushing fix branches. Merge blocking depends on GitLab’s approval-rule support, not on whether you chose a service account or a dedicated user.
Invite the 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

Create one connection per GitLab host in each Gitar organization. The same connection can cover multiple top-level groups that the connected account can access. After connecting, select those groups under Configure Repository Access.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
  • Personal Access Token: The token you generated above, with the api scope
Gitar validates the token as you enter it and reports any problem with the host, the token, or access to the group.
Open Settings → Configuration → Connections, then select Configure for the GitLab connection to update its token or add groups and projects.

​
Configure Repository Access

To onboard everything under the connected GitLab group, select that parent group in Groups. Gitar connects all existing projects in the group and every subgroup the connected account can access. There is no need to add each subgroup or project separately.
  1. Open Settings → Configuration → Connections and select Configure for the existing GitLab connection.
  2. Keep the default Groups tab selected.
  3. Search for the top-level group’s full path, such as acme, and select the matching group.
  4. Review the project preview, then select Onboard N projects. Gitar includes projects in subgroups such as acme/platform and acme/mobile, subject to the connected account’s permissions.
For individual repositories, switch to Projects, search by name or full project path, and select Add, then Save. The screenshot below shows the Projects view with the earlier tab order. Groups opens by default on the left, with Projects on the right.

​
Multiple Top-Level Groups on One Host

Reuse the existing connection for each top-level group on the same GitLab host. Reopen Configure → Groups and repeat the steps above for each group. A second connection to the same host is rejected. The connected account must have access to every group being added. A group-created service account cannot span unrelated top-level groups. On Self-Managed or Dedicated, use an instance service account invited to each group. A dedicated user’s PAT is the fallback when service accounts are unavailable.
One connection does not automatically connect an entire GitLab instance. Select each top-level group explicitly. Projects created later must also be connected from Configure.

​
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: Connected Account Email Configuration Add noreply@gitar.ai to the connected GitLab account 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. After changing the allowlist, open Settings → Configuration in Gitar and click Refresh in the Repositories card to retry webhook registration.

​
Troubleshooting

“GitLab at … is already connected to this organization” Open the existing connection’s Configure → Groups tab to add another group on that host. A separate connection is not needed. If the group cannot be found, check the connected account’s membership and whether its service account is restricted to another top-level group. “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 connected account is a member of that group or one of its parent groups. Creating a service account inside a group does not grant membership on its own.
“Group or project access tokens are not supported” Generate a PAT from the service account’s Manage access tokens page (preferred), or the dedicated user’s profile as a fallback. Tokens generated from group or project Access tokens settings are not accepted. No Service accounts menu Service accounts are preferred but not required. Use a dedicated regular user and generate its PAT instead — availability of the Service accounts menu depends on the GitLab edition and version.