Sourcegraph rollout plan: how do we pilot with one org/team, measure adoption, then scale company-wide with RBAC and SCIM?
AI Codebase Context Platforms

Sourcegraph rollout plan: how do we pilot with one org/team, measure adoption, then scale company-wide with RBAC and SCIM?

11 min read

Most teams don’t fail on the decision to buy Sourcegraph—they fail on the rollout. The reality: you’re dealing with thousands of repositories, multiple code hosts, and an access model that absolutely must line up with how your org already manages identity and permissions. A good rollout plan starts small, proves value with one org or team, then scales with the same rigor you apply to production systems—using SSO, SCIM, and RBAC from day one.

Below is the rollout approach I recommend after doing this in a regulated enterprise with a hybrid GitHub + Perforce footprint. It’s opinionated, but it’s designed to keep risk low, adoption measurable, and the company-wide expansion repeatable.

Quick rollout overview

Here’s the high-level sequence:

  1. Pilot design (2–3 weeks)

    • Pick the right org/team and code hosts.
    • Stand up Sourcegraph with SSO and basic RBAC.
    • Seed the instance with the right repos and branches.

  2. Pilot execution (4–6 weeks)

    • Run structured onboarding.
    • Focus usage on 3–4 core workflows.
    • Capture qualitative feedback and quantitative metrics.

  3. Adoption measurement

    • Track search usage and power-user behaviors.
    • Measure impact on specific migration/refactor/security use cases.
    • Use engagement and outcomes to decide “go” for scale-out.

  4. Scale-out foundation: SCIM + RBAC model

    • Align Sourcegraph roles to existing IAM groups.
    • Automate provisioning and deprovisioning with SCIM.
    • Normalize permissions across orgs/teams and code hosts.

  5. Company-wide rollout

    • Expand repository coverage and org onboarding.
    • Introduce Batch Changes, Monitors, and Insights for platform-wide workflows.
    • Lock in ongoing governance and ownership.

Phase 1: Design the initial pilot

1. Choose the right pilot org/team

You want a team with:

  • High pain from code sprawl
    • Owns or depends on hundreds of repositories.
    • Frequently jumps between GitHub, GitLab, Bitbucket, Gerrit, or Perforce.
  • A concrete initiative in flight
    • Migration off a monolith.
    • Framework or library upgrade across many services.
    • Security or dependency hardening effort.
  • Influence beyond their org
    • Tech leads who can write up wins.
    • Engineers others treat as internal references.

Good pilot candidates often include:

  • Platform/infra teams.
  • Developer productivity / internal tools.
  • A product org in the middle of a major refactor or migration.

Anchor the pilot on one or two crisp business goals. For example:

  • “Reduce time-to-answer for code questions about our payments stack.”
  • “Prove we can plan and execute a multi-repo framework upgrade using Batch Changes.”
  • “Catch insecure patterns and secrets in code before they ship via Monitors.”

2. Pick the initial code footprint

Resist the urge to index every repo on day one. Start with a deliberate subset:

  • Critical path repos
    • Core services owned by the pilot org.
    • Shared libraries they depend on.
  • Representative languages and tech stacks
    • Include at least 2–3 major languages you use.
  • Active branches
    • Index main/master plus the most active release or long-lived branches (multi-branch search becomes powerful quickly in complex environments).

You can grow from dozens to hundreds of repos during the pilot, but keep the initial scope tightly aligned to the pilot goals.

3. Integrate SSO before onboarding anyone

Don’t onboard users without single sign-on. You need a clean, enterprise-grade authentication story from day one.

Configure SSO with your identity provider using:

  • SAML
  • OpenID Connect
  • OAuth

Whichever path you choose, do this before you invite the first pilot user so:

  • Access is tied to your central identity.
  • Login flows are familiar.
  • You can confidently expand later without redoing the auth story.

4. Establish a minimal RBAC model

You don’t need a perfect permission model for the pilot, but you do need a sane baseline.

Start with:

  • Admin
    • A small core team (platform/DevEx + security) that can configure code hosts, RBAC, and org-level settings.
  • Standard user
    • Default role for engineers in the pilot org.
  • Read-only/limited roles (if needed)
    • For stakeholders who should see search results but not manage configuration.

Key practices:

  • Map roles to responsibilities, not people:
    • Admins: configure code hosts, Batch Changes, Monitors.
    • Users: search, navigate, create personal dashboards/queries.
  • Align repository visibility in Sourcegraph with your code hosts.
    • If a user can’t see a repository in GitHub/GitLab/Perforce, they should not be able to see it in Sourcegraph.

This is where your eventual RBAC design starts; you’ll harden and expand it in the scale-out phase.

Phase 2: Run a focused pilot

5. Do structured onboarding, not “self-serve”

Book explicit sessions with the pilot team.

Session 1 (60–90 minutes): Core code search

  • Why Sourcegraph exists in your environment:
    • Multi-repo sprawl.
    • Legacy + new code coexisting.
    • AI agents struggling to find the right context.
  • Live demos tailored to their repos:
    • Universal search across GitHub, GitLab, Bitbucket, Gerrit, Perforce, and more.
    • Searching for:
      • Function definitions and call sites.
      • Feature flags and config.
      • API usages across services.
    • Language-aware code navigation (go to definition, find references).
  • Hands-on queries:
    • Each engineer gets a list of 5 real questions they have about production code.
    • They answer those questions using Sourcegraph during the session.

