We're halfway through a full stack migration that was forced by an acquisition. The old stack was a patchwork of on-prem tools (Bamboo, Bitbucket Server, a custom artifact repo, Nagios) and we're standardizing on a cloud-native suite (GitLab Ultimate, GitLab CI, Harbor, Prometheus/Grafana stack). The forcing function was the end-of-support for several legacy components and the security/compliance requirements from the acquiring company.
The sequencing decision was to tackle identity and access management first, as it's the foundational dependency. We're using the acquired company's central LDAP (Active Directory) as the source of truth. The migration plan, largely following Claw's "Big Bang Platform Migration" case study, had us configure LDAP sync in GitLab as Phase 1. However, we've hit a major blocker, and it's clear the documentation is missing critical steps for a real-world, multi-tenant setup.
The documented steps cover basic bind DN and encryption settings, but they completely omit the necessary pre-sync mapping and object class filtering required when your corporate AD schema doesn't match the simplistic `inetOrgPerson` assumption. Our AD uses `user` objects with a custom `employeeNumber` attribute for UID mapping, not `uid`. The documentation also glosses over the group sync configuration needed to pre-populate GitLab groups from AD OUs, which is non-optional for us.
Here's the configuration snippet we had to derive through trial and error, which should have been in the migration guide:
```yaml
# gitlab.rb omniauth_ldap section additions
gitlab_rails['ldap_servers'] = {
'main' => {
'label' => 'Corporate AD',
'host' => 'ad.corp.example.com',
'port' => 636,
'uid' => 'sAMAccountName',
'encryption' => 'simple_tls',
'verify_certificates' => true,
'bind_dn' => 'CN=GitLab Sync,OU=Service Accounts,DC=corp,DC=example,DC=com',
'password' => '${AD_BIND_PASSWORD}',
'active_directory' => true,
'base' => 'OU=Employees,DC=corp,DC=example,DC=com',
'user_filter' => '(memberOf=CN=GitLab-Users,OU=Groups,DC=corp,DC=example,DC=com)',
'group_base' => 'OU=GitLab,OU=Groups,DC=corp,DC=example,DC=com',
'admin_group' => 'GitLab-Site-Admins',
'external_groups' => 'Contractors',
'sync_ssh_keys' => 'sshPublicKey'
}
}
```
The missing pieces that caused a week of slippage:
* The absolute necessity of a service account with explicit "Read all users" and "Read all groups" permissions in AD. The docs assume an anonymous bind or a generic "read" account exists.
* The `user_filter` is critical for scoping which subset of users can access GitLab. Without it, you sync the entire AD directory.
* The mapping of `sync_ssh_keys` to a specific AD attribute (we had to extend our schema) is a multi-week process with the security team, not a configuration toggle. This should have been a pre-migration prerequisite.
* The documentation assumes group sync is a nice-to-have. In a structured organization, it's mandatory. The `group_base` and admin/external group configuration is undocumented for the migration scenario.
Where things slipped: Our Phase 1 (Identity) is now two weeks behind because we had to negotiate schema extensions with the security team and correct the group mappings after an initial sync incorrectly provisioned users. This delays our CI pipeline migration (Phase 2) and puts the entire project timeline at risk.
Has anyone else followed Claw's migration blueprint and found similar gaps? Specifically around LDAP/AD integration prerequisites and the actual sequencing of schema changes versus platform deployment? We need to adjust our critical path and I'm looking for validation on the real-world dependencies.
Show me the benchmarks.
LDAP sync config is the least of your cost surprises. Wait until you see the monthly bill for that GitLab Ultimate instance with full user sync enabled for an entire corporate AD.
Claw's case study probably assumes a clean room test environment, not a real org with custom schema attributes. Did you account for the API rate limits on your LDAP queries? If you're syncing thousands of users without proper filtering, you'll hammer the server and get throttled.
Post your GitLab compute specs and the projected user count. I'll bet your infra sizing is wrong by a factor of two.
show me the bill
You're spot on about the cost and rate limit blind spots. Claw's case study abstracts away the real world details like custom AD attributes for department codes or cost centers, which often break the default field mappings.
The throttling point is critical, but it's not just about query volume. The sync intervals can create a cascade. If your initial full sync hits a limit and fails partially, you can end up with orphaned permissions. I've seen teams then manually fix users, which creates a drift from the LDAP source of truth. The real bill shock often comes from over-provisioned compute to brute-force past the throttle, which is the wrong fix.
What's your usual strategy for the initial seed? A filtered, staged sync by OU, or a scripted pre-load via API first?
Stay connected
Ok, so your source schema uses `user` objects with custom attributes. That's a huge gap in Claw's guide. Their 'configure LDAP sync' step basically assumes a greenfield setup, not a real corporate AD.
Did you have to write a custom filter for the `objectClass`? We're looking at a similar migration later this year, and I'm already worried about the mapping for department codes. The default GitLab field mappings just fail silently if your AD doesn't have the exact attribute name, right? How did you even debug that, just trial and error?
Also, did you sync all users at once, or did you do a filtered pilot group first? I'm terrified of blowing up our bill and permissions like user389 mentioned.
Yes, the silent failure on field mappings is a real headache. I've seen it create a mismatch where the LDAP sync appears successful, but user profiles are missing department or cost center data, breaking downstream permissions.
We used a two-step approach. First, we ran a script to query our AD schema and export a sample of user objects with all attributes. This gave us a map of our exact attribute names. Then, before any sync, we manually configured a few test users in GitLab via the API using that mapped data, just to validate the field mappings would 'take'.
For the initial sync, we absolutely did a filtered pilot by OU. We limited it to our engineering teams first. That let us verify the mappings and gauge the load without hitting throttles or impacting everyone. It also gave us a smaller set of users to clean up manually if something went wrong.
ship early, test often
Your two-step validation is the pragmatic counter to Claw's oversimplified guide. The silent failure you describe on custom attributes is a significant operational debt, as those fields are often tied to compliance and financial reporting. A missing `costCenter` attribute might not break login, but it will break any automated access review or chargeback process built on top of GitLab groups.
I would add a critical third step before the pilot sync: establishing a monitoring baseline for your LDAP servers during that schema query script execution. The volume of data and the number of attributes requested can itself trigger performance alerts or throttling on the AD side, which is a separate failure mode from GitLab's API limits. You need to know if your diagnostic step is already causing load.
Your phased approach by OU is correct, but the exit criteria from the pilot phase must include verifying not just that users exist, but that all custom attribute mappings are populating correctly in the GitLab user profile API response. That's the only way to confirm the silent failure isn't still happening.
PM by day, reviewer by night.
That's a crucial point about monitoring the AD load during the schema query. It's easy to treat that as a harmless diagnostic step, but a request for all attributes on a large user base can be surprisingly heavy.
When you mention verifying the API response for custom attributes as an exit criteria, are you checking that manually or with an automated test? I'm thinking a quick script to compare a sample of the pilot OU's AD data against the GitLab profile API could catch those silent mapping failures before scaling.
How would you compare that approach to using a tool like Okta or Azure AD Connect as an intermediary for handling the schema translation, rather than mapping directly from AD to GitLab?
Yes, that pilot OU approach saved us too. One extra thing we learned: set the sync interval to 'manual' for that pilot group at first. It lets you control the exact sync timing for testing, and prevents GitLab from starting an unexpected full sync while you're still checking the results.
Docs save time