Quick Start on Divekit

Hello there 👋

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

What is Divekit?

Divekit is a command-line tool for managing individualized programming assignments at scale. It helps educators create, distribute and evaluate programming exercises for large groups of students.

Visual overview: from origin to distributed repositories

Locally:

my-assignment/
├─ .divekit/
├─ src/$Vehicle$.java # placeholder - used by individualization
├─ tests_evalrepo/ # filter - excluded from work repos
└─ README.md

Gitlab: “Individualized repositories”:

gitlab.example.com/.../my-group/ # Work repositories (work target)
├─ my-assignment-4d2c0752-f400-4690-9bac-97c927e68e17/
│ ├─ src/Car.java # $Vehicle$ → Car
│ └─ README.md
├─ my-assignment-4d243142-292b-4b95-abbb-af13f102c857/
│ ├─ src/Bike.java # $Vehicle$ → Bike
│ └─ README.md
└─ my-assignment-8153ded6-ee91-4135-b59e-ace2625f83c3/
 ├─ src/Plane.java # $Vehicle$ → Plane
 └─ README.md

Gitlab: “Evaluation pipeline” (separate eval target)

Installation

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

Prerequisites

Before installing Divekit, ensure your system meets the following requirements:

System Requirements

Operating System: Linux, macOS, or Windows
GitLab: Access to a GitLab instance with API permissions

GitLab Setup

Access to a GitLab instance
An account that may create projects and manage members in the target group
A personal, project, or service-account access token with api scope

The api scope and the account’s GitLab role are independent. The token does not grant namespace permissions that its owner does not already have. A normal distribution does not require instance administrator access; the exact minimum group role depends on the group’s project-creation and member-management settings. See GitLab Permissions before configuring evaluation pipelines, Pages, cleanup, or subgroup creation.

Example Origins

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

Example origins are small assignment repositories that show how authored source files and Divekit configuration work together. Use this guide to choose a starting point, inspect the repository it generates, and identify which parts you must adapt before a real course rollout.

The source repositories live in the public Divekit example origins group. They are not copied into this documentation site.

Choose an example

Example	Best for	Demonstrates
Vehicle Workshop Origin	Learning the smallest useful Divekit workflow	One individualization axis, local validation, and a work-repository distribution
Shape and Color Origin	Comparing your result after the beginner course’s final exercise	Two independent individualization axes and consistent replacement in one file
Example Shop Origin	Exploring a more complete Maven assignment	Multiple related individualizations, work and eval repositories, an Evaluation Pipeline, tests, and plugin configuration

Start with Vehicle Workshop when you want to understand the files in an origin repo and the effect of one placeholder. Use Shape and Color after completing the beginner course exercise and before moving to Example Shop’s paired work and eval setup.

First steps

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

Create Your First Project

Create and open a new directory:

mkdir my-assignment
cd my-assignment

Initialize Divekit:

divekit init

What `divekit init` does

divekit init creates the base configuration for an origin repository and prepares your project for distribution workflows.

Typical structure after init:

my-assignment/
└── .divekit/
 └── distributions/
 └── <distribution>/
 └── config.json

For command details, see divekit init.

variation.json and individualization.json are optional and can be added at project level (.divekit/) or distribution level (.divekit/distributions/<distribution>/). To scaffold a starter variation config, use divekit inject --scope variation.

Individualization

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

Overview

Divekit individualizes repositories with three different files:

variation.json: defines available object, relation, and logic variants.
individualization.json (optional): defines replacement behavior and processing rules.
individuals.json (generated): stores the concrete selection per UUID.

Important: per-member or per-group selection is not configured via individualization.json keys like logicId, objectAssignments, or globalSettings. Those keys are outdated.

Configuration Files

`variation.json` (input)

Defines what can vary:

objects
relations
logic

Example:

{
 "objects": [
 {
 "ids": "Vehicle",
 "objectVariations": [
 { "id": "car", "type": "class", "name": "Car", "variables": { "Vehicle": "Car" } },
 { "id": "truck", "type": "class", "name": "Truck", "variables": { "Vehicle": "Truck" } }
 ]
 }
 ],
 "relations": [
 {
 "id": "ownership",
 "type": "association",
 "source": "Vehicle",
 "target": "Owner",
 "options": ["one-to-one", "one-to-many"],
 "variables": {}
 }
 ],
 "logic": [
 {
 "id": "algorithm",
 "type": "implementation",
 "location": "src/logic",
 "options": ["simple", "complex"],
 "variables": {}
 }
 ]
}

`individualization.json` (optional input)

Defines processing behavior. Current top-level keys are:

Evaluation Pipeline

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

What It Is

Evaluation Pipeline is Divekit’s two-repository mode for a single assignment UUID:

work repository: student-facing code repository
eval repository: evaluation repository

When enabled, distribution creates and links both repositories for each UUID.

What It Does

For each UUID, Divekit:

Creates the work and eval repositories (depending on your target/group layout).
Individualizes content per UUID (same UUID mapping across targets).
Injects evaluation-pipeline CI assets.
Links both repositories by setting cross-repository variables and tokens.
Configures trigger/job-token scope so pipelines can communicate.
Disables GitLab’s unique Pages domain setting on eval repositories when the provider supports project-level Pages settings.

Runtime Flow

flowchart LR
 A["Student pushes to work repo"] --> B["work .gitlab-ci.yml"]
 B --> C["Trigger eval pipeline"]
 C --> D["eval pipeline prepares test env"]
 D --> E["eval runs build/tests/plugins"]
 E --> F["reports/artifacts"]

Work-To-Eval Materialization

