Installation

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

1. Access to a GitLab instance
2. An account that may create projects and manage members in the target group
3. 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.

Creating a Personal Access Token

1. Create one here

or

1. Navigate to your GitLab profile settings
2. Go to “Access Tokens”
3. Create a new token with required scopes
4. Save the token securely - you’ll need it during installation

Storage Requirements

• Minimum 1GB free disk space
• Additional space for repositories (varies by project size)

Network Requirements

• Stable internet connection
• Access to GitLab API endpoints
• No blocking firewalls for HTTP requests

Optional Requirements

• Docker: For running tests in containers
• Maven/Gradle: For Java project support
• IDE: Any Git-compatible IDE for development
• Java: Version 11 or higher (only required for UMLet diagram processing)

Installation

Guided Installation

The recommended path is the guided installer script. It downloads the latest matching release asset from the GitLab releases page, falls back to a source build when needed, and then runs divekit install --non-interactive to finalize the managed local setup.

# Install the latest available release for the current platform
curl -fsSL 'https://gitlab.git.nrw/api/v4/projects/divekit%2Fdivekit-cli/repository/files/scripts%2Finstall.sh/raw?ref=main' | bash

# Install a specific version
DIVEKIT_VERSION=v1.2.3 curl -fsSL 'https://gitlab.git.nrw/api/v4/projects/divekit%2Fdivekit-cli/repository/files/scripts%2Finstall.sh/raw?ref=main' | bash

# Install into a custom directory
DIVEKIT_INSTALL_DIR="$HOME/bin" curl -fsSL 'https://gitlab.git.nrw/api/v4/projects/divekit%2Fdivekit-cli/repository/files/scripts%2Finstall.sh/raw?ref=main' | bash

Useful references:

• Divekit CLI Releases
• Release assets for the latest version

Manual Installation

If you prefer to download a binary yourself, use the latest release assets directly:

1. Open Release assets for the latest version
2. Download the archive for your operating system and architecture, for example divekit-linux-x64.zip, divekit-darwin-arm64.zip, or divekit-windows-x64.zip
3. Extract the divekit binary
4. Run the local install step:

# From a local build or extracted release artifact
./divekit.exe install  # On Windows
./divekit install      # On Linux/macOS

By default, Divekit prefers ~/.local/bin on Unix when that directory already exists or is already part of your PATH; otherwise it falls back to ~/.divekit/bin. On Windows, the default location is %USERPROFILE%\.divekit\bin\divekit.exe. Divekit updates one shell startup file so that the managed directory is added to your PATH when needed. Set DIVEKIT_INSTALL_DIR to override that location.

Environment Setup

After installation, configure your GitLab hosts and tokens using divekit auth. Divekit prefers your operating system’s credential store for tokens (macOS Keychain, Windows Credential Manager, Linux Secret Service). If that is unavailable, it can also read matching environment variables, and in restricted environments it uses its internal fallback store.

DIVEKIT_MEMBERS is optional and defines the base directory for members files. If it is not set, Divekit uses ~/.divekit/members.

GitLab Host and Token Configuration

Use divekit auth to add/update GitLab instances. This records host configuration in ~/.divekit/hosts.json and stores the token under a host-specific secret key in the OS credential manager.

For advanced setups, divekit config hosts set writes the host entry and can either:

• store a token under the configured tokenAt key
• prompt interactively with --ask-token
• rely on an environment variable with the same key name

Steps

1. Create a Personal Access Token (if not already done):

   • Go to your GitLab profile > Access Tokens.
   • Create a token with api scope.
   • Copy the token.

2. Add the Host:

   # Recommended: interactive host/token setup
   divekit auth
   
   # Non-interactive host registration
   divekit auth git-nrw https://gitlab.git.nrw/ --token glpat-xxx...
   
   # Rotate token for an existing host (prompts for token)
   divekit auth git-nrw
   

   The token is stored securely by Divekit, preferably in the OS credential manager. When the interactive flow offers to open GitLab’s token page, the default answer is no; confirm it explicitly if you want Divekit to launch the browser.

How Token Lookup Works

When Divekit resolves credentials for a host, it checks these sources in order:

1. direct CLI token passed via --token
2. secret/keychain entry referenced by tokenAt
3. environment variable with the same key as tokenAt
4. host-derived default environment key such as DIVEKIT_API_TOKEN_GITLAB_COM
5. generic fallback DIVEKIT_API_TOKEN

For scripted runs, --token can also point at a token file by using a file:///absolute/path/to/token value. Divekit reads the file, trims surrounding whitespace, and uses the content as the token, which avoids putting the raw token directly into the shell command line.

Typical hosts.json entries look like this:

{
  "version": "1.0",
  "hosts": {
    "gitnrw": {
      "host": "https://gitlab.git.nrw/",
      "tokenAt": "divekit:auth:gitnrw:token"
    },
    "gitlabcom": {
      "host": "https://gitlab.com/",
      "tokenAt": "DIVEKIT_API_TOKEN_GITLAB_COM"
    },
    "local": {
      "host": "https://gitlab.local/",
      "tokenAt": "DIVEKIT_API_TOKEN"
    }
  }
}

