Konfigurationsdatei

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.