GitLab Integration

The GitLab integration enables Cloud ex Machina to automatically create and manage issues in your GitLab projects, helping you track cost optimization opportunities, system issues, and custom workflows.

You need a GitLab service account, with wich you will configure the integration using direct one-click integration, or most preferably using an Access Token for additional security and reliability.

Creating a GitLab Service Account (Premium/Ultimate)

GitLab Tier Requirement

Service accounts are only available in GitLab Premium and Ultimate tiers. If you're using GitLab Free, see the alternative approach section below.

Security Recommendation - Use Service Accounts Matter

Use a dedicated service account when configuring the GitLab integration. Try to avoid using a personal access tokens issued directly from individual user accounts.

When you configure a GitLab integration using a personal access token:

• All issues and comments are attributed to that specific user
• If that user leaves the company, their account is deactivated or deleted :
  • The access token becomes invalid immediately
  • All integrations using that token stop working
  • You lose visibility into automated cost optimization opportunities
  • It might cause : Security review requirements, Disruption to cost optimization workflows, Audit compliance issues...

Service accounts prevent these issues by:

• Providing consistent, non-expiring access independent of individual users
• Maintaining proper access control across team changes
• Ensuring clear attribution of automated activities
• Meeting security and compliance requirements

Prerequisites

Before configuring the GitLab integration, ensure you have:

• GitLab: Owner or Maintainer permissions in the target group/project
• Cloud ex Machina: Admin access to your tenant

GitLab service accounts are special bot accounts designed for integrations and automation. They:

• Cannot sign in through the UI
• Don't consume paid seats
• Are authenticated exclusively via personal access tokens
• Are clearly identifiable as non-human users in audit logs

Step 1: Create the Service Account

For GitLab.com (Premium/Ultimate):

1. Sign in as a top-level group Owner
2. Navigate to your top-level group
3. Go to Settings > Service accounts
4. Click New service account
5. Fill in:
   • Name: Cloud ex Machina Integration
   • Username: cxm-integration (or your preferred username)
6. Click Create service account

For Self-Managed GitLab (Premium/Ultimate):

1. Sign in as an instance administrator
2. Navigate to Admin Area > Users
3. Click New service account
4. Fill in:
   • Name: Cloud ex Machina Integration
   • Username: cxm-integration (or your preferred username)
5. Click Create service account

note

• Premium tier: Limited to one service account per paid seat
• Ultimate tier: Unlimited service accounts

tip

Service accounts are automatically identified as bots in GitLab's interface and audit logs, making it easy to track automated activities.

Step 2: Add Service Account to Your Groups/Projects

Service accounts must be explicitly added to the groups or projects where they need access:

1. Navigate to your GitLab group or project
2. Go to Settings > Members
3. Click Invite members
4. Select the service account you just created
5. Assign an appropriate role:
   • Maintainer: Required minimum for creating issues and managing project resources
   • Owner: Needed for group-level access (for GitLab.com group service accounts)
6. Click Invite

note

Service accounts work like regular users but can only authenticate via access tokens. They can be added to multiple projects with different permission levels in each.

Step 3: Create a Personal Access Token

Service accounts authenticate exclusively through personal access tokens. To create one:

For GitLab.com:

1. From the service account page (Settings > Service accounts)
2. Click on your service account name
3. In the Access Tokens section, click Add new token
4. Configure the token:
   • Token name: Cloud ex Machina Integration
   • Expiration date: Maximum 365 days (default), or set according to your security policies
   • Scopes: Select the following required scopes:
     • api - Full API access (required for issue creation and management)
     • read_user - Read user's profile
     • read_repository - Read repository data
     • write_repository - Write repository data (required for code versioning features)
     • self_rotate - Optional - Allows CXM to rotate the token periodically for enhanced security.
5. Click Create personal access token
6. Critical: Copy the token immediately and store it securely in a password manager or secrets vault

For Self-Managed GitLab:

1. Navigate to Admin Area > Users
2. Find and click on your service account
3. Click the Access Tokens tab
4. Follow steps 3-6 above

Token Security

The access token is displayed only once at creation. If you lose it, you must create a new token and update the Cloud ex Machina integration configuration.

