How CodeScene Is Deployed: Architecture & Options for Enterprise Teams

Who this is for

This article is for platform, security and engineering leaders who are planning a CodeScene deployment for hundreds of developers. It explains what the components are, where they run, what data goes where, and how to size and secure an installation. For the people and process side of a rollout, see Rolling Out CodeScene Alongside AI Adoption: An Enterprise Onboarding Guide.

1. The components at a glance

A CodeScene deployment has two layers: A central analysis platform and developer tooling that runs where developers work.

Component	What it does	Where it runs
CodeScene platform (Cloud or On-Prem)	Runs the behavioural code analysis (Code Health, hotspots, knowledge and team insights, delivery metrics), along with dashboards, goals, PDF reports and the REST API.	CodeScene Cloud (SaaS) or your own server or private cloud
Pull Request integration	Automated Code Health reviews and quality gates on every pull request. It comments through your Git provider's API and never writes to your repository.	Part of the platform, connected to your Git provider
CodeHealth™ MCP Server	Gives AI assistants (for example GitHub Copilot, Claude Code, Cursor, Codex CLI, Kiro and Amazon Q) Code Health context so they write and refactor healthier code.	Locally on each developer's machine
CodeScene CLI	A deterministic local quality gate that runs as Git pre-commit hooks or AI agent hooks.	Locally on each developer's machine
IDE extensions	Real-time Code Health feedback and the Code Health Monitor while coding.	In the developer's IDE

2. Choose your platform: Cloud or On-Prem

	CodeScene Cloud	CodeScene On-Prem
Hosting	Fully managed SaaS with nothing to install	Self-managed Docker container on your own server or private cloud (AWS, Azure and others; also on AWS Marketplace)
Where your code lives	Repositories are cloned over HTTPS for analysis, and the local copy is deleted right after	Code and analysis results never leave your environment
Git providers	GitHub, Bitbucket, GitLab, Azure DevOps	Any Git remote, including self-hosted GitLab, GitHub Enterprise Server, Bitbucket Data Center and Gerrit
Access model	Git provider OAuth (GitHub, Bitbucket, GitLab, Azure DevOps), or Microsoft Entra ID SSO	Internal users, LDAP/Active Directory, or OAuth2/OpenID Connect, with role mapping from groups
Multiple Git orgs / business units	Each Git org (GitHub org, Bitbucket workspace, etc.) is a separate CodeScene org account. There’s no parent “enterprise” account, so SSO is configured on each account using the same settings.	One instance covers all your Git orgs and repositories, under a single SSO/LDAP configuration and role model.
Updates	Automatic	Pull a new Docker image when you choose to
Scaling	Handled by CodeScene	Single instance, sized by you (see section 4)
Air-gapped / offline	No	Yes, with offline mode
Best fit	A fast start with minimal operational effort	Strict security, compliance or data-residency requirements

Both options are used by large enterprises. CodeScene is ISO/IEC 27001 certified. If you're unsure which one fits, your CodeScene contact can help you decide.

3. Security and data flow

Source code. On Cloud, code is cloned for each analysis and the clone is deleted afterwards. On On-Prem, it never leaves your network. You can delete an analysis project at any time, and its data is removed.
Developer tooling. The CodeHealth MCP Server and CLI analyse code locally, against the developer's own repository. No source code or analysis data is sent to LLM vendors or any other external service. The only outbound calls are REST calls to your own CodeScene instance (Cloud or On-Prem) to fetch results such as hotspots and goals. Developers authenticate through a browser sign-in, or with a personal access token as a fallback.
Pull requests. CodeScene uses your Git provider's API to post review comments and statuses. Some providers (for example GitHub) require read/write scopes for this, but CodeScene never writes to the repository itself.
Telemetry (On-Prem). Limited to licence and utilisation data plus anonymised usage data. No personal identifiers or code are collected.
Network. CodeScene serves HTTP, so put HTTPS in front of it with a reverse proxy (such as nginx) or your cloud provider's certificate service. Proxy servers and self-signed certificates are supported. For allow-listing, see What IP Addresses Are Used by CodeScene?
Access control (On-Prem). Use LDAP/Active Directory or OAuth2/OIDC single sign-on, and map directory groups to roles: Admin, Architect, Manager, Technical Lead, Developer, Full Read-only Access, Bot and others. Project-level access can be granted per team.

4. Sizing On-Prem for hundreds of developers

Recommended setup: A plain Linux VM running the official codescene/codescene Docker image. Kubernetes is also supported: Mount a persistent volume at /codescene, expose port 3003 and use /health for probes.
Starting point for millions of lines of code and/or hundreds of developers: 8 vCPUs and 16+ GB RAM, with the Java heap tuned via -XX:MaxRAMPercentage or -Xmx. Needs grow with the size and history of the codebase.
Storage: Fast local SSD. Don't use shared or distributed file storage such as NFS, Azure Files or Amazon EFS which cause serious performance and stability problems.
Avoid: Serverless or managed container platforms that depend on distributed storage, such as Azure App Service, Azure Containers and AWS Lambda.
Single instance: CodeScene On-Prem doesn't run as multiple instances. Scale up rather than out and configure concurrent analyses to increase throughput.
Database: An embedded H2 database is the default. For enterprise installations, consider an external MySQL or MariaDB database ideally a managed service such as AWS RDS, so that backups and patching are handled for you.
Backups: Back up the database regularly. Cloned repositories and analysis results can be regenerated by re-running analyses.

5. Connect your toolchain

Git provider: Connect your repositories and enable the Pull Request integration (see Which Git Hosting Providers Does CodeScene Support?).
Project management: Connect Jira, Azure DevOps, Trello or ClickUp Boards to get delivery metrics such as planned vs unplanned work, lead times and defect trends.
Project creation at scale: Use the REST API to create projects and assign team owners from a developer portal or script (see Automating Project Creation for Frictionless Team Onboarding).
Developer tooling: Roll out the MCP Server, CLI and IDE extension with the 3-Step Developer Onboarding Guide. Point them at your instance (On-Prem uses CS_ONPREM_URL).

6. A typical enterprise deployment timeline

Week 0:
1. Decide and prepare. Choose Cloud or On-Prem. Complete the security review. For On-Prem, provision the VM, storage, database and HTTPS.
Week 1:
1. Install and connect. Activate the licence, configure SSO and roles, connect your Git provider and PM tool and create the first projects for your core systems.
2. First analyses. Configure teams and mark former developers, then record your baselines. This is also where the AI readiness assessment from the rollout guide starts.
Weeks 2-6:
1. Pilot. Enable the PR integration and developer tooling for one or two pilot teams.
Month 2 onwards:
1. Scale. Automate project creation and roll out team by team.

Planning a large deployment? Your CodeScene contact can run a deployment planning session with your platform and security teams.

Was this helpful?

Still need help? Ask the team