Use the divekit:auth:... form for the normal keychain-first workflow via divekit auth. Use DIVEKIT_API_TOKEN_GITLAB_COM or a custom key when you want to manage tokens via environment variables or divekit config hosts set.

3. Verify:

   divekit doctor --verbose
   

Multiple Hosts

Add additional instances:

divekit auth gitlabcom https://gitlab.com/ --token glpat-yyy...

For advanced host options (for example custom token keys or per-host concurrency), use:

divekit config hosts --help

Member List Configuration

Members are the GitLab user accounts that should receive access to the repositories created for a distribution. A members file groups those accounts by UUID; each group usually represents one student or team repository. The file path is stored in config.json as members.path.

For terminology, see the Glossary and the members.json reference.

• DIVEKIT_MEMBERS: Optional environment variable for the default members directory (not a file path).

  Set it as a system environment variable:

  Linux/macOS

  Add to ~/.bashrc or ~/.zshrc:

  export DIVEKIT_MEMBERS="/path/to/members"
  

  Then:

  source ~/.zshrc
  

  Windows

  Add via System Properties > Environment Variables > User Variables:

  • Variable name: DIVEKIT_MEMBERS
  • Variable value: C:\path\to\members

  Alternatively, set per-distribution:

  divekit config origin set --distribution my-distribution --key members.path --value "$DIVEKIT_MEMBERS/my-distribution_members.json"
  

  Relative members.path values are resolved against the configured members directory.

Security Notes

• Tokens are stored in the operating system’s credential manager when available.
• If the keychain is unavailable, Divekit can still resolve tokens from environment variables and its internal fallback secret store.
• For non-interactive commands that need --token, prefer file:///... token files or CI secret variables over literal token arguments in shell history.
• ~/.divekit/hosts.json stores host metadata and token key references, not raw token values.
• Divekit creates ~/.divekit with private permissions automatically, so a manual chmod 600 ~/.divekit/hosts.json is usually not required.
• Use the api scope required by Divekit, and grant the token owner only the group and project permissions needed for the intended workflow.
• For CI/CD, use temporary tokens or pipeline secret variables.
• hosts.json is ignored in .gitignore by default.
• Prefer the keychain or CI secret variables over .env files for tokens.

Verify Installation

Run Doctor to verify your setup:

divekit doctor --verbose

Typical output looks like:

Doctor summary (run with --strict to fail on issues)

[✓] Divekit Home Directory - Divekit home directory is properly initialized
[✓] Configuration File - Configuration system is accessible
[✓] GitLab Connection & Token - GitLab connectivity OK
[✓] Environment - Environment info

No issues found!

Doctor checks:

• Divekit home directory and writable paths
• Configuration loading, including validation of local Divekit JSON files
• Reachability of configured GitLab hosts and token validity
• Basic runtime environment details (OS/arch, Go, Git)

Uninstall

Use the managed uninstall command to remove the binary and PATH configuration again:

# Remove the managed binary, PATH entry, and install manifest
divekit uninstall

# Also remove stored tokens and ~/.divekit
divekit uninstall --remove-tokens --purge-user-data

Default behavior is conservative:

• divekit uninstall removes the managed binary, PATH entry, and install manifest.
• ~/.divekit is kept unless you add --purge-user-data.
• Stored tokens are kept unless you add --remove-tokens.

Manual uninstall

Use the managed command above when possible. If the command is not available anymore, remove the same files manually:

# Find the active binary first
command -v divekit

# Remove the common Unix install locations
rm -f "$HOME/.local/bin/divekit"
rm -f "$HOME/.divekit/bin/divekit"

# Remove Divekit user data
rm -rf "${DIVEKIT_HOME:-$HOME/.divekit}"

On Windows, remove %USERPROFILE%\.divekit\bin\divekit.exe and %USERPROFILE%\.divekit. If you installed into a custom DIVEKIT_INSTALL_DIR, remove the divekit or divekit.exe binary from that directory instead.

Also remove the Divekit-managed PATH block from your shell startup file, for example ~/.zprofile, ~/.zshrc, ~/.bash_profile, ~/.bashrc, ~/.profile, or ~/.config/fish/config.fish:

# divekit managed path
...
# /divekit managed path

Stored GitLab tokens may still exist in the operating system credential store. Remove entries named for Divekit in Keychain Access on macOS, Windows Credential Manager on Windows, or your Secret Service/keyring tool on Linux.

For the full list of default paths, see Paths and Locations.

Troubleshooting

If you encounter any issues:

1. Run divekit doctor --verbose for detailed diagnostics Malformed Divekit JSON files such as hosts.json, config.json, or remotes.json are reported with file path plus line/column information.
2. Refresh host/token setup with divekit auth (interactive) or divekit auth <hostname> (token update)
3. Check tokens in the OS keychain:
   • macOS: Keychain Access app > Search for “divekit”
   • Windows: Credential Manager > Windows Credentials > Search for “divekit”
   • Linux: Check your Secret Service entries for service divekit
4. Check logs in ~/.divekit/logs
5. If needed, inspect advanced host settings via divekit config hosts list