Skip to main content
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

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> (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.
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 — 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
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
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.
4

Connect in Gitar

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