Configure GDK-in-a-box

If you want to contribute to the GitLab codebase and want a development environment in which to test your changes, you can use GDK-in-a-box, a virtual machine (VM) pre-configured with the GitLab Development Kit (GDK).

The GDK is a local development environment that includes an installation of self-managed GitLab, sample projects, and administrator access with which you can test functionality.

It requires 30 GB of disk space.

If you prefer to use GDK locally without a VM, use the steps in Install the GDK development environment

Download GDK-in-a-box

1. Download and install virtualization software to run the virtual machine:
   • Mac computers with Apple silicon: UTM. Select Download from GitHub.
   • Linux / Windows / Mac computers with Intel silicon: VirtualBox
2. Download and unzip GDK-in-a-box. The file is up to 10 GB and might take some time to download:
   • Mac computers with Apple silicon: UTM image
   • Linux / Windows / Mac: VirtualBox image
3. Open UTM or VirtualBox, add the virtual machine image, then start the virtual machine:
   • UTM: gdk.utm
   • VirtualBox: gdk.vbox
4. Continue to Use VS Code to connect to GDK in the VM.

Use VS Code to connect to GDK in the VM

View a demo video of this step.

1. Start the VM. You can minimize UTM or VirtualBox.

2. In VS Code, select Terminal > New terminal and run a curl command that executes a script to add an SSH key to your local ~/.ssh/config:

   curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/gdk-in-a-box/setup-ssh-key" | bash

   To learn more about the script, you can examine the setup-ssh-key code.

3. In VS Code, install the Remote - SSH extension:

   • VS Code
   • VSCodium

4. Connect VS Code to the VM:

   • Select Remote-SSH: Connect to host from the command palette.
   • Enter the SSH host: debian@gdk.local

5. A new VS Code window opens. You can close or minimize the old window to avoid confusion.

   Complete the remaining steps in this section in the new VS Code window.

6. In the VS Code terminal, run a curl command to run a script to configure Git in the GDK:

   curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/gdk-in-a-box/setup-git" | bash

   • Enter your name and email address when prompted.
   • Add the displayed SSH key to your profile.

   To learn more about the script, you can examine the setup-git code.

7. In VS Code, select File > Open folder, and go to: /home/debian/gitlab-development-kit/gitlab/.

8. Open GitLab in your browser: http://gdk.local:3000.

9. Sign in with the username root and the password 5iveL!fe.

10. Continue to Change the code with the GDK.

Shut down GDK in the VM

You can select the power icon to shut down the virtual machine, or enter the shutdown command in the terminal. Use the password debian:

sudo shutdown now

Update GDK-in-a-box

You can update GDK-in-a-box while connected to debian@gdk.local in VS Code.

In the VS Code terminal, enter gdk update.

Change the code

After the GDK is ready, continue to Contribute code with the GDK.