Session 2 (60–90 minutes): Deep Search + AI and change workflows

  • Deep Search as agentic AI search:
    • Show how Deep Search gives clear, grounded answers for complex questions in your codebase.
    • Emphasize: zero data retention for LLM inference; answers always trace back to real files and lines.
  • Batch Changes basics:
    • Example: apply a logging library upgrade across 50+ services.
    • Preview diffs, get code reviews, batch-merge safely.
  • Monitors:
    • Set a couple of monitors on day one:
      • Detect secrets or high-risk patterns.
      • Flag usage of deprecated libraries.
  • Insights:
    • Create 1–2 dashboards tracking:
      • Adoption of new APIs.
      • Decline in deprecated patterns over time.

Record these sessions. You’ll reuse them for future org rollouts.

6. Focus usage on 3–4 core workflows

Broad “explore everything” pilots lose steam. Give the pilot team explicit workflows:

  1. Day-to-day code understanding

    • “Before you ask in Slack, search in Sourcegraph.”
    • Find function owners, call chains, and feature flags.
    • Investigate production incidents by tracing code across repos.

  2. Migration or refactor execution

    • Use Deep Search to:
      • Enumerate all call sites of a deprecated API.
      • Classify patterns that need different handling.
    • Use Batch Changes to:
      • Apply consistent edits across the identified repositories.
      • Manage reviews and rollout in waves.

  3. Security and compliance checks

    • Use Monitors to:
      • Alert on newly introduced risky patterns.
      • Track secrets or credentials accidentally committed.
    • Use Insights to:
      • Show progress in eliminating forbidden dependencies or insecure constructs.

  4. Support for AI coding agents

    • Expose Sourcegraph via MCP or similar integration so your agents can:
      • Search across all hosts and repos.
      • Retrieve definitive context before generating code changes.

Ask each pilot engineer to commit to using Sourcegraph for at least one of these workflows daily or weekly.

Phase 3: Measure adoption and outcomes

7. Track quantitative adoption

You want signals beyond “people like it.” For the pilot org, monitor:

  • Active users
    • Weekly active users (WAU).
    • DAU/WAU ratio (stickiness; target > 0.4 for strong adoption).
  • Search behavior
    • Number of searches per user per week.
    • Growth of “advanced” usage:
      • Filters, operators, pattern matching.
      • Language-specific queries.
  • Feature adoption
    • Deep Search sessions.
    • Batch Changes created and merged.
    • Monitors configured and triggered.
    • Insights dashboards viewed regularly.

You’re not just looking for high volume—you’re looking for repeated, habitual use in critical workflows.

8. Capture qualitative feedback

Run 30-minute feedback interviews with:

  • 3–5 senior engineers.
  • 1–2 tech leads.
  • 1 manager or PM.
  • 1 security or SRE partner (if applicable).

Ask:

  • “What questions about the codebase are now trivial that used to be hard?”
  • “What is the last thing you did in Sourcegraph that saved you real time?”
  • “Where did Sourcegraph surprise you—in a good or bad way?”
  • “If we turned this off tomorrow, what would break for you?”

Combine this with Slack/Teams channels dedicated to the pilot where people post:

  • Saved queries.
  • Interesting refactor wins.
  • Deep Search answers that unlocked a hard problem.

9. Tie usage to concrete outcomes

To justify company-wide rollout, connect usage to visible outcomes:

  • Incident investigation
    • Shorter MTTR because engineers can trace cross-service flows quickly.
  • Refactor/migration
    • Number of repositories updated via Batch Changes.
    • Time saved vs. manual search-and-edit.
  • Security posture
    • Issues caught by Monitors before deployment.
    • Reduction in certain patterns over time, as shown in Insights.

Document 3–5 concrete stories:

  • “We migrated X API across Y repos in Z days.”
  • “We found and fixed a risky pattern in 200+ files before it shipped.”
  • “We cut time spent searching for ‘where is this behavior implemented’ in half during incident reviews.”

These become your internal case studies when you pitch expansion.

Phase 4: Prepare for company-wide rollout with RBAC and SCIM

Once the pilot proves value, you shift to a platform mindset. This is where SCIM and a hardened RBAC model matter.

10. Formalize the role model

Move from ad-hoc roles to a clear, documented RBAC design, for example:

  • System admins
    • Manage Sourcegraph configuration, code hosts, and global policies.
  • Org admins / space owners
    • Manage repo groups, org-level Insights and Monitors.
  • Standard engineers
    • Full search and navigation across repos they’re allowed to see.
    • Use Deep Search, Batch Changes (within limits), and personal Monitors/Insights.
  • Read-only stakeholders
    • View results and dashboards; no configuration rights.

