GitLab access for project automations

On Project credits, the project's automations reach GitLab through a token that a project admin stores in project settings. JetBrains Air Teams keeps one token per GitLab instance and uses it only for automations that run on the project's credits. Until a token is stored, those automations are paused.

This works the same for GitLab.com and for a GitLab Self-Managed instance that an organization administrator registered in JetBrains Central Console. The token belongs to one instance, so a project whose automations span both connects each instance separately, and project settings lists them by host.

Create the token for an account that exists for this purpose rather than for a person, so the automations keep running as people join and leave. This token is separate from the GitLab authorization you complete for your own cloud tasks – see GitLab.

Create the token in GitLab – as a service account token if your tier offers one, otherwise as a project access token – and then add it to the project in JetBrains Air Teams.

A GitLab service account can serve every repository the project's automations use, so it fits a project with several repositories. GitLab offers service accounts on the Premium and Ultimate tiers.

Create a service account token

In GitLab, go to Settings | Service Accounts and create a service account.
Generate a personal access token for the account, with the scopes its automations need:
- write_repository and api – to push branches and open merge requests. Most automations do this.
- read_repository and read_api – for automations that only read the code, such as reviews.
Add the account as a member of every GitLab project whose repository the automations work on, with the Developer role to push, or Planner for read-only automations. GitLab gives a new member the Guest role, which isn't enough for either. For what each role can do, see Roles and permissions in the GitLab documentation.
This step is easy to miss: until you add it to a project, a service account reaches public projects only.

If service accounts aren't available on your GitLab tier, use a project access token instead. Such a token works only in the GitLab project where you create it, and JetBrains Air Teams stores one token per GitLab instance – so this path fits a project whose automations all work on the same repository.

Create a project access token

On the GitLab project page, go to Settings | Access Tokens.
Create a token, and give it the same scopes and role a service account token needs: the Developer role with the write_repository and api scopes, or Planner with read_repository and read_api for read-only automations. GitLab adds the token's bot user to the project with that role.

Add the token to the project

On the Projects page, select the project, click … in the top-right corner, and select Edit to open project settings.
Under AI Credits, click Connect GitLab for the instance you're adding the token for.
Paste the token into Token and click Save.
JetBrains Air Teams checks the token with GitLab before storing it, so a token that's invalid or missing a scope is rejected right away instead of failing during a run.

The AI Credits section now shows the account the project is connected as and the instance it belongs to, and the automations that were paused for a missing token start running again. Members see the connection but can't change it.

If an automation stays paused, the token's account isn't a member of the GitLab project that holds the repository. Add it there with the role the automation needs.

Replace or remove the token

To replace the token when it expires or you rotate it, click … next to the connection in project settings and select Reconnect – JetBrains Air Teams doesn't show a stored token again.

Select Disconnect to remove the token. The project's GitLab automations are then paused until you add a new one.

30 September 2026