Omnibus GitLab developer documentation

Setting up development environment

Check setting up development environment docs for instructions on setting up a environment for local development.

Understanding the architecture

Check the architecture documentation for an full description of the various components of this project, and how they work together.

Writing tests

Any change in the internal cookbook also requires specs. Apart from testing the specific feature/bug, it would be greatly appreciated if the submitted Merge Request includes more tests. This is to ensure that the test coverage grows with development.

When in rush to fix something (eg. security issue, bug blocking the release), writing specs can be skipped. However, an issue to implement the tests must be created and assigned to the person who originally wrote the code.

To run tests, execute the following command (you may have to run bundle install before running it) 

bundle exec rspec

Merge Request Guidelines

If you are working on a new feature or an issue which doesn’t have an entry on the Omnibus GitLab issue tracker, it is always a better idea to create an issue and mention that you will be working on it as this will help to prevent duplication of work. Also, others may be able to provide input regarding the issue, which can help you in your task.

It is preferred to make your changes in a branch named <issue number>-<description> so that merging the request will automatically close the specified issue.

A good Merge Request is expected to have the following components, based on their applicability:

  1. Full Merge Request description explaining why this change was needed
  2. Code for implementing feature/bugfix
  3. Tests, as explained in Writing Tests
  4. Documentation explaining the change
  5. If Merge Request introduces change in user facing configuration, update to gitlab.rb.template
  6. Changelog entry to inform about the change, if necessary.
noteEnsure shared runners are enabled for your fork in order for our automated tests to run:
  1. Go to Settings -> CI/CD
  2. Expand Runners settings
  3. If shared runners are not enabled, click on the button labeled “Enable shared Runners”

Validating changes to a single software dependency

It can be useful to only build one piece of software, rather than rebuild the whole package each time. For instance, when adding a new software definition. Using this method, you can quickly rebuild an omnibus package containing only the software and its dependencies. Once you’ve confirmed the software builds on its own, you can add it to the Omnibus GitLab build and confirm it there. To use this:

  1. Setup your development environment

  2. Copy the simple.rb file into your projects 

    cp doc/development/examples/simple.rb config/projects/
  3. Change the dependency in config/projects/simple.rb to match the software you are testing

  4. Build the simple project by running 

    bundle exec omnibus build simple

Testing changes during install/upgrade

If you are working on changes to the install/upgrade process, and not the reconfigure process itself, you can use the scripts/repack-deb tool to quickly repack an existing GitLab deb with changes from your local branch. It will repack the existing deb file into a new deb containing the local content from

  • config/templates/package-scripts
  • files/gitlab-cookbook/
  • files/gitlab-ctl-commands
  • files/gitlab-ctl-commands-ee