divekit run

Run an extension across repositories

Synopsis

Execute an extension on all repositories in a distribution.

Runs a custom extension on each repository, enabling batch operations like code analysis, automated testing, or data extraction across all student submissions.

Extension Resolution

  • By name: Looks in .divekit/scripts/run/<extension>
  • By path: Direct path to extension file (./scripts/custom.lua)

Supported Engines

  lua       Lua scripts (.lua)
  sh        Shell scripts (.sh, .bash)
  python    Python scripts (.py)
  node      Node.js scripts (.js, .mjs)
  deno      Deno TypeScript (.ts)
  go        Go programs (.go)
  java      Java programs (.java)
  kotlin    Kotlin scripts (.kt, .kts)

ENVIRONMENT VARIABLES (available in extensions):
  DIVEKIT_DISTRIBUTION    Distribution name
  DIVEKIT_REPO_UUID       Current repository UUID
  DIVEKIT_REPO_PATH       Path to repository
  DIVEKIT_RESULT_FILE     Result file for the current repository run
  DIVEKIT_RESULTS_DIR     Results directory for the full extension run

Lua Workflows

  Lua extensions can either use the legacy per-repository form:
    return function(dk) ... end

  Or register a workflow at top level:
    dk.run.prepare(function(ctx) ... end)
    dk.run.each(function(repo) ... end)
    dk.run.cleanup(function(ctx) ... end)

  prepare runs once before repository processing. each runs once per selected
  repository. cleanup runs once at the end, also after prepare/each failures.
  Lua extensions executed by divekit run are local code execution and may use
  standard Lua os/io APIs such as os.execute.

External Workflows

  Non-Lua extensions run once per repository by default. If the extension path
  is a directory containing workflow.json, Divekit treats it as a
  workflow folder. The manifest selects runtime and entry file, and Divekit
  calls prepare(ctx), each(repo), and cleanup(ctx) functions when they exist.
  Workflow folders can contain normal project files such as package.json,
  node_modules, go.mod, or helper modules next to the entry file.

Output Formats

  ndjson streams result objects as they are emitted. json, table, csv, and md
  are written after repository processing has finished.

Usage

divekit run [extension|path/to/extension] [flags]

Examples

# Run a named extension from .divekit/scripts/run/
divekit run analyze -d ST2M4

# Run an extension file directly
divekit run ./scripts/check-commits.lua -d ST2M4

# Fetch repositories first, then run an extension
divekit run analyze -d ST2M4 --fetch-first

# Run with parallel execution
divekit run analyze -d ST2M4 --workers 5

# Force Python runtime
divekit run ./script.py -d ST2M4 --engine python

# Run JavaScript with Bun and pass runner arguments
divekit run ./script.js -d ST2M4 --js-runner bun --runner-arg=--watch

# Run an external workflow folder
divekit run has_readme -d ST2M4

# Create a workflow extension in .divekit/scripts/run/
divekit run init has_readme --language python

# Output results as JSON
divekit run analyze -d ST2M4 --output-format json

# Output results as newline-delimited JSON
divekit run analyze -d ST2M4 --output-format ndjson

# Output results as a plain text table
divekit run analyze -d ST2M4 --output-format table

# Output results as CSV
divekit run analyze -d ST2M4 --output-format csv

# Output multiple result formats
divekit run analyze -d ST2M4 --output-format csv --output-format md

# Write result files to a custom directory
divekit run analyze -d ST2M4 --output-dir ./analysis-results

# Output results as a Markdown table
divekit run analyze -d ST2M4 --output-format md

Flags

-d, --distribution string         Distribution name
  -e, --engine string               Force runtime engine: lua|sh|node|deno|python|go|java|kotlin
      --fetch-first                 Fetch repositories before running an extension
      --js-runner string            JavaScript runner: node|bun|deno
      --output-dir string           Directory for run result files
      --output-format stringArray   Output format: json|ndjson|table|csv|md (repeatable, comma-separated values allowed)
  -r, --remote string               Remote repository URL (e.g. GitLab instance)
      --repos-dir string            Directory containing repositories (overrides cache)
      --runner-arg stringArray      Additional runtime argument (repeatable)
  -t, --token string                GitLab token or token file path (file:///...)
      --ts-runner string            TypeScript runner: deno|ts-node|node|bun|go-ts (default "deno")
  -w, --workers int                 Concurrent workers for per-repo execution (default 4)

Inherited Flags

-l, --loglevel string   log level (debug, info, warn, error, fatal) (default "info")
      --no-index          skip project index update
      --non-interactive   run in non-interactive mode (fails if interactive input is required)
  -y, --yes               assume yes/default for all prompts (non-interactive with automatic defaults)

Available Subcommands

  • init — Create a run workflow extension
divekit run init

Create a run workflow extension