Socket for GitLab permissions
The GitLab roles and scopes the Socket GitLab app's tokens need, and the data the app sends to Socket.
Socket for GitLab is in beta. Behavior may change between releases.
The Socket GitLab app uses one GitLab token for API calls and, optionally, separate read-only tokens for clones. Give each token the lowest role its jobs need.
GitLab roles by job
GITLAB_TOKEN needs the api scope and the highest role among the jobs you turn on:
| Job | When it applies | Minimum role for GITLAB_TOKEN |
|---|---|---|
Merge request comments, project sync, socket.yml reads | Every deployment | Guest |
| "Socket Security" commit statuses | ENABLE_COMMIT_STATUS=true | Developer |
| External status checks | ENABLE_EXTERNAL_STATUS_CHECKS=true (GitLab Ultimate) | Developer |
| Pipelines must succeed on each project | ENFORCE_MERGE_CHECKS=true | Maintainer on each project |
| One webhook per project | Self-managed GitLab, or GitLab.com Free, when the app manages webhooks | Maintainer on each project |
| One group webhook | GitLab.com Premium or Ultimate, when the app manages webhooks | Owner on the group |
Clones use GITLAB_READ_TOKEN or the tokens in GITLAB_TOKENS, with the read_repository scope and the Reporter role. Without a clone token, the app clones with GITLAB_TOKEN, which then needs read_repository as well as api.
Token types by GitLab tier
Self-managed GitLab offers group access tokens on every tier, Free included. On GitLab.com, group access tokens need Premium or Ultimate, so on GitLab.com Free use a personal access token from a user who has the role you need on each project.
Socket API token scopes
Create the Socket API token in the organization the app uses, with every full-scans, diff-scans, and repo scope. The app creates a Socket repository for each GitLab project, uploads scans, and reads diff scan results for merge requests.
Startup scope check
At startup, the app asks GitLab which scopes each token carries and logs one line per token. GITLAB_TOKEN scopes look minimal means the token has only the scopes its job needs. A warning such as GITLAB_TOKEN has broader scopes than needed names the extra scopes. The check never stops the app, and the log names the setting, never the token value.
Data the app sends to Socket
The app clones each commit inside its container and sends Socket the following:
- Manifest files and lockfiles that match Socket's list of supported files, such as
package.json,package-lock.json,pom.xml, andrequirements.txt. The contents of other files never leave the host. - Scan metadata: the project and group path, branch, commit hash and message, the committer's email address, and the merge request number.
- The app's operational logs (startup, sync, and scan events), sent to api.socket.dev.
- Error reports, sent to Socket's error tracking service.
Related topics
Updated about 5 hours ago