# Check Gitlab tokens

## Introduction

**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

* curl
* Bash REST API client<br>A set of class like functions with a http. prefix. <br>Docs: <https://os-docs.iml.unibe.ch/bash-rest-api-client/>

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`.

## Configuration

The script needs to connect to the Gitlab API.
You need to create a token in a admin group to read all tokens of all projects.

Put 2 bash variabbles into `/etc/icinga2/gitlab.cfg`:

```shell
GITLAB_API='https://gitlab.example.com/api/v4'
GITLAB_TOKEN='glpat-1234567890'
```

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

## Syntax

```txt
./check_gitlab_tokens -h
______________________________________________________________________

CHECK_GITLAB_TOKENS
v1.0

(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
    -r FILE        path to REST_CLIENT; default: ./../inc/rest-api-client.sh

    -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

```

## Example

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

```text
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>
...
```