GitLab

Trustle reads users, groups, projects, and their members from GitLab. Trustle can add and remove group and project members, and set their access level.

Prerequisites

• An identity provider connected in Trustle, for example Okta or Microsoft Entra ID. Trustle hides SaaS Applications until one is connected.
• One of these accounts for Trustle:
  • Group service account: needs the Owner role in the top-level group. On self-managed GitLab, an administrator can also create it. It does not use a seat, and it cannot sign in to the GitLab UI. Service accounts are on every tier in recent GitLab versions, but the limits differ by version and by instance.
  • Dedicated user account: works on every GitLab tier. A GitLab administrator creates it, or on GitLab.com a group Owner invites it by email. It uses a seat, and it can sign in to the GitLab UI unless you restrict it.
• For self-managed GitLab: Trustle must reach the instance over HTTPS.

Configure GitLab

Step 1: Create an account for Trustle

Use a group service account if your tier has one. Otherwise, use a dedicated user account.

Option A: Group service account

1. In GitLab, open your top-level group. Go to Settings → Service accounts.
2. Click Add service account.
3. Enter a name, for example trustle-integration. GitLab makes a username such as service_account_group_<id>_<random>. You can change it.
4. Click Create service account.

Option B: Dedicated user account

1. Create the user, for example trustle-service, with an email such as trustle-service@company.com. On self-managed GitLab or GitLab Dedicated, a GitLab administrator creates it. On GitLab.com, a group Owner invites the email address, and the invitee creates the account. Set a strong password; you need it only for setup. Mark the user as an External user if it must not see internal projects.
2. On self-managed GitLab, give the user the Administrator access level if you want Trustle to read every user’s email. See Step 3.

Step 2: Add the account to your groups

GitLab gives a new account no access. Trustle imports the groups that the account can see and the projects that it is a member of. With the Administrator access level, the account sees every group. You can also add the account to single projects instead of a whole group.

1. Open the top-level group. Go to Manage → Members.
2. Click Invite members.
3. Search for the account username from Step 1.
4. Select the Owner role. Click Invite.
5. Do this for each top-level group that Trustle must read.

The account gets the same access to every subgroup and project below the group.

Step 3: Grant permissions

Permission	Required	What Trustle does with it
api token scope	Yes	Calls the GitLab API. Test Connection uses it.
Group membership (Step 2)	Yes	Imports the groups, projects, and members that the account can see. Without it, the sync imports nothing. Test Connection does not check it.
Owner role in each group	Yes	Adds and removes group and project members at every access level. With a lower role, GitLab refuses some changes. Only an Owner can give the Owner role.
Administrator access level (self-managed, Option B only)	Optional	Reads every user’s email, so Trustle can link GitLab users to Trustle users. Without it, GitLab returns only the email that each user made public. Users with no public email stay unlinked.

Step 4: Create a personal access token

For Option A:

1. In the top-level group, go to Settings → Service accounts.
2. Select the service account. Open its access tokens and click Add new token.
3. Continue at the token form below.

For Option B:

1. Sign in to GitLab as the dedicated user.
2. Go to User settings → Access tokens. Click Add new token.
3. Continue at the token form below.

On the token form:

1. Enter a Token name, for example Trustle.
2. Set an Expiration date that matches your security policy. GitLab allows at most 365 days by default. Some GitLab 17.6 and later instances allow 400 days, if an administrator turned it on. GitLab Dedicated does not.
3. Under Scopes, select api.
4. Click Create personal access token. Copy the token.

Caution

GitLab shows the token once. If you lose it, create a new token.

Step 5: Collect the values for Trustle

Trustle field	Where to find it in GitLab	Example
GitLab URL (Optional)	Leave it empty for GitLab.com. For self-managed GitLab, enter the instance address. It must start with https://.	https://gitlab.example.com
Personal Access Token	The token from Step 4	glpat-…

Connect in Trustle

1. In Trustle, go to Connections.
2. Under SaaS Applications, find GitLab and click Connect.
3. Enter a Connection Name, for example GitLab production. Description is optional.
4. Enter the values from Step 5.
5. Click Test Connection.
6. After the test passes, click Save Connection.

Note

Test Connection checks only that the token is valid. An account with no group memberships passes the test, and the sync then imports nothing. Do the steps in Verify after the first sync.

Verify

1. On the Connections page, open the GitLab connection.
2. Wait for the first sync to finish.
3. Check that Trustle shows the groups and projects from Step 2.
4. Check that GitLab users are linked to Trustle users. An unlinked user has no email in GitLab.

If something is missing, see Troubleshooting.

Caution

Trustle removes a member from the group or project where the member was added. If the user also gets access from a parent group, GitLab keeps that access.

Security notes

Note

• Use a dedicated account for Trustle only. Do not use a person’s own token.
• Store the token in a secret manager. Never commit it to a repository.
• Create a new token before the old one expires. Then paste the new token into the Trustle connection.

Troubleshooting

Test Connection fails

• Personal Access Token: check that the token has not expired and is not revoked. It must have the api scope.
• GitLab URL: leave it empty for GitLab.com. For self-managed GitLab, the address must start with https://.

Test Connection passes, but the sync imports no groups or projects

The account is not a member of any group. GitLab does not add a new service account to its group. Do Step 2. Then run the sync again.

GitLab users are not linked to Trustle users

GitLab returns a user’s email only to an administrator token, or when the user made the email public. Do one of these:

• On self-managed GitLab, give the Trustle account the Administrator access level.
• Ask each user to set a Public email in their GitLab profile.

Trustle links the users after the next sync.

Last-used dates are empty

Trustle reads the last-used date from each user’s GitLab activity. A service account that uses only the API often has no activity, so its date stays empty.

Trustle cannot add or remove a member

The account needs the Owner role in the group. Do Step 2.

None of these fixes work

Email support@trustle.com. Include the error message, the connection name, and the GitLab URL (or GitLab.com) and the top-level group name. Never send a secret, key, or token.