Overview

When integrating GitLab repositories with Aqua Supply Chain Security using pull-based CI integration, the GitLab personal access token or project access token must include write permissions. This requirement applies even when the primary goal is code scanning and comparison, because Aqua posts scan results directly to pull requests.

This article explains the required GitLab token permissions, why write access is necessary, and how to justify the requirement to GitLab administrators.

Required Token Permissions

For GitLab CI integration with Aqua Supply Chain Security, configure the GitLab token with write permissions as displayed on the Aqua integration page.

The permissions shown on the Supply Chain Security → Integrations → GitLab page in the Aqua console are accurate and should be followed.

Why Write Permissions Are Required

Although the integration is described as pull-based (Aqua retrieves code from the repository for scanning), Aqua also posts comments directly on merge requests with scan findings and status.

This behavior requires write-level API access to:

• Create or update comments on merge requests
• Post scan result summaries inline in the GitLab UI
• Enable developers to review findings without leaving the merge request workflow

Read-only permissions are insufficient because comment posting is a write operation on the GitLab API.

Pull-Based Scanning vs. Token Permissions

Aqua does not require write access to modify repository source code. Write permissions are used specifically for merge request comment integration, not for pushing code changes.

Configuration Steps

Step 1: Create a GitLab Access Token

1. 1. In GitLab, navigate to User Settings → Access Tokens (or project/group token settings)
2. 2. Create a token with the scopes required by the Aqua integration page
3. 3. Ensure write-level API access is included (typically api scope)

Step 2: Configure the Integration in Aqua

1. 1. Log in to the Aqua console
2. 2. Navigate to Supply Chain Security → Integrations → GitLab
3. 3. Enter the GitLab instance URL and access token
4. 4. Follow the permission guidance displayed on the integration page
5. 5. Test the connection and verify merge request comment posting

Step 3: Verify Integration

1. 1. Open a merge request in the connected GitLab repository
2. 2. Trigger a Supply Chain Security scan (via CI pipeline or Aqua event)
3. 3. Confirm scan findings appear as comments on the merge request
4. 4. Review the repository scan history in the Aqua console

Justifying Write Permissions to GitLab Administrators

When requesting token approval from a GitLab security or platform team, provide the following rationale:

• Aqua Supply Chain Security integrates scan results into the merge request review workflow
• Write API access is required only for posting comments, not for modifying source code
• Read-only tokens will cause comment integration to fail
• Permissions align with the official Aqua integration requirements displayed in the console

Important Considerations

• Enterprise policy: Some organizations restrict write tokens at the group or instance level; coordinate with GitLab admins early in the integration process
• Token scope minimization: Use project-scoped or group-scoped tokens where possible rather than instance-wide tokens
• Documentation alignment: Aqua documentation is being updated to reflect the write permission requirement for CI integration clarity

Platform Coverage

• Component: Supply Chain Security
• Platform: Aqua SaaS
• Integration: GitLab CI (pull-based)

Summary

Related Resources

• Supply Chain Security CI Integrations
• GitLab Integration Guide