How Divekit Works

Follow authored course content through distribution, student work, evaluation, and reporting.

Divekit turns one maintained course origin into individualized repositories and keeps the resulting distribution operable throughout an assignment. This page explains what is authored, what Divekit generates, and which boundaries need care before a real cohort is involved.

You can operate Divekit through its CLI or its web interface. Both use the same origin and distribution model.

From Origin To Results

flowchart LR
    MAINTAINER((Course maintainer))
    ORIGIN["Authored origin<br/>course files + .divekit/"]
    MEMBERS["Member input<br/>kept outside the origin"]
    DIVEKIT["Divekit<br/>CLI or web interface"]
    STATE["Generated distribution state<br/>individuals.json + remotes.json"]
    LOCAL["Local provider output"]
    WORK["GitLab work repositories"]
    STUDENT((Students))
    EVAL["GitLab eval repositories"]
    PLUGINS["Pinned plugin suites"]
    RESULTS["Plugin results<br/>reports + feedback"]

    MAINTAINER --> ORIGIN
    ORIGIN --> DIVEKIT
    MEMBERS --> DIVEKIT
    DIVEKIT --> STATE
    DIVEKIT --> LOCAL
    DIVEKIT --> WORK
    DIVEKIT --> EVAL
    STUDENT --> WORK
    WORK --> EVAL
    PLUGINS --> EVAL
    EVAL --> RESULTS
    RESULTS --> STUDENT
    RESULTS --> MAINTAINER

1. Author The Course Once

The origin repository is the maintained source for an assignment. It contains the course files and .divekit/ configuration that describe distribution, individualization, and optional evaluation behavior. Variation choices and individualization rules are authored inputs too.

The members file is an input to a particular rollout, not course content. Keep it outside the origin so names or account identifiers cannot become part of every generated repository by accident.

2. Resolve A Distribution

A named distribution combines the origin defaults with its own settings and member input. Divekit resolves that configuration, selects a concrete variation for each UUID, and prepares the target-specific repository contents.

During this process Divekit writes generated distribution state:

individuals.json records the concrete selections assigned to each UUID.
remotes.json maps each UUID and target to the repository that Divekit created or manages.

These files make later operations such as patch, fetch, overview, and passcheck refer to the same repositories and assignments. Inspect them when diagnosing a distribution, but do not maintain them as authoring inputs.

3. Inspect Locally Or Write To GitLab

The local provider creates complete repository trees under .divekit/local-data/ without creating GitLab projects. It is useful for checking individualization, target selection, and generated CI files before a real rollout. The generated trees can still contain individualized or sensitive content, so local output needs the same care as an exported repository.

A GitLab-backed distribution creates or updates projects, assigns members, and records the remote mappings. The work target is the student-facing repository. When Evaluation Pipeline is enabled, Divekit also creates a paired eval target for separated CI and evaluation.

4. Students Work In The Work Repository

Students clone, edit, and push the individualized work repository. They should receive only the role needed for the assignment. Hidden evaluation material belongs in the paired eval repository rather than in the work repository.

5. Evaluate And Report

A push to the work repository can trigger the paired eval pipeline. The eval pipeline obtains the current work state, combines it with evaluation-only material, and runs the configured build and analysis jobs.

From Divekit CLI v2.45.0, a plugin suite supplies one build ecosystem and a compatible, pinned set of analysis plugins. Those plugins produce report data, feedback, and other artifacts inside the evaluation workflow. Divekit can aggregate this state for course maintainers, while generated GitLab Pages can present selected feedback to students. CLI v2.44.0 and earlier use the legacy flat plugin workflow. See Plugin Suites for the versioned setup workflow and Plugins for current and legacy usage.

Know The Different Kinds Of State

Kind	Owned by	Purpose
Authored origin content	Course maintainer	Defines course files, distribution settings, individualization, and evaluation inputs.
Member input	Course maintainer or institution	Maps synthetic or real GitLab accounts to stable distribution UUIDs. It stays outside the origin.
Generated distribution state	Divekit, stored with the distribution	Records concrete selections and remote mappings for follow-up operations.
Local provider output	Divekit, on the operator machine	Provides generated repository trees for inspection without GitLab changes.
Work repositories	Students and course staff	Hold the individualized, student-facing assignment and its Git history.
Eval repositories	Course staff and CI	Hold separated evaluation material, CI configuration, and evaluation state.
Plugin-produced results	Evaluation pipelines	Provide analysis results, report inputs, feedback, and artifacts.

Privacy And Trust Boundaries

Origin To Generated Repositories

Origin content can cross into many repositories in one operation. Keep member lists, access tokens, exports, and unrelated files outside the origin. Review the operation plan and generated local output before distributing to GitLab.

Operator Machine To GitLab

The operator machine holds authentication material, member input, local output, and generated distribution state. Keep tokens in the credential locations used by divekit auth, not in the origin. A GitLab token gives Divekit the authority of its owner, so use the narrowest account role that can perform the intended workflow. See GitLab Permissions.

Repository And Pages Access

Work repositories can contain student identities and submitted work. Eval repositories can additionally contain hidden tests, pipeline credentials, and evaluation results. Keep both targets private unless publication is a deliberate workflow using synthetic identities and sanitized content. Check GitLab project membership and Pages access separately because a feedback page has its own publication boundary.

Plugin Execution

Evaluation plugins process student work inside CI. Use trusted plugin sources and review intended updates before changing the versions locked by a suite. The lock makes the chosen implementation reproducible, but the source decision still determines which code receives the evaluation input.

Contributor Architecture

This site owns the durable product model for course maintainers. Go package layout, service boundaries, GUI server details, and other implementation architecture are maintained with the CLI source:

Last modified August 13, 2026: docs: add operator guidance and example origins (2cc9812)