Skip to main content
Garth supports two token types for GitLab authentication. Use a Group Access Token if you are on GitLab Premium or Ultimate — it creates a managed bot user and simplifies permission management across the organization. Otherwise, use a Personal Access Token from a dedicated service account.

​
Step 1: Create an access token

Do not use a personal user account. Code reviews will be attributed to the token owner. Create a standalone service account named GPRABot exclusively for this integration.
The service account must be added to the relevant project as a Maintainer — this role is required to manage webhooks.
1

Authenticate as the service account

Log into GitLab using the dedicated Garth service account.
2

Open Access Token settings

Click your avatar → Edit Profile → Access Tokens.
3

Name the token

Give the token a clear name such as Garth Bot Key. You can optionally set an expiry date; leaving it blank defaults to 365 days. If the token expires, Garth stops functioning until you replace it in the dashboard.
4

Select token scopes

Enable the following scopes:
  • api
  • read_api
  • read_user
  • read_repository
  • write_repository
5

Save the token

Click Create Personal Access Token and copy the token immediately. GitLab will not display it again.
1

Open Garth integrations

Log into the Garth dashboard and navigate to Settings → Integrations.
2

Bind the token

Select the GitLab tab. Enter your GitLab URL (https://gitlab.com) and the Access Token you just created, then click Validate.
GitLab integration settings showing token validation
3

Install repositories

After validation, select the repositories you want Garth to review and click Install Repositories.
Automatic webhooks: Garth installs webhooks on selected repositories automatically. No manual webhook configuration is required. Webhooks are also removed automatically when you uninstall a repository.
GitLab integration settings showing repository selection and Install Repositories button

​
Network configuration

If your infrastructure requires IP allowlisting, permit the following address through your firewall: 
34.117.160.133/32

​
Troubleshooting

If Garth is not accessing repositories or reviewing merge requests:
  1. Check webhook status — go to the project’s settings in GitLab under Webhooks and verify the Garth webhook exists and is active.
  2. Manually delete the webhook if it exists but is not working.
  3. Refresh the repository page in the Garth app.
  4. Reinstall the webhook — untoggle and re-toggle the repository in the Garth dashboard.
If you cannot install Garth on a repository:
  1. Verify group/project membership — the service account must hold at least Maintainer access to the target project to manage webhooks.
  2. Check token scopes — confirm all required scopes (api, read_api, read_user, read_repository, write_repository) are present on the token.
  3. Re-validate the token — go to Settings → Integrations → GitLab in Garth and re-enter your credentials.
  4. Toggle the repository — uninstall and reinstall the repository from the Garth app to force a fresh webhook setup.
If you receive authentication or permission errors:
  1. Check token expiry — GitLab Personal Access Tokens expire based on the date you set (or after 365 days by default). Regenerate and update the token in Garth if it has lapsed.
  2. Confirm the token type — use either a Group Access Token with api scope and Maintainer role, or a Personal Access Token from the dedicated service account — not a personal user account.
  3. Verify Group Owner status — the Garth user initiating the connection must hold GitLab Group Owner status.
  4. Re-authenticate — update the token in Settings → Integrations → GitLab within Garth and re-link with a freshly generated token.