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.
Installing Prerequisites
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 protected] -g
Installation
Next, clone the GDK repository:
cd /path/to/your/workspace
git clone [email protected]: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 protected]:example/gitlab-ce.git [email protected]:example/gitlab-shell.git [email protected]:example/gitlab-workhorse.git
The above 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 make update.
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.
Making changes
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 ./run again.
Running tests
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 suiterake specto run the rspec suiterake 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 testbundle 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.
