gdk

name	gdk
description	GitLab Development Kit (GDK) — local GitLab development environment. Use when the user mentions GDK, starting/stopping GitLab locally, running rails console, GDK services, or local GitLab development, or looking up something in the gitlab project. Keywords - gdk, gdk start, gdk stop, gdk update, gdk status, gdk reconfigure, local gitlab.

GitLab Development Kit (GDK)

GDK is the local development environment for GitLab. It lives at /Users/tomas/workspace/gl/gdk.

Network Setup

GDK uses a custom loopback alias for its hostname:

• Hostname: gdk.test
• Listen address: 172.16.123.1
• Web URL: http://gdk.test:8080 (NGINX-proxied)
• SSH: gdk.test:2222

A LaunchDaemon at /Library/LaunchDaemons/org.gitlab1.ifconfig.plist creates the loopback alias on boot. If services like gitlab-workhorse or sshd fail with bind: can't assign requested address, the alias is missing.

Diagnosis: ifconfig lo0 | grep 172.16 — if no output, the alias is missing.

Fix (requires sudo — ask the user to run these):

sudo ifconfig lo0 alias 172.16.123.1
# If daemon got unloaded:
sudo launchctl load /Library/LaunchDaemons/org.gitlab1.ifconfig.plist

After alias is restored (agent can do this): gdk restart gitlab-workhorse sshd

Admin Credentials

