Configuration

Divekit configuration is split across user-level and project-level files. This page focuses on how the configuration architecture is organized. Detailed JSON schemas, keys, and fallback rules now live under Reference.

1. Configuration Layers

Divekit uses three practical layers:

1. User-level defaults in ~/.divekit/
2. Project-level defaults in <origin-repo>/.divekit/
3. Distribution-specific overrides in <origin-repo>/.divekit/distributions/<distribution>/

The CLI resolves files from the most specific layer outward. This keeps shared defaults reusable while still allowing per-distribution overrides.

2. User-Level Configuration

~/.divekit/ stores machine-wide settings:

~/.divekit/
├── .env                    # optional env vars (for example DIVEKIT_MEMBERS)
├── hosts.json              # host aliases + secret/env key references
├── members/                # default base directory for members files
├── logs/                   # command logs and diagnostics
└── secrets/                # fallback secret store if no OS keychain is available

User-level files are typically about host authentication, reusable defaults, and machine-local fallback storage.

Reference pages:

• hosts.json
• Paths and Locations

{
  "version": "1.0",
  "hosts": {
    "gitnrw": {
      "host": "https://gitlab.git.nrw/",
      "tokenAt": "divekit:auth:gitnrw:token"
    },
    "gitlabcom": {
      "host": "https://gitlab.com/",
      "tokenAt": "DIVEKIT_API_TOKEN_GITLAB_COM"
    },
    "local": {
      "host": "https://gitlab.local/",
      "tokenAt": "DIVEKIT_API_TOKEN"
    }
  }
}

Advanced example with a custom key and concurrency settings:

{
  "version": "1.0",
  "hosts": {
    "gitlabcom": {
      "host": "https://gitlab.com/",
      "tokenAt": "MY_GITLAB_COM_TOKEN",
      "maxWorkers": 4,
      "rateLimitDelayMs": 250,
      "enableConcurrency": true
    }
  }
}

Notes:

• tokenAt is the lookup key for secrets, not the token value itself.
• divekit auth usually creates divekit:auth:<hostname>:token entries for keychain-first storage.
• divekit config hosts set defaults to a host-derived key such as DIVEKIT_API_TOKEN_GITLAB_COM unless --token-key is provided.
• At runtime, Divekit tries the configured tokenAt first, then a host-derived default key, then generic DIVEKIT_API_TOKEN.

3. Project-Level Distribution Configuration

Each origin repository keeps distribution-specific config here:

<origin-repo>/.divekit/distributions/<distribution>/
├── config.json             # primary distribution config (version 2.0)
├── remotes.json            # generated after distribution
└── individuals.json        # generated/updated during distribution

The architecture intentionally separates:

• authoring inputs such as config.json, variation.json, and individualization.json
• generated state such as remotes.json and individuals.json

Reference pages:

• config.json
• members.json
• variation.json
• individualization.json
• State Files
• Configuration Keys

members.path points to a members file with schema version 2.0. Each entry in groups creates one repository, and the uuid field is the identifier used for {{uuid}} in the repository name template. A group may contain one member or several members that share the same repository. Optional label and metadata fields provide group context for repository name templates such as {{label}}, {{slug}}, and {{metadata "key"}}.

{
  "version": "2.0",
  "groups": [
    {
      "uuid": "b8520e99-2bad-c0de-b61c-1249a10f7a5a",
      "label": "Team 01",
      "metadata": {
        "fruit": "banana"
      },
      "members": ["alice", "bob"]
    },
    {
      "uuid": "a70decaf-bad7-4c95-b211-d0bc95f48204",
      "members": ["charlie"]
    },
    {
      "uuid": "3631f4ea-f100-a320-b8aa-76e9c7b36266",
      "members": ["dana"]
    }
  ]
}

4. Resolution Strategy

The important architectural rule is specificity:

1. Distribution-level files override project-level files.
2. Project-level files override user-level defaults.
3. If no file exists, Divekit may fall back to code defaults.

This applies especially to variation.json, individualization.json, and members.path resolution.

See Paths and Locations for the exact lookup order.

5. CLI Commands for Configuration

# Authentication hosts (recommended workflow)
divekit auth
divekit auth git-nrw https://gitlab.git.nrw/ --token glpat-xxx...

# Advanced host configuration
divekit config hosts --help

# Distribution config
divekit config origin show -d ST2M4
divekit config origin set -d ST2M4 --key groupId --value 12345

# Effective merged config
divekit config explain

divekit config explain is the best command when you want to understand the effective merged configuration rather than only the stored files.

6. Runtime Overrides

Command flags can override stored configuration for a single run:

# Select project files interactively
divekit patch

# Override distribution selection at runtime
divekit patch -d ST2M4 src/main/java/Exercise.java

# Override log level globally
divekit patch --loglevel debug -d ST2M4 src/main/java/Exercise.java

# Reconcile eval Pages settings without patching files
divekit patch -d ST2M4 --disable-eval-pages-unique-domain

The --disable-eval-pages-unique-domain override is target-scoped: it only updates eval repositories recorded in remotes.json.

For evaluation-pipeline behavior, target layout, and linking details, see Evaluation Pipeline.