Student edits happen in the work repository, while tests and hidden evaluation material live in the eval repository. The repositories are separate. Distribution creates their initial contents, but enabling Evaluation Pipeline does not define how later student changes replace or merge into the eval checkout. When the eval pipeline starts, Divekit runs its internal eval setup, fetches the current work repository state, and applies .divekit/materialization.json in the eval repository.

Plugins

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

This page documents the flat plugin model of pre-suite origins. New courses enable a plugin suite instead; existing origins migrate to it.

What Plugins Do

Evaluation Pipeline plugins add optional CI modules to eval repositories. Typical examples are PMD, Surefire, or JaCoCo/PIT analysis plugins.

Each plugin has two main controls:

add (alias use): choose the source or project, optionally pin a ref, and enable the plugin
enable or disable: toggle whether the plugin runs after it has been configured

Use pin when you only want to change the Git ref for an already configured plugin.

Manual Feedback

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

Manual feedback lets course staff add direct notes to generated evaluation reports without changing plugin output. It is meant for human feedback such as “try extracting this into a helper” or “this applies to everyone in this milestone”.

Unlike plugin feedback, manual feedback is authored in the origin repository and then patched into generated eval repositories. The report renders it as a separate teaching-team thread, above generic plugin feedback.

Author Feedback

Use the interactive command when selecting a distribution or members manually:

Plugin Suites

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

Available from divekit v2.45.0; per-plugin wizards run from the suite since v2.47.0. Earlier releases use the flat plugin model documented in the command pages.

What A Suite Is

A plugin suite bundles one build ecosystem and everything that analyzes its output. The maven suite ships the build stage of the evaluation pipeline (the job and the container image that compiles a student project) together with the analysis plugins that run against that build: PMD, Surefire, JaCoCo/PIT. A gradle suite does the same for Gradle projects, and the custom suite is the generic fallback for courses that build something else.

Migrate To Plugin Suites

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

Available from divekit v2.45.0; earlier releases use the flat plugin model documented in the command pages.

Who Needs This

Origins that were set up before plugin suites list their plugins by a flat name such as pmd or jacoco-pit, without a suite in front of it. Those origins have to be converted once. An origin created with a current Divekit is already on the new model and needs nothing.

Distribution

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

Overview

divekit distribute creates individualized repositories from an existing distribution config. In a typical run it:

reads .divekit/distributions/<name>/config.json
creates repositories in the configured target group(s)
individualizes content for each UUID
assigns members and permissions
writes state files: remotes.json and individuals.json

If the evaluation pipeline is enabled, Divekit also creates the linked eval repositories.

Prerequisites

divekit init is a one-time setup step and does not need to be repeated before every distribution.

Member Aliases

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

Member aliases are useful when a local members file contains course-internal names, but the corresponding GitLab accounts use different usernames.

Keep GitLab usernames in groups[].members. Divekit uses those values for GitLab access, repository membership, distribute, patch, members list, overview, and the GUI. The optional displayNames map only controls how those members are shown locally.

Set an Alias

If a member currently appears as myname in members.json, but the GitLab username is myname_extern, set the alias before rerunning distribution:

Run Extensions

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

divekit run executes local extensions against repositories from a distribution. Typical uses are static analysis, report extraction, custom checks, or orchestration around external tools.

Before running an extension, make repositories available locally:

divekit fetch -d ST2M4

Then run an extension from .divekit/scripts/run/ or by path:

divekit run analyze.lua -d ST2M4
divekit run ./scripts/analyze.py -d ST2M4

Use --fetch-first when Divekit should fetch before executing:

divekit run analyze.lua -d ST2M4 --fetch-first

Simple Lua Extensions

A simple Lua extension returns a function. Divekit calls that function once for every selected repository.

Safe Rollout Checklist

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

Use this checklist before the first rollout to a real cohort and before a later patch that sends new content to student repositories. After completing it, you should have private repositories for the intended students, with only the required access and without an accidental copy of the cohort member list.

Before distribution

Confirm that groupId and any evaluation target point to the intended GitLab groups. Use a separate non-production group for the rehearsal.
Run the complete workflow once with a small members file containing only synthetic test accounts controlled by the course team. The --count option does not assign users, so it does not test access control.
Confirm that the target namespace permits private projects. For any existing or reused project, check its effective project visibility in GitLab. A private project inside a public group remains private, so inspect the project rather than inferring its visibility from the parent group.
Store the real members file outside the origin repo. Check that it is not tracked by Git and is not among the files that distribution can copy. DIVEKIT_MEMBERS can point Divekit at a dedicated members directory outside the origin repo.
Authenticate with divekit auth. Keep tokens out of the origin repo, committed configuration, shell history, and ordinary environment files. Prefer Divekit’s credential-store integration or a protected CI secret. Grant the token owner only the GitLab permissions required for this rollout.

The relevant distribution settings are described in the config.json reference. GitLab documents how project visibility affects who can see repository content.

Quick Start on Divekit

Hello there 👋

What is Divekit?

Visual overview: from origin to distributed repositories

Installation

Prerequisites

System Requirements

GitLab Setup

Example Origins

Choose an example

First steps

Create Your First Project

What divekit init does

Individualization

Overview

Configuration Files

variation.json (input)

individualization.json (optional input)

Evaluation Pipeline

What It Is

What It Does

Runtime Flow

Work-To-Eval Materialization

Plugins

What Plugins Do

Manual Feedback

Author Feedback

Plugin Suites

What A Suite Is

Migrate To Plugin Suites

Who Needs This

Distribution

Overview

Prerequisites

Member Aliases

Set an Alias

Run Extensions

Simple Lua Extensions

Safe Rollout Checklist

Before distribution

What `divekit init` does

`variation.json` (input)

`individualization.json` (optional input)