Konfigurationsdatei
Die Konfigurationsdatei der offiziellen Instanz finden Sie hier →
Die Badge-API wird mithilfe einer yaml-Konfigurationsdatei mit dem Namen .badge-api.yaml
konfiguriert. Das Programm sucht diese Datei im aktuellen Arbeitsverzeichnis
und in /etc/badge-api/
oder frag diese aus einem Git-Repository ab.
Die Konfigurationsdatei besteht aus mehreren Schlüsselabschnitten, darunter:
- gitClients: Enthält die Konfiguration für die Verbindung zu Git-Anbietern.
- badges: Definiert die Abzeichen, ihre Stufen, Prüfungen und zugehörigen Schwellenwerte.
- personalEmailDomains: Eine Liste persönlicher E-Mail-Domains (erforderlich für die Überprüfung des Elefanten- und Busfaktors).
- remoteConfigUrl: URL zu einer Remote-Konfigurationsdatei (optional). Oder die Umgebungsvariable
REMOTE_CONFIG_URL
. - subsequentUseApiDomain: Die Domain der API für die nachfolgende Verwendung
Git Clients Konfiguration
Der Abschnitt gitClients
definiert, wie die Badge-API eine Verbindung zu GitLab-Repositorys herstellt.
gitClients:
- baseUrl: <git_server_url>
tokenFile: <path_to_token_file>
type: <git_server_type>
maxRequestsPerSecond: <requests_per_second>
baseUrl
: Die URL Ihrer GitLab-Instanz (z. B., https://gitlab.opencode.de).tokenFile
: The file containing the access token (see Token Permissions).type
: The type of GitLab server (e.g., gitlab).maxRequestsPerSecond
: Maximum number of requests allowed per second to avoid rate-limiting.
Token Rechte
Ein Token wird verwendet, um die Badge-API gegenüber der API des Git-Providers zu authentifizieren. Für den regulären Gebrauch
benötigt der Token keine besonderen Berechtigungen. Er wird nur verwendet, weil GitLab selbst für
Open-Source-Projekte eine Authentifizierung für den Endpunkt /member
erfordert.
Es gibt jedoch einen Sonderfall, wenn Sie manuelle Prüfungen mit einer in einem privaten Repository
gespeicherten Entscheidungs-JSON-Datei bereitstellen. In diesem Fall verwendet die Badge-API das bereitgestellte Token
auch für den Zugriff auf die JSON-Datei (sofern die baseURL übereinstimmt). Für diesen Vorgang muss das Token mindestens
über die Berechtigung read_repository
verfügen (ein Projektzugriffstoken ist ebenfalls zulässig). Dasselbe gilt für
svgUrls
, die in privaten Repositorys gespeichert sind.
Die API identifiziert das richtige Token anhand der bereitgestellten baseUrl
und type
in der Konfigurationsdatei.
Badges Konfiguration
Im Abschnitt badges
werden verschiedene Badges, ihre Level und Prüfungen definiert. Eine Badge
kann mehrere Stufen haben, die jeweils mit Prüfungen verbunden sind.
badges:
- id: <badge_id>
description: <badge_description>
levels:
- name: <level_name>
svgUrl: <url_to_badge_svg>
checks:
- type: <check_type>
description: <check_description>
threshold:
timeRangeInMonths: <number_of_months>
min: <minimum_value>
max: <maximum_value>
Jede Badge kann verschiedene Stufen haben (z. B. bronze
, silver
, gold
). Für jede Stufe gibt es
Prüfungen, die auf das Projekt angewendet werden. Die verfügbaren Prüfungen finden Sie im Abschnitt
Implemnetierte Checks.
Jeder Check hat einen Schwellenwert mit zwei optionalen Parametern:
min
: Mindestwert (z. B. Anzahl der Commits, Maintainer).max
: Maximalwert (z. B. Antwortzeit auf Issues).timeRangeInMonths
: Zeitraum (in Monaten) zur Bewertung der Projektaktivität.
Beispiel Konfiguration
badges:
- id: maintained
description: This badge checks if a project is maintained.
levels:
- name: bronze
notNecessaryForNextHigherLevel: true
svgUrl: https://gitlab.opencode.de/open-code/badgebackend/badge-api/-/raw/main/assets/MAINTAINED-1.svg
checks:
- type: COMMITS
description: Checks if the number of commits during the last 6 month is greater than 5.
threshold:
timeRangeInMonths: 6
min: 5
- name: silver
svgUrl: https://gitlab.opencode.de/open-code/badgebackend/badge-api/-/raw/main/assets/MAINTAINED-2.svg
checks:
- type: ISSUE_REACTION_TIME
description: Checks if the average reaction time to issues is less than 7 days.
threshold:
timeRangeInMonths: 3
max: 7
- type: BUS_FACTOR
description: Checks if multiple maintainers are working on the project.
threshold:
timeRangeInMonths: 6
min: 1
- name: gold
svgUrl: https://gitlab.opencode.de/open-code/badgebackend/badge-api/-/raw/main/assets/MAINTAINED-3.svg
checks:
- type: RELEASES
description: Checks if the number of releases during the last 6 month is greater than 1.
threshold:
timeRangeInMonths: 6
min: 1
- type: ELEPHANT_FACTOR
description: Checks if multiple companies are working on the project.
threshold:
timeRangeInMonths: 6
min: 1
Remote-Konfiguration
Mit dem Parameter remoteConfigUrl
können Sie eine URL zu einer Remote-Konfigurationsdatei angeben. Diese
Datei wird abgerufen und verwendet, um die lokale Konfiguration zu überschreiben. Nur die Abschnitte
badges
und personalEmailDomains
werden aus der Remote-Konfigurationsdatei berücksichtigt. Um andere
Werte zu aktualisieren, muss eine lokale Datei verwendet werden.
Die Remote-Konfigurationsdatei kann die spezielle Zeichenfolge <badge-config-repo>
enthalten. Dieser
Wert wird durch den remoteConfigUrl
-Basispfad ersetzt. Dies ist nützlich, um die Remote-Konfiguration
von einem anderen Branch aus zu validieren und die URL über eine Umgebungsvariable zu übergeben.