Checks check gitlab tokens

Table of Contents

Check Gitlab tokens

Script: check_gitlab_tokens

check_gitlab_tokens checks all newer tokens of projects and groups if they expire soon. You can set a warning and a critical level in days.

Gitlab has an api requrest /personal_access_tokens but it doesn’t have the information about the project or usergroup where it is defined. This check executes additional requests to show it and offers the url to the web linkinterface.

The check returns

  • unknown - the http request to gitlab api failed
  • critical - min. 1 token is expiring soon
  • warning - min. 1 token reached the warning level (and no criritical token was found)
  • ok - api request was successful; no critical or warning token was found.

Requirements

Extract or Git pull the Bash REST API client somewhere in your filesystem. eg. /opt/bash-api-client/. With the parameter -r <FILE> you point to the file rest-api-client.sh.

Standalone installation

From this repository ypu need next to this script:

  • inc_pluginfunctions shared function for all IML checks written in bash

Configuration

The script needs to connect to the Gitlab API. You need to create a token

  • as an admin user
  • with api-read role

to read all tokens and all projects + users.

Put 2 bash variables for gitlab access and optionally the rest client into /etc/icinga2/gitlab.cfg. This file needs read permissions for the icinga client user only.

You can use another filename for this configuration - but then you need the parameter -g <FILE>to reference it.

variable Type Description
GITLAB_API string target url to the gitlab api
GITLAB_TOKEN string token of an admin user to read the api
REST_CLIENT string rest-api-client.sh as filename with full path or relative to the check_gitlab_tokens

Example:

# Gitlab access:
GITLAB_API='https://gitlab.example.com/api/v4'
GITLAB_TOKEN='glpat-1234567890'

# Rest API client
# REST_CLIENT='/some/where/rest-api-client.sh'

Hint:

If you need to skip the token check but the check was rolled out on a server then you can set GITLAB_TOKEN=SKIP. You can leave the other variables empty.

Syntax

./check_gitlab_tokens -h
______________________________________________________________________

CHECK_GITLAB_TOKENS
v1.1

(c) Institute for Medical Education - University of Bern
Licence: GNU GPL 3

https://os-docs.iml.unibe.ch/icinga-checks/Checks/check_gitlab_tokens.html
______________________________________________________________________

Check gitlab tokens and warn if tokens expire soon.

This check fetches the gitlbab tokens created in the last 395 days
from the Gitlab API. It skips

    - personal access tokens of users
    - revoked tokens

The script can run several seconds depending on count of tokens, projects
and users. Maybe you want to call it with a longer interval.

SYNTAX:
check_gitlab_tokens [OPTIONS]

OPTIONS:

    -h or --help   show this help.

    -w VALUE       warning level  (default: 30)
    -c VALUE       critical level (default: 10)

    -g FILE        path to GITLAB_CONFIG; default: /etc/icinga2/gitlab.cfg
                   There you can set/ override:

                     GITLAB_API='https://gitlab.example.com/api/v4'
                     GITLAB_CONFIG=<TOKEN>
                     REST_CLIENT="/opt/rest-api-client/rest-api-client.sh"

    -r FILE        path to REST api client
                   default: /opt/rest-api-client/rest-api-client.sh
                   The parameter overrides the variable REST_CLIENT.

    -s DAYS        Number of days for max age of token; default: 395

PARAMETERS:

    None.

EXAMPLES:

    check_gitlab_tokens -w 28 -c 7
        Set other warning and critical level

    check_gitlab_tokens -g ./gitlab.cfg
        Set a custom gitlab config file

    check_gitlab_tokens -r /opt/bash-api-client/bash-api-client.sh
        Set a custom gitlab config file

Output

The execution of check_gitlab_tokens returns

  • a status line with found tokens total, count of warning and critical
  • one line per token with
    • date of expiration
    • status; one of OK, warning, critical based on number of days before expiring
    • name of thwe token
    • name of the project or group
    • web link to the token page of the project or group
OK: 16 Gitlab Tokens (max 395 days old) .. critical: 0 (10 days) .. warnings: 0 (30 days)

2025-01-17  OK        changelog - demoproject <https://gitlab.example.com/test/demoproject/-/settings/access_tokens>
2025-01-23  OK        read_repo - demoproject <https://gitlab.example.com/test/demoproject/-/settings/access_tokens>
2025-03-14  OK        api_token - admin <https://gitlab.example.com/admin/sysadminstuff/-/settings/access_tokens>
...