Logo

Troubleshoot your first rollout

Run Your First Distribution

Troubleshoot your first rollout

Build a small troubleshooting routine you can reuse whenever the first rollout looks wrong.

For beginner-level troubleshooting, these commands are enough:

divekit doctor
divekit dev
divekit config hosts list
divekit overview -d M0

You should also be ready to open these files directly:

  • .divekit/distributions/M0/config.json
  • .divekit/distributions/M0/individuals.json
  • .divekit/distributions/M0/remotes.json
  • .divekit/individualization.json

A simple troubleshooting order

When something looks wrong, debug in this order.

1. Re-check the environment

divekit doctor

2. Re-check the host setup

divekit config hosts list

If authentication looks suspicious, refresh it with:

divekit auth

3. Re-check the local individualization setup

divekit dev

4. Re-check the distribution config

Open .divekit/distributions/M0/config.json and verify:

  • remote
  • groupId
  • the optional name key, if you added one — without it, repositories are named M0-<uuid> by default

5. Re-check the generated state

Open individuals.json and remotes.json.

6. Re-check the remote result in GitLab

Compare the actual repositories with what the local state files claim.

This order moves from broad environment problems to concrete distribution state.

Quick diagnosis guide

Symptom First place to look Why
nothing was created doctor, host setup, groupId broad environment or target config failures come first
names look wrong config.json and overview naming mistakes usually show up before deeper state analysis
members are missing divekit members list and the member input you provided remote membership depends on valid input
content was not individualized divekit dev, template placeholder, individualization.json, individuals.json the problem is usually in the variation chain

Redo and clean up

You do not need these tools in the main beginner workflow, but you should know they exist.

--add

This distributes to configured members that are still missing from the existing distribution state, for example after adding them with divekit members add.

--fresh

This resets individuals.json and remotes.json before redistributing. It only touches the local state: repositories that already exist on GitLab are not deleted and become orphans.

A safe beginner rule is:

  • do not use --fresh unless you can explain exactly why the existing state should be rebuilt

divekit purge

This deletes the repositories of a distribution on GitLab. Divekit shows a deletion plan first and asks for confirmation.

Understand the scope before you ever use it: the plan is built from the target group, not from remotes.json.
purge lists every repository that currently exists in the configured group — including repositories that Divekit never created. Only repositories that GitLab has already scheduled for deletion are skipped.

That is safe in this course, because your target group contains nothing but the generated test repositories.
In real setups, point distributions only at groups that exclusively hold distributed repositories, and always read the deletion plan before you confirm.

Redo a botched first rollout

  1. delete the created repositories with divekit purge -d M0
  2. fix the actual problem in your config or individualization
  3. run divekit distribute -d M0 again — add --fresh only if you also want fresh local state and new individualization choices

Common failures

What to try
Check host setup, token validity, groupId, and whether local validation already indicated a problem.
What to try
By default, repositories are named <distribution>-<uuid>, so check the distribution name first. If you added an optional name key to config.json, check that pattern as well.
What to try
Inspect the configured members with divekit members list and check whether those identifiers are valid on the target GitLab environment.
What to try

Check divekit dev, placeholder spelling in the template, individualization.json, and individuals.json.

If individuals.json records the right choices but the repository content does not reflect them, compare the source files more carefully.

Check

Pick one of the following small changes and inspect the consequences carefully:

  1. add an optional name key such as "name": "project-{{uuid}}" to config.json, inspect the effect locally, then remove it again
  2. add one more variation option to individualization.json
  3. re-open individuals.json and compare it with overview
Suggested answer
config.json for target and naming changes, individualization.json for variation changes, and the generated state files (individuals.json, remotes.json) to see what a rollout actually produced.
Suggested answer
doctor is healthy, no unresolved placeholders remain, the host alias exists, config.json points to the intended host and group, and individualization.json matches the template placeholders.

Clean up your M0 test rollout

The two M0 repositories from this section were only a learning exercise.
Do not leave them on the shared GitLab instance — delete them now:

divekit purge -d M0

Divekit lists the repositories in the target group, shows a deletion plan, and asks for confirmation:

$ divekit purge -d M0

┃  # Deletion Plan
┃
┃  https://gitlab.git.nrw/your-group
┃  └─ work
┃     ├─ M0-b8520e99-2bad-c0de-b61c-1249a10f7a5a
┃     └─ M0-a70decaf-bad7-4c95-b211-d0bc95f48204

Are you sure you want to delete 2 repositories?

  Yes      No

Deleted repositories: 2/2
Deleted 2 repositories

Three details are worth knowing:

  • the plan covers the whole target group: purge would also list repositories in that group that Divekit never created, so read the plan before you confirm — if it shows more than your test repositories, answer No
  • depending on the instance settings, GitLab may keep the deleted repositories visible as scheduled for deletion for a while — that is GitLab’s delayed deletion, not a failed purge
  • purge only deletes the remote repositories; the local state files (individuals.json, remotes.json) stay untouched

This was also your first real divekit purge run.
The final exercise ends with the same cleanup step — from now on, treat it as part of every test rollout.