divekit distribute

Creates multiple repositories on GitLab based on the Version 2.0 configuration in config.json.

Usage

divekit distribute [distribution-name] [flags]

Flags

• --base-url <url>: Base URL for the GitLab instance
• --token <value>: GitLab access token (required for GitLab provider)
• --distribution <name>, -d <name>: Specify which distribution to use (or as argument)
• --members-file <path>: Path to a file with member names (one per line)
• --add: Add users to an existing distribution
• --fresh: Delete remotes.json/individuals.json before distributing
• --message <text>, -m <text>: Commit message for initial commit
• --max-workers <int>: Maximum number of concurrent workers (0 = default: 3)
• --rate-limit-delay <duration>: Delay between GitLab API requests (0 = default: 100ms)
• --provider <type>: Provider to use: gitlab (default), local (filesystem), simulated (dry-run)
• --concurrent: Enable concurrent execution (default: true)
• --warn-unresolved-tokens <mode>: Warn about unresolved tokens: auto|true|false (overrides config)
• --dangerously-delete-group-projects: Enable deletion of existing projects without prompting (use with caution)
• --help: Show help information

Credentials

• Tokens are stored in your operating system’s credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service).
• Configure hosts via:

  divekit config set @hosts git-nrw https://gitlab.git.nrw/  # prompts for token and stores it in OS keychain
  

• The flags --token and --base-url are optional overrides. If omitted, Divekit resolves credentials and base URL from your configured hosts (hosts.json contains only host metadata and a token-key reference).

Description

The divekit distribute command creates individualized repositories for each student or group based on your configuration. It is idempotent, meaning it skips existing repositories and only processes new members. The command supports concurrent processing with configurable worker pools and automatic rate limit handling with exponential backoff.

Key features:

• Repository creation and configuration from origin templates
• Member permission assignment with validation
• Idempotent operations for safe re-execution
• Concurrent processing (default 3 workers)
• Automatic rate limit handling with exponential backoff (up to 5 retries)
• Custom commit message support
• Provider support (GitLab, local, simulated for dry-run)
• Individualization using variables and content variations
• Linking between code and sandbox repositories

The flow:

1. Validates the configuration and member data
2. Loads members from file or config
3. Creates code repositories in the specified GitLab group (or simulates)
4. Optionally creates secure pipeline repositories
5. Sets up repository linking between code and test repos
6. Assigns members with appropriate permissions
7. Applies individualization rules to content
8. Handles unresolved tokens with configurable warnings

Examples

Distribute with interactive confirmation

$ divekit distribute --distribution my-assignment

starting distribution (provider="gitlab", add=false, fresh=false, workers=3, concurrent=true, non-interactive=false, delete=false)
Loading configuration: ./.divekit/distributions/my-assignment/config.json
Resolving credentials from host config...

Pre-checks:
[√] Members loaded (27)
[√] Configuration valid
[√] Targets detected: main, test

Plan (summary):
- Create 27 code repositories in group #123456
- Create 27 test repositories in group #234567
- Link code→test repositories
- Assign members with role: developer

Continue? [y/N]: y

Creating code repositories...
Creating test repositories...
Linking repositories...
Assigning members...

Done.

Adding to existing distribution (latecomers)

$ divekit distribute --dirstibution my-assignment --add --members-file ./new-members.txt

What Gets Created

• Code Repositories: Main repositories where students work on their assignments, with individualized content
• Test Repositories: Optional secure repositories for automated testing (if securePipeline enabled)
• Repository Links: Automatic linking between code and test repositories
• Member Assignments: Students assigned with configured permissions (developer/maintainer)
• Initial Commits: With custom message and origin content variations