• Username: root
• Password: stromek23
• API token (root, api scope): source ~/.secrets/gdk → exports $GDK_TOKEN (and $GDK_RUNNER_TOKEN). Use for REST/GraphQL calls and for connecting the Duo CLI (GITLAB_TOKEN=$GDK_TOKEN GITLAB_URL=http://gdk.test:8080).

Configuration

Config file: /Users/tomas/workspace/gl/gdk/gdk.yml

Current config highlights:

• AI gateway enabled (http://gdk.test:5052)
• Duo workflow enabled
• NGINX enabled (GDK accessible at :8080)
• License provisioning enabled (Ultimate + Duo Enterprise)
• Vite enabled (webpack disabled)
• Topology service disabled
• mise enabled (asdf opted out)

To view all config: gdk config list To set a value: gdk config set <key> <value> After config changes: gdk reconfigure

Shell Requirement

The gdk command requires mise-managed Ruby. In non-interactive bash, mise isn't activated, so gdk fails with "You are using Ruby 2.6.10". Always run gdk commands through fish:

fish -c 'cd /Users/tomas/workspace/gl/gdk && gdk status'
fish -c 'cd /Users/tomas/workspace/gl/gdk && gdk start postgresql redis rails-web'
fish -c 'cd /Users/tomas/workspace/gl/gdk && gdk rails console'

Rails Console

Use heredoc to pipe Ruby commands. Output is noisy — filter with grep 'RESULT:':

fish -c 'cd /Users/tomas/workspace/gl/gdk && gdk rails console' <<'RUBY' 2>&1 | grep 'RESULT:'
puts "RESULT:answer: #{User.count}"
RUBY

Gotcha: If PostgreSQL shows too many clients already, restart postgresql + rails:

fish -c 'cd /Users/tomas/workspace/gl/gdk && gdk restart postgresql rails-web rails-background-jobs'

Common Commands

gdk start                    # Start all services
gdk stop                     # Stop all services
gdk restart                  # Restart all services
gdk status                   # Check service status
gdk update                   # Pull latest code + update dependencies + migrate DB
gdk reconfigure              # Regenerate config files after gdk.yml changes
gdk tail                     # Tail all service logs
gdk tail <service>           # Tail specific service logs
gdk doctor                   # Run diagnostics
gdk pristine                 # Reset caches/deps without deleting data
gdk kill                     # Forcibly kill all services (use when stop hangs)
gdk rails <command>          # Run Rails commands (e.g., gdk rails console)
gdk psql                     # PostgreSQL console (gitlabhq_development)
gdk open                     # Open GitLab in browser
gdk predictive               # Run tests/linters/coverage for local changes
gdk predictive --rspec       # Only RSpec tests
gdk predictive --jest        # Only Jest tests
gdk predictive --rubocop     # Only RuboCop on changed Ruby files
gdk predictive --yes         # Skip confirmation prompt
gdk switch <branch>          # Switch gitlab to branch + update services
gdk sandbox                  # Ephemeral database sandbox
gdk feature-flags            # List feature flags
gdk feature-flags reset      # Reset all to defaults

Services

GDK manages these services (via runsv):

Service	Purpose
postgresql	Database
redis	Cache / queues
praefect	Gitaly cluster manager
praefect-gitaly-0	Git storage
rails-web	GitLab Rails (Puma)
rails-background-jobs	Sidekiq workers
gitlab-workhorse	Git HTTP / reverse proxy
gitlab-http-router	HTTP routing
sshd	Git SSH access
vite	Frontend dev server
nginx	Reverse proxy (port 8080)
gitlab-ai-gateway	AI features gateway
duo-workflow-service	Duo workflow

Start/stop/restart individual services: gdk start <service> / gdk stop <service>

Logs

Service logs are in /Users/tomas/workspace/gl/gdk/log/<service>/current.

# Check why a service is failing
cat log/gitlab-workhorse/current | tail -20
cat log/rails-web/current | tail -20

CI Runners

GDK ships with 30 phantom instance runners in the DB (never contacted). To run CI jobs locally, you need a real Docker runner. See resources/duo-workflows.md for full setup.

Quick check: docker ps | grep gitlab-runner — if no output, the runner container isn't running.

colima start                              # Start Docker VM (if not running)
docker start gitlab-runner-hitl           # Start existing runner container
docker logs -f gitlab-runner-hitl         # Watch runner pick up jobs

SaaS Simulation Mode

The file /Users/tomas/workspace/gl/gdk/env.runit contains environment variables for all GDK runit services (rails-web, sidekiq, etc.). Key variable:

export GITLAB_SIMULATE_SAAS=1   # Web process acts as GitLab.com (SaaS)
export GITLAB_SIMULATE_SAAS=0   # Web process acts as self-managed

This only affects web processes — gdk rails console doesn't load env.runit, so Gitlab.com? and Gitlab::Saas.feature_available? return different values in console vs web. Always verify behavior through actual HTTP requests, not just the console.

When GITLAB_SIMULATE_SAAS=1:

• Controllers marked # EE:Self Managed (e.g. admin Duo settings at /admin/gitlab_duo/*) return 404
• SaaS-only features become available
• License behavior changes (Cloud Connector, CustomersDot integration)

Toggle it by editing env.runit and restarting rails: gdk restart rails-web rails-background-jobs

Troubleshooting

1. Services won't bind → Missing loopback alias (see Network Setup above)
2. Rails won't start → Check log/rails-web/current for migration errors; run gdk update or cd gitlab && bundle exec rails db:migrate
3. Stale state → gdk pristine resets caches without deleting data
4. Everything stuck → gdk kill then gdk start
5. Config changes not taking effect → gdk reconfigure after editing gdk.yml
6. WebSocket 403 on duo workflows → Workhorse origin check. See resources/duo-workflows.md "WebSocket Origin Gotcha"
7. Vite asset errors in DWS flows → Start vite: fish -c 'cd /Users/tomas/workspace/gl/gdk && gdk start vite'
8. Admin pages return 404 but console says settings exist → Check GITLAB_SIMULATE_SAAS in env.runit. Many admin pages (Duo settings, self-managed features) are gated by !Gitlab::Saas.feature_available?(:gitlab_com_subscriptions) and will 404 when SaaS mode is on. Console doesn't load env.runit so it won't reproduce the issue.

GitLab Source

The GitLab Rails app is at /Users/tomas/workspace/gl/gdk/gitlab/. This is a regular git checkout that GDK manages.

Testing an MR branch (gitlab, gitlab-ai-gateway, etc.)

Don't just git checkout an MR branch and restart services. A branch is usually based on an older master and pulls in unrelated migrations and gem/Gemfile.lock changes. Checking it out raw leads to rails failing to boot:

• Could not find <gem> in locally installed gems (Bundler::GemNotFound) → missing bundle install
• HTTP 500 with check_pending_migrations → unrun migrations from the branch base

Correct workflow — update GDK first, then rebase the branch on the freshly-updated master:

# 1. Update GDK: pulls latest code on all managed repos + bundle install + db:migrate + more
fish -c 'cd /Users/tomas/workspace/gl/gdk && gdk update'

# 2. Fetch + rebase the MR branch onto the updated master (in the relevant repo)
cd /Users/tomas/workspace/gl/gdk/gitlab
git fetch origin <mr-branch>
git checkout <mr-branch>
git rebase origin/master       # branch now sits on the same base gdk update just migrated

# 3. Only if the rebased branch adds NEW migrations of its own:
fish -c 'cd /Users/tomas/workspace/gl/gdk/gitlab && bundle exec rails db:migrate'

# 4. Restart the services that load the changed code
fish -c 'cd /Users/tomas/workspace/gl/gdk && gdk restart rails-web rails-background-jobs'

gdk update is the thing that runs bundle install and db:migrate for you — rebasing onto the just-updated master means the branch shares that already-migrated base, so step 3 is usually a no-op.

Which service to restart for which repo:

• gitlab/ (Rails, incl. ee/...workflow.rb agent privileges) → rails-web rails-background-jobs
• gitlab-ai-gateway/ flow configs / tools_registry.py / base.py → duo-workflow-service (the V1 Flow engine runs from this service, not gitlab-ai-gateway). Restart it after the gateway code is updated, not before.

Verify rails is healthy before testing: poll curl -s -o /dev/null -w '%{http_code}' -H "PRIVATE-TOKEN: $GDK_TOKEN" http://gdk.test:8080/api/v4/user until it returns 200 (502 = still booting, 500 = app error — check gitlab/log/development.log).

Feature Flags

Via Rails console:

gdk rails console
# Then: Feature.enable(:flag_name) / Feature.disable(:flag_name)

Application Settings

Common settings that block features in development. Check/change via Rails console:

# CI identity verification (blocks CI job creation)
Gitlab::CurrentSettings.ci_requires_identity_verification_on_free_plan
ApplicationSetting.current.update!(ci_requires_identity_verification_on_free_plan: false)

# Duo features
Gitlab::CurrentSettings.duo_features_enabled

# Duo Agent Platform (instance-level, needed for non-SaaS)
Ai::Setting.instance.duo_agent_platform_enabled
Ai::Setting.instance.update!(duo_agent_platform_enabled: true)

License / Subscription

See resources/license-debugging.md for debugging license activation issues, customers portal URL configuration, and activation troubleshooting.

AI Gateway / Duo Setup

See doc/howto/ai/_index.md for the full Duo setup guide (AI gateway, Duo Workflow, Runner, Knowledge Graph). See doc/howto/ai/gitlab_ai_gateway.md for AI gateway-specific config. API keys and auth config live in gitlab-ai-gateway/.env.

See resources/duo-workflows.md for Duo Workflow testing setup (CI workflows, DWS branches, permissions, add-on provisioning).

Duo Group

A gitlab-duo group (id: 96) exists with experiment_features_enabled and duo_features_enabled on. It contains a gitlab-duo/test project (id: 20) for testing Duo features. URLs:

• Group: http://gdk.test:8080/gitlab-duo
• Project: http://gdk.test:8080/gitlab-duo/test

GDK Documentation

Full docs are at /Users/tomas/workspace/gl/gdk/doc/. Key pages:

• doc/howto/local_network.md — loopback alias setup and persistence
• doc/configuration.md — all gdk.yml options
• doc/gdk_commands.md — full command reference
• doc/howto/ai/_index.md — AI/Duo setup (gateway, workflow, runner)
• doc/howto/ai/gitlab_ai_gateway.md — AI gateway config
• doc/troubleshooting/ — common issues