Connect GitLab to Viio in a few clicks to track seats, spot inactive repos, and make sure you only pay for the licences you truly need.
Capabilities
Capability | What it means in Viio |
✅ Users | Imports every active GitLab member so you can map ownership and cost. |
✅ Usage | Captures the Last activity on GitLab date for each user, helping you identify dormant accounts. |
✅ Plans & Licences | Fetches your licensed‑seat count and compares it with actual seats in use. |
Prerequisites
You must be a GitLab Admin (GitLab SaaS or self‑managed) to authorise the integration.
GitLab self‑managed only: make sure your instance is reachable from
app.viio.io(port 443).
Setup
Go to Viio → Integrations and choose GitLab.
Select GitLab SaaS or Self‑Managed, then click Connect.
When GitLab asks for permission, review the scopes (read_api and read_user) and choose Authorise.
Back in Viio, give the connection a friendly name (e.g. Engineering GitLab) and press Save.
Wait for the first sync to finish—Viio will let you know when the data is ready.
Self‑managed token alternative
If your firewall blocks OAuth redirects, you can use a Personal Access Token instead:
In GitLab, go to User Settings → Access Tokens.
Create a token with scopes read_api and read_user.
In Viio, choose Use personal access token and paste the value.
Click Validate & Install.
Troubleshooting & FAQ
Issue | How to resolve |
Authorisation failed | Check that the GitLab user is an Admin and the scopes read_api and read_user are enabled. |
No data after 24 h | Verify the token/OAuth app is still active and hasn’t expired. |
Seats don’t match GitLab UI | GitLab counts all active users; Viio ignores blocked users. Unblock or delete duplicates to align numbers. |
Self‑managed connection times out | Confirm your instance is reachable over HTTPS from the public internet. |
Technical Details
Auth methods: OAuth 2.0 or Personal Access Token (read_api, read_user).
Endpoints called (GitLab REST API v4):
GET /api/v4/users– fetch membersGET /api/v4/license– fetch seat countsGET /api/v4/projects?statistics=true– capture activity metrics (for future features)
Viio operates read‑only; it never creates, edits, or deletes GitLab data.
Data is refreshed every 24 hours
Additional resources
GitLab personal access tokens – https://docs.gitlab.com/user/profile/personal_access_tokens/