Getting started

This page tells you how to get a development environment up and running so you can build, test, and run GitLab locally.

Recommended path: GitLab Development Kit (GDK)

The official tool for working on the monolith is the GitLab Development Kit. GDK installs and configures the dependent services (Gitaly, Shell, Workhorse, Postgres, Redis, etc.) and exposes a single gdk start/gdk stop/gdk update workflow.

Steps:

1. Install GDK following https://gitlab.com/gitlab-org/gitlab-development-kit#installation.
2. Clone this repo into the path GDK expects (gitlab-development-kit/gitlab/).
3. Run gdk install and then gdk start.
4. Visit http://gdk.test:3000.

GDK installation takes 30-60 minutes on a fresh machine. The README for the GDK lists prerequisites (Homebrew formulae on macOS, apt packages on Ubuntu) and known caveats per OS.

Manual installation (not recommended)

If you must bypass GDK, the official guide is at https://docs.gitlab.com/install/installation/. It is long and error-prone — most contributors use GDK.

One step you must remember when installing manually:

cp config/puma.example.development.rb config/puma.rb

without it Puma will not boot.

System requirements

From README.md:

• Ubuntu / Debian / CentOS / RHEL / OpenSUSE (production); macOS supported for local development
• Ruby (MRI) 3.3.10 — pinned in .ruby-version and .tool-versions
• Node.js — version pinned in .nvmrc
• Git 2.33+
• PostgreSQL 16.5+
• Redis 6.0+

The development tool versions are also captured in mise.toml for mise users, and in .tool-versions for asdf users.

Common commands

Once GDK is running:

# Run the Rails console
bin/rails console

# Run the full Rails app standalone (rare)
bundle exec rails server

# Run a single RSpec file
bin/rspec spec/models/project_spec.rb

# Run a single Jest test
yarn jest spec/frontend/path/to/file.spec.js

# Database migrations
bin/rails db:migrate
bin/rails db:rollback

# Generate the GraphQL schema
bin/rake gitlab:graphql:schema:dump

# Lint Ruby
bundle exec rubocop
bundle exec haml-lint

# Lint frontend
yarn lint:eslint
yarn lint:stylelint
yarn lint:prettier

# Run the Sidekiq cluster locally
bin/sidekiq-cluster '*'

Asset compilation

Webpack and Vite handle two different bundles:

• Main JS bundle: bin/webpack-dev-server (run by GDK automatically) or yarn webpack.
• Frontend islands: built with Vite (yarn vite / per-island scripts in scripts/build_frontend_islands).

A full production build is invoked via scripts/compile_assets.

Database setup

The repository ships three example database configs:

• config/database.yml.postgresql — single-database mode.
• config/database.yml.decomposed-postgresql — main + ci databases.
• config/database.yml.decomposed-sec-postgresql — main + ci + sec.

Pick one, copy to config/database.yml, and edit credentials. GDK does this for you.

The main schema dump is at db/structure.sql (~2.8 MB), and db/init_structure.sql contains the initial bootstrap state. There are 591 forward migrations in db/migrate/ and 946 post-deployment migrations in db/post_migrate/.

Workhorse

Workhorse is a separate Go binary that GDK builds automatically. To rebuild it manually:

cd workhorse
make

It is normally launched by GDK, sitting in front of Puma on port 3000.

Configuration files you will edit

File	Purpose
config/database.yml	Postgres connection settings
config/redis.yml	Redis (or copy redis.yml.example)
config/gitlab.yml	Application-level settings (host, paths, integrations)
config/secrets.yml	OmniAuth, key derivation, JWT secrets
config/feature_flags/development/<name>.yml	New feature flags during development

GDK creates working defaults for all of these.

Where to go next

• Development workflow — branch, MR, review.
• Testing — RSpec, Jest, Cypress.
• Debugging — logs, common errors.
• Patterns and conventions — service objects, finders, error handling.