This post is part of a series Celebrating 1,000 Contributors
GitLab is built on open-source and has a thriving community. We appreciate all of our existing contributors and we look forward to welcoming new contributors, as well. This post is helpful if you've considered developing a feature or fix for GitLab but are unsure how to set up a development environment.
As with any Rails application, GitLab has a few moving parts: a database, Redis, Sidekiq, the Rails application server, GitLab Workhorse, and GitLab Shell. It can be a challenge to configure each of these components on your own. That's why we created the GitLab Omnibus packages for users, recently highlighted in another blog post. Perhaps not as well known is that we also have the GitLab Development Kit (GDK) to improve the experience for developers. In this post we'll go through the steps necessary to get GDK set up on your workstation.
All of the details here were obtained from the GDK README file, which is comprehensive and should be your first resource when you have questions.
First, you need to install some prerequisite items. Every platform has different requirements and we've outlined the steps for each in the 'Prerequisites for all platforms' section of the README. We have instructions for Mac, Ubuntu, Arch Linux, Debian, Fedora, and CentOS/Red Hat. For example, to install prerequisites for a Mac, run the following commands in Terminal:
brew tap homebrew/dupes brew tap homebrew/versions brew install git redis postgresql libiconv icu4c pkg-config cmake nodejs go openssl node npm bundle config build.eventmachine --with-cppflags=-I/usr/local/opt/openssl/include npm install email@example.com -g
Next, clone the GDK repository:
cd /path/to/your/workspace git clone firstname.lastname@example.org:gitlab-org/gitlab-development-kit.git cd gitlab-development-kit
Before configuring GDK, fork any GitLab repositories that you plan to contribute to. By default, GDK will install using the source repositories, such as
https://gitlab.com/gitlab-org/gitlab-ce.git. Community members do not have privileges in the main
gitlab-ce project so you will need a fork to submit merge requests. Here is a list of various GitLab repositories you may want to fork:
- GitLab CE - https://gitlab.com/gitlab-org/gitlab-ce
- GitLab EE - https://gitlab.com/gitlab-org/gitlab-ee
- GitLab Shell - https://gitlab.com/gitlab-org/gitlab-shell
- GitLab Workhorse - https://gitlab.com/gitlab-org/gitlab-workhorse
After forking any of the above repositories, you are ready to run the
make command to install all components. Be sure to tell
make about your forks. If you chose not to fork one or more repositories you can leave off the corresponding argument and GDK will use the source repository.
make email@example.com:example/gitlab-ce.git firstname.lastname@example.org:example/gitlab-shell.git email@example.com:example/gitlab-workhorse.git
make command installs and configures all components. Then, run
support/set-gitlab-upstream to automatically add an upstream remote in each cloned GitLab component. This will ensure that upstream changes are pulled in later when you run
Start GDK by executing
./run. All components will be started and output will be logged to the console. You can access GitLab in your browser at
http://localhost:3000 or press
Ctrl-C to stop all processes.
The various component repositories are all cloned inside the GDK directory. For example, GitLab code is checked out in
$GDK_HOME/gitlab. Change in to this directory and check out a new feature branch.
As you make changes you can refresh your browser to see the effects. In some cases, you may need to restart GDK to load the change. Restart by pressing
Ctrl-C and then execute
Some changes will require writing tests, or running existing tests to ensure you didn't break anything. GDK makes this very easy using the following commands:
rake spinachto run the spinach suite
rake specto run the rspec suite
rake gitlab:testto run all the tests
GitLab has a lot of tests and it can take a long time to run the full suite. Use the following command format to run tests in a single file:
bundle exec rspec spec/controllers/commit_controller_spec.rbfor a rspec test
bundle exec spinach features/project/issues/milestones.featurefor a spinach test
Opening a merge request
If all tests pass and you're ready to submit for review, commit the changes and push them to your fork. Then, visit GitLab.com and you should notice a banner near the top. Click the blue 'Create Merge Request' button to initiate a merge request. This will create a merge request from your fork to the GitLab source project so our team can review your contribution.
Congratulations! After installing the GitLab Development Kit you are well-equipped to contribute to GitLab. We're happy to welcome you to our community and look forward to your future contributions.
For more information on contributing to GitLab, please see our Contributing Guide.