Logo

Configure a GitLab host and token

Orientation and Setup

Configure a GitLab host and token

Connect Divekit to the GitLab host that later appears in your distribution config.

Later, your distribution configuration will refer to a host alias through the remote field in config.json.

That means Divekit needs:

  • a configured GitLab instance
  • a token for that host

Interactive setup

Run:

# Start the interactive host and token setup
divekit auth

In the normal course setup, gitnrw is already available in the instance list.
Select that instance, then create or paste a Personal Access Token with api scope when the CLI asks for it.

The important part for beginners is:

  • choose the correct instance
  • paste the token when prompted (right click & paste should work in most terminals)
  • let Divekit validate it

What the prompt flow looks like

A typical interactive flow looks roughly like this:

Select an instance:

●    gitnrw https://gitlab.git.nrw/
○    Register new instance...

Create a Personal Access Token with scope 'api':
https://gitlab.git.nrw/-/user_settings/personal_access_tokens?name=divekit&scopes=api

Access token:
******************************************************

┃   VALID   Personal Access Token 
┃                                 
┃  Name     divekit               
┃  Expires  2026-08-14 (29 days)  
┃

Two details in this flow are worth understanding:

  • the Expires line in the VALID box: a token that expires in about a month is normal for this course
  • a keyring warning may appear after validation — it means Divekit could not use the OS credential store and may fall back for this process

Refreshing an expiring token

If the token is close to expiry later, the beginner fix is simple:

divekit auth

Then select the instance again and enter a new token.

Verify the configured host

After setup, list your configured hosts:

# List configured hosts
divekit config hosts list

Then rerun doctor:

# Re-check the environment after authentication setup
divekit doctor

Example shape of a good result:

$ divekit config hosts list

Configured hosts

  name      gitnrw
  url       https://gitlab.git.nrw
  tokenKey  DIVEKIT_API_TOKEN_GITLAB_GIT_NRW

  Source: /Users/your-name/.divekit/hosts.json

$ divekit doctor
[✓] Divekit Home Directory
[✓] Configuration File
[✓] GitLab Connection & Token
[✓] Environment

Quick interpretation

What you see How to read it What to do next
a gitnrw host entry appears in config hosts list and doctor shows healthy auth Normal success state Continue to project setup
the host exists but doctor still reports auth trouble Instance is known, token is still wrong or expired Re-run divekit auth and enter a fresh token
you selected the wrong instance Setup mismatch Re-run divekit auth and choose the correct entry

Common failures

What to try

For this course, your token needs api scope.

If doctor still reports authentication problems, create a new token and refresh the setup with:

divekit auth
What to try

That warning is normal for a short-lived token.

It does not block the course as long as the token is still valid.

What to try

That is not fatal.

Just open the shown URL manually, create the token there, and paste it back into the CLI.

Check

Complete the host setup and verify it with:

divekit config hosts list
divekit doctor
Suggested answer
divekit config hosts list shows the gitnrw alias pointing to https://gitlab.git.nrw, and divekit doctor no longer reports missing credentials. If you intentionally use another GitLab instance, your configured alias and base URL should match that instance instead.
Suggested answer
Run divekit auth again, select the same instance, and paste a new token. Nothing else in your setup needs to change.
Suggested answer
Your distribution config will reference it through the remote field in config.json. If the alias is missing or wrong, every later command that talks to GitLab fails.