Skip to main content
Version: next

GitLab

TokenTimer uses the GitLab REST API v4 to discover Personal Access Tokens, Project Access Tokens, Group Access Tokens, Deploy Tokens, Pipeline Trigger 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. Only API v4 is supported (introduced in GitLab 9.0; API v3 was removed in GitLab 11.0), so any GitLab 9.0+ instance works.

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, deploy tokens, and pipeline trigger tokens)
  • Groups where you are Maintainer/Owner (group access tokens)
  • Best for: individual users, team members, GitLab.com
info

Pipeline Trigger Tokens specifically require the Maintainer role on the project. Developer-role access is not enough; GitLab returns an empty list for projects where you only have Developer access, even though you can see the project itself. This applies to every project, including projects that belong to a group rather than your personal namespace.

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, Pipeline Trigger Tokens, or SSH Keys. Pipeline Trigger Tokens are off by default; enable the checkbox to include them.
  • Exclude regular-user PATs: filter out PATs owned by regular users while keeping administrator and service-account PATs (enabled by default)
  • Include expired tokens: optionally scan tokens that have already expired
  • Include revoked tokens: optionally scan revoked PATs (admin only)
  • Filter rules: optional include/exclude rules (exact or regex, on name or description) applied to the scan preview, the import, and every auto-sync run. See Filter rules.
  • Remove obsolete tokens: opt-in cleanup that deletes previously imported tokens no longer found at the source. See Obsolete-token cleanup.
info

By default, only active administrator and service-account tokens are scanned. Regular-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
  • Pipeline Trigger Tokens: description, project, owner, creation date (no expiry in GitLab, imported as Never expires)
  • 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.
  • Scan filters, filter rules, and the obsolete-token cleanup setting are saved with the configuration and applied on every scheduled run.
  • 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.