Set up your development environment

Development of the Linux package can be done using an existing package available from the Downloads page. To know how to set up a build environment to build these packages and use them, please read Setting up a Build Environment

Choose one of the GitLab installation methods below. To provide isolation and to prevent rebuilding of the package for each and every change, it is preferred to use a container for development.

Set up a container

  1. Install Docker for your OS as per the official Docker installation docs.

  2. Pull the GitLab CE nightly image: 

    docker pull gitlab/gitlab-ce:nightly

  3. Run the Docker image with a shell prompt: 

    docker run -it --publish 443:443 --publish 80:80 --publish 22:22 gitlab/gitlab-ce:nightly bash

    This command runs Docker with the GitLab nightly image. You start with a bash prompt, where you run the following commands.

  4. Initialize GitLab by first starting runsv, followed by reconfigure: 

    /opt/gitlab/embedded/bin/runsvdir-start &
gitlab-ctl reconfigure

    If you have sysctl errors after running reconfigure, there is a workaround in the common installation problems doc.

  5. (Optional) Take a snapshot of your container, so you can revert to this image if required. Run these commands on the Docker host: 

    docker ps # Find the container ID of our container.
docker commit <container_id> gitlab_nightly_post_install

Use an official nightly package

  1. Get the GitLab CE nightly package from the Nightly Build repository and install it using the instructions given on that page.

    note
    On Ubuntu Xenial, you may have to install tzdata. This issue is reported in #4769.
  2. Configure and start GitLab.
  3. Check if you can access the GitLab instance from your host browser on <ip address of host>.

  4. Install the basic tools used for developing Omnibus GitLab: 

    sudo apt-get install git

Get the source of Omnibus GitLab

  1. Get the source code of Omnibus GitLab from the repository on GitLab.com: 

    git clone https://gitlab.com/gitlab-org/omnibus-gitlab.git ~/omnibus-gitlab

    We will be doing the development inside the ~/omnibus-gitlab directory.

  2. Instructing GitLab to apply the changes we make to the cookbooks.

    During development, we need the changes we make to the cookbooks to be applied immediately to the running GitLab instance. So, we have to configure GitLab to use those cookbooks instead of the ones shipped during installation. This involves backing up of the existing cookbooks directories and symlinking the directories where we make modifications to its location: 

    cd ~/omnibus-gitlab/files/gitlab-cookbooks
for i in $(ls); do
  mv "/opt/gitlab/embedded/cookbooks/${i}" "/opt/gitlab/embedded/cookbooks/${i}.$(date +%s)"
  ln -s "$(pwd)/${i}" "/opt/gitlab/embedded/cookbooks/${i}"
done

    Now, you can make any necessary changes in the cookbooks inside ~/omnibus-gitlab/files/gitlab-cookbooks/ and run sudo gitlab-ctl reconfigure for those changes to take effect.

Run GitLab QA Against Your Development Environment

You can run GitLab QA tests against your development instance.

This ensures that your new work is behaving as expected, and not breaking anything else. You can even add your own tests to QA to validate what you are working on.

  1. Create a user account on your development instance for GitLab QA to use

    Then, from any machine that can reach your development instance:

  2. Clone the GitLab EE repository 

    git clone git@gitlab.com:gitlab-org/gitlab.git

  3. Change to the qa directory 

    cd gitlab/qa

  4. Install the required gems 

    bundle install

  5. Run the tests 

    GITLAB_USERNAME=$USERNAME GITLAB_PASSWORD=$PASSWORD bundle exec bin/qa Test::Instance $DEV_INSTANCE_URL

Trigger QA pipeline against deployed instance

If there is sustained network access to the deployed instance, you can trigger GitLab QA tests against the deployed instance using the GitLab QA Executor project. It contains CI configuration to run GitLab QA against self-managed GitLab environments with parallelization.

Run specific chefspec tests

You can also test your changes against the current tests (or to test your newly added tests).

  1. Install bundler and ruby-dev, which are required to build the necessary gems: 

    sudo apt install bundler ruby-dev

  2. Change to the omnibus-gitlab directory: 

    cd ~/omnibus-gitlab

  3. Install the required gems inside the omnibus directory: 

    /usr/bin/bundle install --path vendor/bundle

    If you use the GitLab Nightly Docker images, /opt/gitlab/embedded/bin is prepended to the $PATH, so using bundle alone uses the binary that is included as part of GitLab. That’s why we use the absolute path to the system bundle.

  4. Run your desired tests. The tests may need to run as root, as they need access to read the secrets file: 

    sudo bundle exec rspec spec/<path_to_spec_file>

Use chef-shell with omnibus-gitlab cookbooks

You can use chef-shell to debug changes to the cookbooks in your instance.

As root in your development server run: 

/opt/gitlab/embedded/bin/cinc-shell -z -c /opt/gitlab/embedded/cookbooks/solo.rb -s -j /opt/gitlab/embedded/cookbooks/dna.json

Use Customers Portal Staging in GitLab

To connect your GitLab instance to Customers Portal Staging, you can set the following custom environment variables in /etc/gitlab/gitlab.rb by supplying them in a gitlab_rails['env'] hash. Set:

  • GITLAB_LICENSE_MODE to test
  • CUSTOMER_PORTAL_URL to https://customers.staging.gitlab.com

For example: 

gitlab_rails['env'] = {
    "GITLAB_LICENSE_MODE" => "test",
    "CUSTOMER_PORTAL_URL" => "https://customers.staging.gitlab.com"
}
note
For GitLab Geo, deployments using the above configuration must be added to each secondary site.

OpenShift GitLab Development Setup

See Omnibus GitLab development setup documentation.