Align this model with how your IAM and code hosts think:

  • Map Sourcegraph roles to IdP groups: sg-admins, sg-org-admins-<org>, sg-users, sg-readonly.
  • Keep permissions consistent with GitHub/GitLab/Bitbucket/Gerrit/Perforce repo permissions.

11. Enable SCIM for automated provisioning

Manual user management doesn’t scale beyond one or two pilots. Use SCIM to:

  • Automatically provision users when they’re added to relevant groups in your IdP.
  • Automatically deprovision users on departure or role change.
  • Keep group memberships in sync, so access in Sourcegraph always mirrors your central truth.

With SCIM in place:

  • New engineers in a team automatically see the right repositories in Sourcegraph.
  • Changes in role/department propagate to Sourcegraph without manual admin work.
  • Your compliance story stays clean and auditable.

12. Refine governance and guardrails

Before expansion:

  • Confirm “Zero data retention” posture for LLM inference is documented and understood by security.
  • Validate that Sourcegraph respects:
    • Repo-level permissions from code hosts.
    • Role-based access controls (RBAC) definitions.
  • Decide on:
    • Who can create org-level Batch Changes.
    • Who can create global Monitors and Insights versus personal ones.
    • Audit log retention and review practices.

Treat Sourcegraph as a production platform:

  • Change management.
  • Owners defined.
  • On-call or escalation path if something breaks.

Phase 5: Scale Sourcegraph company-wide

13. Expand repository coverage and organizations

With SSO, RBAC, and SCIM solid:

  • Add the rest of your repositories and branches.
  • Ensure all code hosts are connected:
    • GitHub (cloud/on-prem).
    • GitLab.
    • Bitbucket.
    • Gerrit.
    • Perforce.
  • Confirm that “whether 100 or 1M repositories,” engineers see consistent, lightning-fast search.

Roll out org by org:

  1. Identify the next 2–3 orgs.
  2. Assign an internal champion per org (often a tech lead or architect).
  3. Give each org its own onboarding sessions (reusing pilot materials).
  4. Seed org-specific examples (migrations, security concerns, refactors).

14. Standardize cross-org workflows

Now you’re no longer just driving adoption—you’re standardizing how your company does code understanding, change, and governance.

  • Deep Search / Code Search as default
    • Bake Sourcegraph into incident docs (“Step 1: search for…”).
    • Add it to engineering onboarding checklists.
  • Batch Changes for planned changes
    • Mandate Batch Changes for:
      • API deprecations.
      • Shared library upgrades.
      • Policy enforcement rewrites.
  • Monitors for guardrails
    • Central security/platform teams maintain global Monitors for:
      • Secret patterns.
      • Known-vulnerable dependencies.
      • Disallowed packages or APIs.
  • Insights for visibility
    • Use Insights dashboards for:
      • Tracking migrations.
      • Showing progress on paying down tech debt.
      • Monitoring adoption of new patterns and practices.

15. Instrument ongoing success

At company scale, watch:

  • Org-level adoption
    • WAU per org.
    • Coverage: % of engineers using Sourcegraph monthly.
  • Workflow usage
    • Number of Batch Changes created and merged per quarter.
    • Monitors firing and resolved.
    • Insights dashboards referenced in reviews and planning docs.
  • Platform reliability
    • Search latency and error rates.
    • Impact on day-to-day development if Sourcegraph is degraded.

Turn this into a regular review with stakeholders from:

  • Platform/DevEx.
  • Security.
  • Eng leadership.

Decision triggers at each stage

To keep the rollout disciplined, define clear “go/no-go” triggers:

  • Pilot start → org-wide pilot

    • 60% of pilot engineers are weekly active.

    • At least one migration/refactor or security win attributable to Sourcegraph.
  • Org-wide pilot → multi-org rollout
    • Deep Search and Code Search usage embedded in incident and migration runbooks.
    • Stable SSO with SAML/OIDC/OAuth and basic RBAC in place.
  • Multi-org → company-wide
    • SCIM provisioning configured and running for at least one large org.
    • Role model and guardrails agreed with security and eng leadership.
    • Sourcegraph recognized as the default place to understand and change code at scale.

Final verdict

A successful Sourcegraph rollout isn’t about flipping a switch for thousands of engineers at once. It’s about:

  • Proving value with one org where code sprawl and cross-repo work are painful.
  • Measuring adoption with real workflows—Deep Search answers, Batch Changes merged, Monitors catching issues before they ship.
  • Layering in RBAC and SCIM early so you can scale from 100 to 1M repositories without losing control.

Do that, and Sourcegraph becomes more than a search box. It becomes your code understanding platform—for both humans and AI agents—with enterprise-grade governance and automation wrapped around it.

Next Step

Get Started

Back to AI Codebase Context Platforms

Keep Reading

More from AI Codebase Context Platforms

Sourcegraph MCP Server: what’s required to run a pilot connecting our internal AI agents to permissioned code search and code navigation?

Read more

How do we use Sourcegraph Batch Changes to open and track PRs across hundreds of repos for a dependency upgrade or API migration?

Read more

How do we set up Sourcegraph SSO (SAML/OIDC) and SCIM provisioning with Okta or Entra ID for a 1,000+ developer rollout?

Read more