Step 1: Create a Service Account

GitLab integration uses Personal Access Tokens (PAT) from a dedicated account.

Account options:

• Group Service Account (GitLab Premium / Ultimate only)
  GitLab’s official service account feature. Recommended when available.
  Does not consume a seat license.
• Dedicated User Account (All GitLab tiers)
  A regular GitLab user created exclusively for automation purposes.
  Consumes a seat license.

Both options are supported by Trustle.
Use Group Service Accounts when available; otherwise, use a Dedicated User Account.

Option A: Group Service Account (Recommended - GitLab Premium/Ultimate Only)

Prerequisites:

• GitLab Premium or Ultimate tier (not available on Free tier)
• Owner role in a top-level group on GitLab.com
• For self-hosted: Administrator status OR Owner role with appropriate permissions

Steps:

1. Go to your top-level group's service accounts page: https://gitlab.com/groups/{your-group}/-/settings/service_accounts
2. Click "Add service account"
3. Enter a name (e.g., "trustle-integration")
   
   • Username will auto-generate as service_account_group_{id}_{random} but can be edited
4. Click "Create service account"
5. CRITICAL: Service accounts do not automatically have access. You must explicitly add them:
   
   • Go to Group → Members: https://gitlab.com/groups/{your-group}/-/group_members
   • Click "Invite members"
   • Search for the service account username
   • Assign role: Owner (recommended for full access)
   • Service account will inherit access to subgroups and projects

Important Notes:

• Service accounts do not use a seat license
• Service accounts cannot access the GitLab UI (API and Git operations only)
• Maximum token expiration: 365 days (400 days in GitLab 17.6+)

Option B: Dedicated User Account (For GitLab Free or Self-Hosted Without Service Account Feature)

If you don't have access to Premium/Ultimate or prefer a manual approach:

1. Have a GitLab administrator create a new user account:
   
   • Username: e.g., trustle-service or trustle-integration
   • Email: Service account email (e.g., trustle-service@company.com)
2. Configure the account:
   
   • Set a strong password (will only be used for initial setup)
   • Mark as "External user" if you don't want it to have access to internal projects
   • For full access to all GitLab users, groups, and projects: Grant Administrator role
3. CRITICAL: Add the user account as a member to groups/projects you want to extract:
   
   • Go to each group: Group → Members → Invite members
   • Search for the user account username
   • Assign role: Owner (recommended for full access)

Limitations of Manual User Accounts:

• Consumes a seat license (unlike service accounts)
• Can access GitLab UI unless separately restricted
• Subject to user-related policies and access controls

Step 2: Generate a Personal Access Token

Group Service Account (GitLab Premium / Ultimate)

1. Go to Group Settings → Service Accounts
2. Select the service account
3. Open the Access Tokens tab
4. Click Add new token
5. Configure the token:
   
   • Token name: Trustle Acme Integration
   • Expiration date: Set according to your security policy (maximum 365 days)
   • Scopes: select api
6. Click Create personal access token
7. Copy the token immediately (it will not be shown again)

Step 3: Set up the integration

1. Navigate to the Connections page in Trustle from the left menu
2. Under SaaS Applications find the Gitlab logo and choose Connect
3. Provide the connection details and Personal Access Token created on Step 2
4. Click Test Connection
5. Upon successfully testing the connection, click Save Connection

‍