GitLab access tokens expire. Project tokens, group tokens, personal access tokens — all of them. The trouble is that the expiration dates live in different corners of the UI, and you usually find out one expired the morning a CI pipeline mysteriously starts failing.
gitlab-token-expiration is the small tool I wrote to never have that morning again.
The pain
Modern GitLab setups rack up a lot of tokens. A handful of project access tokens for CI, group tokens for shared deploy keys, your own personal access token, plus whatever your colleagues have created. Every one of them has an expiry date, and there’s no single dashboard that shows you the full picture.
The risk profile is annoying: tokens silently expire, pipelines silently break, and you spend twenty minutes asking “but it worked yesterday?” before checking the date.
What the tool does
It walks the projects and groups your token can see, plus your personal access tokens, and lists every expirable token along with its expiration date. That’s the whole feature set — it’s a discovery tool, not a rotation tool.
Install
Homebrew is the easiest:
brew tap sgaunet/homebrew-tools
brew install sgaunet/tools/gitlab-token-expiration
Or grab a binary from the releases page and drop it on your PATH.
Run it
The tool needs a token with enough scope to read project and group settings:
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxx
# Optional, for self-hosted GitLab
export GITLAB_URI=https://gitlab.example.com
gitlab-token-expiration -h
Run gitlab-token-expiration and you get a list of everything expiring, sorted by date. Pipe it into grep for a specific project, into head to see what’s about to die, or just eyeball it.
How I actually use it
Once a month, I run it manually and rotate anything expiring within the next 30 days. That’s the whole workflow.
If you want to be fancier, you can wire it into a cron, parse the output, and post to Slack when something’s about to expire. I haven’t bothered. Manual review once a month catches everything that matters and forces me to actually look at which tokens still exist — which is a small audit benefit on its own.
Where to find it
- Source: github.com/sgaunet/gitlab-token-expiration
- License: MIT
It’s a small tool that solves one specific irritation. If you’ve ever debugged a “but it worked yesterday” CI failure that turned out to be an expired token, you already understand the value proposition.