Reference on Divekit

Repository Name Templates

Mon, 01 Jan 0001 00:00:00 +0000

Repository names are configured with the optional top-level name key in a distribution’s config.json. Divekit renders the template once for every group in members.json. If name is omitted, the default is {{distribution}}-{{uuid}}.

{
 "name": "exercise-{{username}}"
}

Repository name templates use Go’s text/template syntax. This page documents the data and functions that Divekit provides for this specific use case.

Common Examples

Use the first configured GitLab username as the complete repository name:

Configuration Keys

Mon, 01 Jan 0001 00:00:00 +0000

This page summarizes the most relevant keys that users edit in current Divekit setups.

Distribution config.json

Key	Type	Notes
`version`	string	Use `"2.0"`.
`remote`	string	Host alias from `hosts.json`.
`groupId`	integer	Work distribution group ID.
`name`	string	Optional repository name template. If omitted, Divekit uses `{{distribution}}-{{uuid}}`.
`members.path`	string	Path to `members.json`.
`members.permissions`	string	Default permission level, usually `developer`.
`evaluationPipeline.enabled`	boolean	Enables the paired eval target.
`evaluationPipeline.groupId`	integer	Optional explicit eval root group.
`groupLayout.mode`	string	`distribution-subgroups` or `legacy`.
`groupLayout.rootGroupId`	integer	Optional explicit root group for derived subgroups.
`snapshot.remote`	string	Optional host alias used by `divekit snapshot` for writes. Defaults to the work target remote.
`snapshot.groupId`	integer	Optional snapshot root group used by `divekit snapshot`. Interactive runs can store this after you choose a root group.
`deleteExistingRepositories`	boolean	Deletes existing target repositories before distribution.
`scripting.languages`	array	Enabled languages for scripting/tooling.
`scripting.extensions`	object	File-pattern to language mapping.
`variables.variableDelimiter`	string	Start delimiter for token replacement.
`variables.variableDelimiterEnd`	string	Optional end delimiter.
`variables.values`	object	Fixed values shared across all UUIDs.

Notes:

GitLab Permissions

Mon, 01 Jan 0001 00:00:00 +0000

Divekit authenticates with a personal, project, or service-account access token. Two independent permission layers determine what the CLI can do:

the scopes attached to the token
the GitLab permissions of the account that owns the token

A broad token scope does not grant its owner additional access to groups or projects. A high group role cannot compensate for a token that lacks the needed API scope.

Token Scope

Current authentication and distribution workflows require the GitLab api scope. Divekit validates this scope during authentication. Additional read_api or write_repository scopes do not expand namespace access when api is already present.

Paths and Locations

Mon, 01 Jan 0001 00:00:00 +0000

This page summarizes the default file locations and path resolution rules used by the current CLI.

User-Level Paths

~/.divekit/
├── .env
├── bin/
├── divekit.db
├── gui-runs/
├── hosts.json
├── install.json
├── members/
├── scripts/
│ └── run/
├── logs/
└── secrets/

Notes:

bin/ is the fallback managed binary installation directory (divekit or divekit.exe).
divekit.db stores central local SQLite state such as managed GUI authentication data.
gui-runs/ stores per-origin SQLite run state for queued and executed GUI actions.
hosts.json stores host aliases and secret/env lookup keys.
install.json tracks the managed install location and PATH integration for divekit uninstall.
members/ is the default base directory for members files.
scripts/run/ contains extensions resolved by divekit run <name>.
scripts/ also contains built-in hook helpers such as Java transformers.
secrets/ is a fallback storage area when no OS credential manager is available.

Project-Level Paths

<origin-repo>/.divekit/
├── variation.json
├── individualization.json
├── local-data/
│ └── <distribution>/
│ ├── local/
│ │ └── <run-id>/
│ │ ├── <target>/<project>/repo
│ │ └── remotes.json
│ ├── gitlab/
│ │ └── <timestamp>/
│ │ ├── work/<uuid>/repo
│ │ ├── artifacts/<uuid>/pages/export.json
│ │ └── remotes.json
│ └── runs/
│ └── <timestamp>/
├── eval-pipeline/
│ ├── work/
│ │ ├── .gitlab-ci.yml
│ │ └── .gitlab/
│ │ └── ci/
│ │ └── divekit/
│ │ └── eval-trigger.yml
│ ├── materialization.json
│ ├── plugins.json
│ └── eval/
│ ├── .gitlab-ci.yml
│ ├── .divekit/
│ │ └── plugins/
│ │ └── <suite>/
│ │ └── <plugin>/
│ │ └── <result.path>
│ └── .gitlab/
│ └── ci/
│ └── divekit/
│ └── plugins/ (flat pre-suite plugins only)
│ ├── <plugin-id>.yml
│ └── <plugin-id>/
│ └── feedback/
└── distributions/
 └── <distribution>/
 ├── config.json
 ├── feedback/
 │ ├── _all.json
 │ └── <uuid>.json
 ├── variation.json
 ├── individualization.json
 ├── individuals.json
 ├── remotes.json
 └── eval-pipeline/
 ├── work/
 │ ├── .gitlab-ci.yml
 │ └── .gitlab/
 │ └── ci/
 │ └── divekit/
 │ └── eval-trigger.yml
 ├── materialization.json
 ├── plugins.json
 └── eval/
 ├── .gitlab-ci.yml
 ├── .divekit/
 │ └── plugins/
 │ └── <suite>/
 │ └── <plugin>/
 │ └── <result.path>
 └── .gitlab/
 └── ci/
 └── divekit/
 └── plugins/ (flat pre-suite plugins only)
 ├── <plugin-id>.yml
 └── <plugin-id>/
 └── feedback/

Resolution Rules

individualization.json

