OP#7546 Icinga Check für ablaufende Gitlab tokens https://projects.iml.unibe.ch/work_packages/7546

docs/20_Checks/check_gitlab_tokens.md

@@ -4,12 +4,36 @@
 
 **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`. 
+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
 
@@ -18,7 +42,7 @@ Extract or Git pull the Bash REST API client somewhere in your filesystem. eg. /
 ______________________________________________________________________
 
 CHECK_GITLAB_TOKENS
-v0.1
+v1.0
 
 (c) Institute for Medical Education - University of Bern
 Licence: GNU GPL 3
@@ -26,7 +50,7 @@ Licence: GNU GPL 3
 https://os-docs.iml.unibe.ch/icinga-checks/Checks/check_gitlab_tokens.html
 ______________________________________________________________________
 
-Check gitlab tokens and warn if a token expires soon.
+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
@@ -34,8 +58,11 @@ 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 [-w WARN_LIMIT] [-c CRITICAL_LIMIT]
+check_gitlab_tokens [OPTIONS]
 
 OPTIONS:
 
@@ -53,30 +80,36 @@ PARAMETERS:
 
     None.
 
-EXAMPLE:
-    check_gitlab_tokens -w 28 -c 7
+EXAMPLES:
 
-```
+    check_gitlab_tokens -w 28 -c 7
+        Set other warning and critical level
 
-### Parameters
+    check_gitlab_tokens -g ./gitlab.cfg
+        Set a custom gitlab config file
 
-Add directories to check.
-Set a directory that is writable for world or prepared to be accessible for the icinga user.
+    check_gitlab_tokens -r /opt/bash-api-client/bash-api-client.sh
+        Set a custom gitlab config file
 
-## 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`:
+## Example
 
-```shell
-GITLAB_API='https://gitlab.example.com/api/v4'
-GITLAB_TOKEN='glpat-1234567890'
-```
+The execution of  `check_gitlab_tokens` returns
 
-You can use another filename for this configuration - but then you need the parameter `-g <FILE>`to reference it.
+* 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
 
-## Example
+```text
+OK: 16 Gitlab Tokens (max 395 days old) .. critical: 0 (10 days) .. warnings: 0 (30 days)
 
-`check_gitlab_tokens -r /opt/rest-api-client/rest-api-client.sh`
+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>
+...
+```
\ No newline at end of file