index.mdx

import { Callout } from 'nextra/components'

# Configuration

<Callout type="info">
  You can find the configuration file of the official instance [here →](https://gitlab.opencode.de/open-code/badgebackend/badge-api/-/blob/main/.badge-api.yaml)
</Callout>



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

### Git Clients Configuration

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

```yaml
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](#manual-check-type) 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.

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

```yaml
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:

```yaml
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 Open-Code 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 access it at **start time**.

The JSON file should have the following structure:

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

Example decision JSON file:

```json
{
  "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/.*"
  ]
}
```