Skip to main content
Version: 0.9

GitLab

TokenTimer uses the GitLab REST API v4 to discover Personal Access Tokens, Project Access Tokens, Group Access Tokens, Deploy Tokens, and SSH keys across your GitLab instance. Scan filters let you focus on service accounts or specific token types.

Supported: gitlab.com or self-hosted GitLab.

Credential setup​

  1. Go to GitLab → User Settings → Access Tokens
  2. Create a new Personal Access Token with the read_api scope
  3. Set an expiration date (recommended: 1-7 days)
  4. Copy the token immediately (it will not be shown again)
  5. Revoke after use. The token is used once and never stored (unless you configure auto-sync, which stores it encrypted).

Permissions required​

tip

The read_api scope is required and sufficient for all scans, including when using admin accounts. No additional permissions are needed.

What you can scan depends on your GitLab role:

Regular user​

  • Your own personal access tokens and SSH keys
  • Projects where you are Maintainer/Owner (project access tokens and deploy tokens)
  • Groups where you are Maintainer/Owner (group access tokens)
  • Best for: individual users, team members, GitLab.com

Admin user (self-hosted GitLab)​

  • All personal access tokens across the entire instance (all users)
  • All project access tokens and group access tokens you have access to
  • All deploy tokens in accessible projects
  • Your own SSH keys
  • Best for: security teams conducting instance-wide token audits
  • Note: admin accounts still use the read_api scope. The broader access comes from the admin role, not the token scope.

Scan filters​

Configure which credentials to scan:

  • Token types: select Personal Access Tokens, Project Access Tokens, Group Access Tokens, Deploy Tokens, or SSH Keys
  • Exclude users' Personal Access Tokens: filter out individual user PATs and keep only service account tokens (enabled by default)
  • Include expired tokens: optionally scan tokens that have already expired
  • Include revoked tokens: optionally scan revoked PATs (admin only)
info

By default, only active service account tokens are scanned. User PATs are excluded to focus on automation credentials.

What is discovered​

  • Personal Access Tokens: name, owner (admin scan), expiration, scopes, last used, creation date
  • Project Access Tokens: name, project, service account username, expiration, scopes, last used, creation date
  • Group Access Tokens: name, group, service account username, expiration, scopes, last used, creation date (GitLab 14.7+)
  • Deploy Tokens: name, project, expiration, scopes, last used, creation date
  • SSH Keys: title, expiration (if set), last used, creation date

Metadata only. No actual token values or private keys are retrieved.

Auto-Sync​

GitLab is one of two providers (with GitHub) that support scheduled re-scans on self-hosted TokenTimer. Instead of running a manual scan every time, you can save the credential once, along with your scan filters; TokenTimer encrypts the credential at rest and a background worker re-scans on a cron schedule, importing new and updated tokens automatically.

  • Set up auto-sync from the integration's scan modal by choosing a schedule and saving the credential; TokenTimer encrypts it before storing.
  • The scan frequency and worker behavior are controlled by WORKER_AUTO_SYNC_CRON (Docker Compose) or the auto-sync CronJob schedule (Helm). See Worker scheduling.
  • Every create, update, delete, manual trigger, and failure of an auto-sync configuration is recorded as an AUTO_SYNC_* audit event (AUTO_SYNC_CREATED, AUTO_SYNC_UPDATED, AUTO_SYNC_DELETED, AUTO_SYNC_TRIGGERED, AUTO_SYNC_FAILED). See Auto-Sync events.
  • This is not available on TokenTimer Cloud, which never stores integration credentials.