Vault Plugin for Gitlab Access Token

This is a standalone backend plugin for use with Hashicorp Vault/OpenBao. It lets you automate the creation and revocation of GitLab personal, project, and group access tokens through Vault.

IMPORTANT: Upgrading to >= 0.7.x will require you to revoke, remove all the paths, and remove the mount path. This is required because the paths internally have changed to accommodate config per role.

Security model

The current authentication model requires providing Vault with a Gitlab Token.

GitLab Support

• GitLab CE/EE (Self-Managed)
  • 17.11.7 CE (tested)
  • 18.11.2 CE (tested)
• GitLab.com
  • Personal access tokens and user service accounts are not supported
• GitLab Dedicated
  • Personal access tokens and user service accounts are not supported

Quick links

• Vault Website – https://www.vaultproject.io

Token types

All tiers = Free + Premium + Ultimate · All offerings = GitLab.com + Self-Managed + Dedicated

Token type	Tier	Offering	Status
Personal Access Tokens	All tiers	All offerings	GA
Project Access Tokens	All tiers	All offerings	GA
Group Access Tokens	All tiers	All offerings	GA
User/Group Service Account Tokens¹	All tiers	All offerings	GA
Pipeline Project Trigger Tokens	All tiers	All offerings	GA
Group/Project Deploy Tokens	All tiers	All offerings	GA

¹ Service accounts on GitLab Free are capped: up to 100 per top-level group on GitLab.com, or 100 per instance on Self-Managed. Premium and Ultimate are unlimited.

Getting started

This is a Vault plugin and is meant to work with Vault. This guide assumes you have already installed Vault and have a basic understanding of how Vault works.

Otherwise, first read this guide on how to get started with Vault.

To learn specifically about how plugins work, see documentation on Vault plugins.

Quickstart

Register the plugin binary and enable it:

vault plugin register \
  -sha256=$(sha256sum path/to/plugin/directory/gitlab | cut -d " " -f 1) \
  -command=vault-plugin-secrets-gitlab \
  secret gitlab

vault secrets enable gitlab

Configure the backend and verify the config:

vault write gitlab/config/default base_url=https://gitlab.example.com token=gitlab-super-secret-token auto_rotate_token=false auto_rotate_before=48h type=self-managed
vault read gitlab/config/default

Create a role and request a token:

vault write gitlab/roles/personal name='{{ .role_name }}-{{ .token_type }}-{{ randHexString 4 }}' path=username scopes="read_api" token_type=personal ttl=48h
vault read gitlab/token/personal/username

Documentation

• Path overview and endpoint patterns
• Runtime flags
• Backend configuration
• Role configuration and templating
• End-to-end examples
• Upgrade guidance
• Local development

Info

Running the logging with debug level will show sensitive information in the logs.