Token Expiration

GitLab service account tokens default to 365-day expiration. Plan token rotation in advance to avoid service disruption.

Configuring the Integration in Cloud ex Machina

Step 1: Navigate to Integrations

1. Go to your Cloud ex Machina tenant
2. Navigate to Settings > Integrations
3. Find GitLab AI Agent (Personal Access Token) in the list of available integrations
4. Click Connect

Step 2: Enter GitLab Configuration

In the integration settings dialog, provide:

• GitLab Instance URL:
  • For GitLab.com: gitlab.com
  • For self-hosted: Your GitLab instance URL (e.g., gitlab.yourcompany.com)
• Personal Access Token: The token you created from the service account

Step 3: Save

1. If successful, click Save to activate the integration
2. Configure additional settings:
   • Namespace Path: Select your company's namespace in the choice list (e.g., my-company)
   • Repository: The default repository where issues will be created by Cloud ex Machina.

Troubleshooting

Integration Test Fails

Problem: Connection test fails when configuring the integration

Solutions:

• Verify the access token is copied correctly (no extra spaces)
• Ensure the service account has Maintainer or Owner role in the project
• Check that the project path is correct (case-sensitive)
• For self-hosted GitLab, verify the instance URL is accessible from Cloud ex Machina

Issues Not Being Created

Problem: Integration is configured but issues aren't appearing in GitLab

Solutions:

• Verify the service account still has access to the project
• Check the access token hasn't expired
• Review the integration settings to ensure events are configured to trigger issue creation
• Check Cloud ex Machina logs for any error messages

Service Account Access Revoked

Problem: The service account was accidentally removed or deactivated

Solutions:

• Re-add the service account to the project with appropriate permissions
• Verify the account is active in GitLab user management
• If needed, create a new service account and update the integration

Alternative Approach using Dedicated Bot Account

If you're using GitLab Free tier (which doesn't support service accounts), or if you don't want to use service account tokens, you can use a dedicated bot user account as a workaround:

Creating a Dedicated Bot User

1. Create a new GitLab user account with a shared team email:

   • Email: cxm-integration@yourcompany.com (use a team distribution list)
   • Name: Cloud ex Machina Bot
   • Username: cxm-integration-bot

2. Secure the account:

   • Use a strong, unique password stored in a password manager
   • Enable two-factor authentication if your organization requires it
   • Share access credentials only with administrators who need them

3. Add the bot user to your projects:

   • Navigate to your project
   • Go to Settings > Members
   • Invite the bot user account
   • Assign Maintainer role (required for issue creation)

4. Connect the CXM Gitlab integration

   • Sign in as the bot user (or impersonate him)
   • Go to Cloud ex Machina integrations page, then click connect on the Gitlab AI Agent standard integration.

   OR for additional security, Create and use a personal access token:

   • Sign in as the bot user (or impersonate him)
   • Navigate to Preferences > Access Tokens
   • Create a token with the same scopes as listed in Step 3 above
   • Store the token securely
   • Go to Cloud ex Machina integrations page, then click connect on the Gitlab AI Agent (Personal Account Token) integration, inputing your access token.

Bot User Limitations

Bot users in GitLab Free:

• Count against your seat/user limit
• Are not automatically identified as bots in the UI
• Can sign in through the UI (should be disabled via strong password policies)
• Require more careful access management

Recommendation: Upgrade to GitLab Premium or Ultimate for true service account support if security and auditability are critical.

Security Best Practices reminder

1. Avoid using personal access tokens from individual user accounts for integrations
2. Use dedicated service accounts (Premium/Ultimate) or dedicated bot users (Free/Self-hosted) with minimal required permissions
3. Store access tokens securely in a password manager or secrets vault
4. Rotate tokens regularly (e.g., every 90 days or before token expiration) according to your security policies
5. Monitor account activity for suspicious behavior through GitLab's audit logs
6. Document account ownership so multiple admins can manage it
7. Review permissions quarterly to ensure they remain appropriate
8. Use shared team emails for bot users, never personal email addresses

Next Steps

• Learn about other available integrations in Integrations Overview
• Configure additional providers to centralize your workflows