GitLab Permissions

Divekit authenticates with a personal, project, or service-account access token. Two independent permission layers determine what the CLI can do:

1. the scopes attached to the token
2. the GitLab permissions of the account that owns the token

A broad token scope does not grant its owner additional access to groups or projects. A high group role cannot compensate for a token that lacks the needed API scope.

Token Scope

Current authentication and distribution workflows require the GitLab api scope. Divekit validates this scope during authentication. Additional read_api or write_repository scopes do not expand namespace access when api is already present.

Keep tokens out of committed files and command histories. Prefer the operating system credential store, Divekit’s secret store, an environment variable, or a file:///absolute/path/to/token value passed to divekit auth --token.

Standard Distribution

For a normal distribution into an existing group, the token owner must be able to:

• read the selected group and relevant users
• create projects in the configured groupId
• push generated repository content
• read and update created projects
• add project members at the role configured by members.permissions, unless member assignment is disabled

GitLab combines group membership with the group’s Allowed to create projects setting. There is no single minimum role that works on every instance. A practical starting point is Maintainer in a group that permits Maintainers to create projects and manage members. Use Owner only when group policy or the intended operation requires it. Instance-wide administrator access is not required for a normal distribution.

The token owner can assign only roles that GitLab permits that account to grant. Check this when members.permissions requests a high project role.

Additional Capabilities

Creating distribution subgroups requires permission to create subgroups below the configured parent. Deleting existing repositories or purging a distribution requires permission to delete the affected projects; do not grant that capability only for normal distribution.

An enabled evaluation target can additionally require permission to:

• create and update projects in the evaluation group
• create project access tokens and pipeline trigger tokens
• create or update CI/CD variables
• manage the inbound CI job-token allowlist between work and evaluation projects
• update project and GitLab Pages settings
• run pipelines on an available runner

Exact roles depend on the GitLab version, group policy, and custom-role configuration. The relevant CI/CD and Pages features must also be enabled.

Diagnose Permission Failures

A successful divekit auth confirms that the token is valid and has the required scope. It does not prove that the account may create projects or manage members in a particular group.

For 403 Forbidden responses or rejected project/member operations, verify:

1. groupId points to the intended group
2. the token owner’s effective role in that group
3. the group’s project- and subgroup-creation settings
4. the requested member role may be granted by that account
5. cleanup, evaluation, CI/CD, and Pages permissions separately

Related pages:

• Installation
• config.json
• members.json
• Evaluation Pipeline