GitLab Administrator Permissions Required for Supply Chain Security Runner Discovery

Overview

When integrating a self-hosted GitLab server with Aqua Supply Chain Security, the integration token must have GitLab administrator privileges to discover and list GitLab runners. This requirement is imposed by GitLab's API design—not by Aqua—and affects automatic repository and runner discovery when using Source Code Management integration.

This article explains why administrator access is required, which integration capabilities are affected, and what functionality remains available with read-only or non-administrator tokens.

Understanding GitLab Runner API Permissions

GitLab restricts access to runner management APIs to administrator accounts. The List all runners endpoint (GET /runners) requires administrator privileges even though the operation is read-only.

GitLab API reference: List all runners

When Aqua Supply Chain Security integrates with a self-hosted GitLab instance, CodeSec operates between the Aqua platform and GitLab. For ad-hoc scans triggered through the integration, Aqua must initiate scan jobs on GitLab runners. Discovering available runners requires calling the GitLab runners API, which GitLab only permits for administrator accounts.

> Note: This is a GitLab platform restriction. Aqua cannot override or bypass GitLab's permission model for runner listing.

Supply Chain Security Integration Modes

Aqua Supply Chain Security supports two integration approaches when adding a repository under Supply Chain → Code Repositories → Add New Repository:

Source Code Management

• Automatically discovers repositories and triggers scans on a regular schedule
• Analogous to integrated registry discovery in Workload Protection
• Requires runner discovery via the GitLab runners API
• Requires GitLab administrator token for full functionality

CI Integrations

• Scans are triggered explicitly—you define what to scan and when
• Analogous to CI/CD pipeline scans in Workload Protection
• Does not depend on automatic runner discovery
• Can operate without GitLab administrator privileges, but with limited scope

Behavior Without Administrator Access

If the GitLab integration token does not have administrator privileges:

Without administrator access, Aqua cannot enumerate runners across the GitLab instance. This is particularly relevant in environments with:

• Shared runners managed at the instance level
• Group or project runners managed by individual application teams

Downgrading from administrator to read-only permissions may cause ad-hoc scans to fail or produce incomplete results due to insufficient access to runner configurations.

Comparison with Other Integrations

This permission model is similar to other third-party integrations where the upstream platform requires elevated access for catalog or inventory operations:

• Harbor registry integration requires administrator access to retrieve the _catalog endpoint for image discovery
• GitLab runner integration requires administrator access to list runners for discovery

In both cases, the elevated permission requirement originates from the upstream platform's API design, not from Aqua.

Important Considerations

Security Assessment Implications

Organizations conducting security assessments should evaluate:

1. 1. Scope of administrator access — A GitLab administrator token grants instance-wide API access as defined by GitLab's permission model
2. 2. Runner visibility — Administrator access allows listing runners across shared and project-level runners, not limited to a single project
3. 3. Integration mode selection — CI Integrations may satisfy security requirements when automatic discovery is not required

Shared Runner Environments

In GitLab instances with both shared runners and project-specific private runners, administrator-level API access can list runners beyond a single application's scope. Organizations with strict least-privilege policies should weigh this against the need for Source Code Management auto-discovery.

Product Direction

Aqua is engaged with product management regarding GitLab's least-privilege API design and potential future integration options that reduce the administrator requirement.

Recommended Approaches

Option 1: Use CI Integrations (Least Privilege)

If automatic discovery is not required:

1. 1. Navigate to Supply Chain → Code Repositories → Add New Repository
2. 2. Select CI Integrations as the integration type
3. 3. Configure explicit scan triggers for specific repositories and pipelines
4. 4. Use a GitLab token with permissions scoped to the required projects

This approach avoids the need for instance-wide runner listing.

Option 2: Grant Administrator Access (Full Discovery)

If Source Code Management with automatic discovery is required:

1. 1. Create a dedicated GitLab service account with administrator privileges
2. 2. Use this account solely for the Aqua integration
3. 3. Apply organizational access controls and audit logging on the service account
4. 4. Configure the integration under Source Code Management

Option 3: Evaluate with GitLab Vendor

Organizations unable to grant administrator access may consult with GitLab regarding:

• Alternative API endpoints for runner visibility
• Project-scoped runner listing options
• Future GitLab API permission changes

Verification

Confirm Integration Mode

1. 1. Log into Aqua Console
2. 2. Navigate to Supply Chain → Code Repositories
3. 3. Review the integration type configured for your GitLab server (Source Code Management vs. CI Integrations)

Confirm Runner Discovery Status

1. 1. If using Source Code Management, verify runners appear in the integration configuration
2. 2. If runners are not listed and the token lacks administrator privileges, this is expected behavior per GitLab API restrictions
3. 3. Test an explicit CI Integration scan to confirm scan execution works independently of runner discovery

Platform Coverage

Applicable To:

• Aqua SaaS
• Aqua Enterprise Self-hosted
• Supply Chain Security (CodeSec)

Integration Type:

• Self-hosted GitLab server integration

Not Applicable To:

• GitLab.com SaaS integrations with different permission models (verify current GitLab documentation)

Summary

Related Resources

• GitLab API — List all runners
• Aqua Supply Chain Security Documentation
• Supply Chain — Code Repositories Integration