.divekit/distributions/<distribution>/individualization.json
.divekit/individualization.json
~/.divekit/individualization.json
built-in defaults

Variation definitions

.divekit/distributions/<distribution>/individualization.json
.divekit/distributions/<distribution>/variation.json
.divekit/individualization.json
.divekit/variation.json
~/.divekit/individualization.json
built-in defaults with no variations

Omitting variations from a unified file continues this lookup. An explicitly empty variation section stops it. The obsolete ~/.divekit/templates/variation.json is no longer a runtime fallback; current versions remove an unchanged managed copy during install/update and preserve a customized copy with a warning.

Environment Variables

Mon, 01 Jan 0001 00:00:00 +0000

This page lists the environment variables that are relevant in normal Divekit CLI usage.

User and Configuration Variables

Variable	Purpose
`DIVEKIT_HOME`	Overrides the base location used for `~/.divekit`-style user data resolution.
`DIVEKIT_MEMBERS`	Base directory used for `members.path` resolution when paths use `$DIVEKIT_MEMBERS/...`.
`DIVEKIT_API_TOKEN`	Default token key used by host entries when no host-specific token key is derived.
`DIVEKIT_API_TOKEN_<HOST>`	Derived host-specific token key, for example `DIVEKIT_API_TOKEN_GITLAB`.

Interaction Mode Variables

These are typically set by CLI flags, but they can also be set explicitly:

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

This glossary defines core Divekit terms used across Quick Start, Reference, and CLI docs.

Term	Definition
Divekit	Command-line tool for creating, distributing, and operating individualized programming assignments.
CLI	Command Line Interface. The primary way to use Divekit (`divekit ...`).
Personal Access Token	GitLab token used by Divekit to call the GitLab API for operations such as creating groups, repositories, and memberships.
Divekit Home Directory	User-level Divekit directory, usually `~/.divekit`, for local configuration, generated state, and fallback storage.
Origin Repository	Source repository containing assignment template files and `.divekit` configuration.
Distribution	Named setup in `.divekit/distributions/<name>/` that controls one rollout.
Distribution Config	`.divekit/distributions/<name>/config.json`, the main runtime config for distribution commands.
Target	Logical repository target in a distribution (for example `work` or `eval`).
Work Target	Student-facing code repository target (`work`).
Eval Target	Evaluation-pipeline repository target (`eval`) used for separated CI and evaluation flows.
Evaluation Pipeline	Optional paired `work`/`eval` model for separated CI and evaluation workflows. See Evaluation Pipeline.
Linking	Automatic connection between paired targets (variables/tokens/trigger URLs, job-token scope, UUID pairing).
Member	GitLab user account assigned to a distributed repository with a configured permission level.
Members File	JSON file referenced by `members.path`. It contains `groups`; each group has a stable `uuid` and the GitLab usernames that should receive access to that repository.
Members Directory	Base directory used to resolve members files. It is configured with `DIVEKIT_MEMBERS` and defaults to `~/.divekit/members`.
Group Label	Optional human-readable label on a members group. It can be used in repository name templates with `{{label}}` or as a GitLab-safe `{{slug}}`.
Group Metadata	Optional key/value metadata on a members group. It can be imported from member tables and used in repository name templates with `{{metadata "key"}}`.
UUID	Stable unique identifier used for one student/group repository pair across targets.
Individualization	Process of generating per-UUID content variants during distribution.
Variation Config	`variation.json` containing selectable object/relation/logic options.
Individualization Config	`individualization.json` containing delimiter, solution-deletion, warnings, file-manipulation and related rules.
Individuals File	`individuals.json`, generated state of concrete selections per UUID.
Remotes File	`remotes.json`, generated mapping of UUIDs to created remote repositories/project IDs.
Placeholder / Variable	Token in template files (for example $Vehicle$ ) replaced during individualization.
Host Alias	Named host entry in `~/.divekit/hosts.json` used by distribution targets (`remote`).
Provider	Backend used for execution, for example `gitlab`, `local`, or `simulated`.
Dry Run	Preview mode without remote changes (`--dry-run`, often via simulated provider).
Add Mode	`divekit distribute --add`: only process new UUIDs/members, keep existing distributed repos.
Fresh Mode	`divekit distribute --fresh`: rebuild distribution state files (`remotes.json`, `individuals.json`) while preserving stable repository indexes.
Fetch Snapshot	Timestamped GitLab repository snapshot under `.divekit/local-data/<distribution>/gitlab/<timestamp>/`, populated by `divekit fetch` or `divekit run --fetch-first` and reused by `run`/analysis commands.
Research Snapshot	History-stripped GitLab copy created by `divekit snapshot`. It contains the repository tree from distributed work repositories as one neutral initial commit, but it does not scrub UUIDs, names, paths, or file contents.
Local Provider Output	Filesystem distribution output under `.divekit/local-data/<distribution>/local/<run-id>/`, created by `divekit distribute -p local`.
Extension	A program executed across fetched or pulled repositories, typically via `divekit run`. Named run extensions live under `.divekit/scripts/run/`.
Run Workflow	Lifecycle extension form for `divekit run`. Lua workflows register `dk.run.prepare`, `dk.run.each`, and/or `dk.run.cleanup`; external workflow directories contain `workflow.json` and runtime functions such as `prepare`, `each`, and `cleanup`.
Plugin	CI plugin switch in evaluation-pipeline templates, executed in the eval pipeline and managed as described in Plugins.
Variable Extensions	`individualization.json -> variableExtensions`: token transformation rules (prefixes/suffixes/transformations). Not the same as runtime script extensions.
Inject	`divekit inject` command to scaffold default assets (CI templates, variation template, scripts).
Group Layout	Strategy for deriving work/eval groups (`distribution-subgroups` or `legacy`).