Configuration

The badge API is configured using a yaml configuration file with the name .badge-api.yaml. The program looks for this file in the current working directory and inside /etc/badge-api/.

The configuration file consists of several key sections, including:

• gitClients: Contains the configuration for connecting to git providers.
• badges: Defines the badges, their levels, checks, and associated thresholds.
• personalEmailDomains: A list of personal email domains (required by the elephant and bus factor check).
• remoteConfigUrl: URL to a remote configuration file (optional). Or REMOTE_CONFIG_URL environment variable.
• subsequentUseApiDomain: The domain of the subsequent use API

Git Clients Configuration

The gitClients section defines how the Badge API connects to GitLab repositories.

gitClients:
  - baseUrl: <git_server_url>
    tokenFile: <path_to_token_file>
    type: <git_server_type>
    maxRequestsPerSecond: <requests_per_second>

• baseUrl: The URL of your GitLab instance (e.g., 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 Permissions

The token is used to authenticate the badge API against the git provider API. For regular usage the token does not need any special permissions. It is only used because even for open source projects gitlab requires authentication for /member endpoints.

Nevertheless, there is a special case if you provide manual checks with a decision json file stored in a private repository. In this case, the badge api uses the provided token to access the json file as well (if the baseURL matches). For this operation the token needs to have at least the read_repository permission (project access token is fine as well). The same applies to svgUrls which are stored in private repositories.

The API identifies the correct token by the provided baseUrl and type in the configuration file.

Badges Configuration

The badges section defines various badges, their levels, and checks. A badge can have multiple levels, each with associated checks.

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>

Each badge can have different levels (e.g., bronze, silver, gold). For each level, there are checks that are applied to the project. A check can be based on the following types:

• COMMITS: Checks if the project has a minimum number of commits in a defined time range.
• ISSUE_REACTION_TIME: Measures the average time to respond to issues.
• BUS_FACTOR: Checks the number of maintainers involved.
• RELEASES: Checks the number of releases made in a specified period.
• ELEPHANT_FACTOR: Checks if multiple companies are contributing to the project.
• PACKAGES: Checks the number of packages released.
• CI_PIPELINES: Checks the number of successful CI pipelines.

Each check has a threshold with two optional parameters:

• min: Minimum value required (e.g., number of commits, maintainers).
• max: Maximum value allowed (e.g., issue response time).
• timeRangeInMonths: Time period (in months) to evaluate the project activity.

Example configuration

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

Manual check type

Besides the predefined checks there is a MANUAL check type. This type of check requires external input or decision-making, which cannot be automatically evaluated by the API based on predefined metrics like commits, issues, or releases. Instead, it relies on an external JSON file to guide the decision-making process.

Example of a manual check:

badges:
  - id: open-source
    description: This badge checks if a project is open source.
    levels:
      - name: gold
        svgUrl: https://gitlab.opencode.de/open-code/badgebackend/manual-badges/-/raw/main/badges/open-source.svg
        checks:
          - type: MANUAL
            decisionJsonUrl: https://gitlab.opencode.de/open-code/badgebackend/manual-badges/-/raw/main/badges/open-source.json
            description: Checks if a project is open source. This check is decided manually by the openCode team.

In this case, the decisionJsonUrl points to a file (open-source.json) that contains the rules or decision criteria for determining if a project is open source. The file is hosted on a GitLab server, and the Badge API will refresh it every 5 minutes.

The JSON file should have the following structure:

{
  "granted": <List of repository urls that are granted the badge>,
  "grantedRegex": <List of regex patterns that are granted the badge>,
}

Example decision JSON file:

{
  "granted": [
    "https://gitlab.opencode.de/open-code/badgebackend/badge-api",
    "https://gitlab.opencode.de/open-code/badgebackend/badge-frontend"
  ],
  "grantedRegex": [
    "https://gitlab.opencode.de/open-code/badgebackend/.*"
  ]
}

Remote Configuration

The remoteConfigUrl parameter allows you to specify a URL to a remote configuration file. This file will be fetched and used to override the local configuration. Only the badges and personalEmailDomains sections are respected from the remote configuration file. To update other values, a local file needs to be used.

The remote configuration file might contain the special string <badge-config-repo>. This value will be replaced with the remoteConfigUrl base path. This is useful to validate remote configuration from a different branch and pass the url via an environment variable.