Category Direction - GDK

Stage Create
Maturity Viable
Last reviewed 2020-07-28

This direction is constantly evolving, and everyone can contribute:


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 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 is Not Planned Right Now

Working on the GitLab Compose Kit (GCK). The GCK project is also building local development environment tooling, however with an aim of allowing users to spin up a container-based environment that only runs the bare minimum of services required to maximize performance and ease of use. Whatever the future may hold, the current standard for our developers is the GDK, which is where the focus of this category will remain for the time being.

We should investigate integrating/combining these two projects, but there are a few requirements (such as allowing some services to be run under Docker) that must be completed before we can even test this out. We're keeping these requirements in mind during planning, and are hoping to revisit this soon.

Why is this important?

The GDK is key to our GitLab's Strategy as it is the entrypoint to contribution to the GitLab project itself. Without the GDK, many contributors would have to learn the specifics of every required 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, they'd look a lot like the GDK.