Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Direction - GDK

Last reviewed 2021-01-16


The GDK team is responsible for the GitLab Development Kit (GDK). The GDK provides a self-contained GitLab environment, which can be run locally or in a virtual machine. It's useful for developers contributing to the GitLab project, or anyone needing to test, experiment with, or validate GitLab functionality.

This category is responsible for improving the usability and reliability of the GDK. The GDK is essential for locally developing and testing changes. It is used by nearly all of the product development organization at GitLab as well as our community of contributors and partners.

It is therefore critical to optimize this experience for two reasons: productivity gains made through tool enhancements have compounding returns, and it makes it easier to get started contributing.

In the longer term, the vision is for the GDK to be a simple, reliable, and flexible tool that allows everyone to contribute. Developers should be able to keep their local development environment up-to-date painlessly, designers should be able to quickly check out a branch and validate a feature they designed, and everyone using the GDK should be running few commands to achieve this, and experience a highly-performant local installation when they do so.

Target audience

The GDK serves as a simple way to set up a local development environment for working on GitLab. With that in mind, the target audience for the GDK is anyone who is contributing to the GitLab project. This includes:

GitLab is an Open Core product, and our community is central to the continued success of our mission. This means that tools that allow anyone to jump in and contribute are vital to keeping that momentum going.

Future Vision

We want to build towards a state in which any GitLab contributor can easily install and use the GDK with minimal effort. By "lowering the bar" to getting started, we allow our contributors to focus on designing and building our next great feature.

We're iterating toward a version of the GDK that can install in a single command, updates itself painlessly, and allows contributors to check out a feature branch with minimal effort.

Challenges to address

Getting started with the GDK is straightforward for GitLab employees because of the tribal knowledge and in-company training we do. We need to move that knowledge in to the documentation and the handbook to make it just as easy for anyone in the community to get ramped up.

Examining a specific branch is a central workflow for many of our personas. These users would benefit greatly from a minimal-fuss, no-configuration way to switch to a specific branch to verify various aspects of the application with high velocity.

Making GDK updates a smooth experience is a high-priority issue, as there are a large number of reports of breaks happening when upgrading. This makes it painful to upgrade and smoothly continue working, or (even worse) discourages developers from upgrading in a timely manner.

Getting help with the GDK isn't so bad for GitLab Team Members, since they can just join the #gdk (internal) Slack channel. This approach is not suitable for community members, and we need a better solution that works well for everyone (so that everyone can contribute.)

What's Next & Why

Adding gdk checkout <branch> for reviewing specific branches to make it simpler for users to check out a specific feature branch quickly and easily. Currently the process is fragile and poorly documented and introducing a simple, reliable command will make it easier for all involved.

Update the GDK Documentation to increase clarity particularly for new contributors. This will include reorganizing content to make it more discoverable and scannable, improving our "Preparing your computer" recommendations, and updating the documentation for the latest requirements and prerequisites.

Introduce gdk pristine command to allow contributors a way to get a potentially broken GDK back to a working state in a low-touch way.

Allow some services to be run under Docker - Convert "data-oriented" services to have the option of being run natively or via Docker to reduce the complexity of installing/upgrading indivdual services.

Include 'stale process' detection as part of gdk doctor. This has bitten us a few times recently with some existing services that were re-engineered. It would have been really helpful for gdk doctor to detect and suggest solutions when it detects potential conflicts with old services that were left running after an update.

What we are not doing

Integrating the GitLab Compose Kit (GCK). The GCK project is also building local development environment tooling, however, the architecture of the two approaches are fundamentally incompatible. See this note on that project's readme for more information.

Why is this important?

The GDK is key to our Strategy, as the GDK is the entrypoint to contribution to the GitLab project itself. Without the GDK, many contributors would have to learn the specifics of every service that a local environment must run to function, the commands required to run each of those services, and the order they must be stood up in to function properly. They'd have to run these commands manually, or more likely, write some tooling that automates the process for them… which after significant amounts of time and effort were put in to those scripts, it would probably look a lot like the GDK.

Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license