Skip to main content
Running Devin across an enterprise means managing environments for dozens of organizations and hundreds of repositories. This page covers the patterns that work well at scale, and the mistakes to avoid.

​
Organizing blueprints across tiers

The most common question enterprise admins ask: “Where should this configuration go?” The answer is simple: put it in the enterprise blueprint by default. The enterprise blueprint is the right place for anything that applies (or could apply) to all organizations. This includes language runtimes, security tools, corporate certificates, internal CLIs, proxy configuration, and shared registry auth. It’s perfectly fine to install multiple languages and tools here, even if not every org uses all of them.
Blueprint tierWhen to use itExamples
EnterpriseDefault for all shared configurationPython 3.12, Node 20, Go 1.22, Rust, security scanners, corporate CA certs, internal CLIs, proxy config, shared registry tokens
OrganizationOnly when something should not apply to every orgA team-specific private registry, tools restricted to certain teams, org-specific linting config
RepositoryPer-repo setup that runs in the repo directorynpm install, uv sync, project-specific knowledge items, repo-level .envrc files
The only reason to use an org blueprint instead of the enterprise blueprint is when you specifically don’t want something applied to every organization. For example, if one team uses a private npm registry that other teams shouldn’t have access to, that registry configuration belongs in that team’s org blueprint, not the enterprise blueprint. If something applies to all orgs, it goes in enterprise. If it’s repo-specific, it goes in the repo blueprint. The org tier exists only for the exceptions in between.
Don’t put repo-specific commands (like npm install) in the enterprise or org blueprint. Those tiers run in the home directory, not in the repo directory, so repo-specific commands will fail or install in the wrong place.

​
Use knowledge items at the right tier

Knowledge items are additive across tiers. Devin sees all of them. Use this to layer guidance:
  • Enterprise knowledge: Company-wide coding standards, security review requirements, internal documentation links.
  • Org knowledge: Team conventions, shared library usage patterns, team-specific deployment procedures.
  • Repo knowledge: Lint, test, and build commands for the specific project.

​
Secrets management at scale

Secrets cascade through the same tier hierarchy as blueprints, with more specific secrets taking precedence.

​
Where to define secrets

Secret scopeUse forExamples
EnterpriseCredentials shared across all orgsInternal registry tokens, corporate proxy auth, shared API keys for internal services
OrganizationTeam-specific credentialsTeam deployment keys, API tokens for team services, team-specific registry auth
RepositoryRepo-specific credentialsPer-project API keys, project-specific service accounts
Put secrets at the highest applicable tier. If every org needs access to the internal npm registry, define the token as an enterprise secret once. Don’t duplicate it across 50 org configs.

​
Secret hygiene

  • Never put secrets in YAML. Always use the secrets management UI. Secrets in YAML end up in logs, build artifacts, and audit trails.
  • Rotate secrets regularly. When you rotate a secret in the UI, the new value takes effect on the next build. No blueprint changes needed.
  • Use descriptive names. INTERNAL_NPM_TOKEN is better than TOKEN_1. Other admins (and your future self) need to understand what each secret is for.
  • Audit secret usage. Periodically review which secrets exist and whether they’re still needed. Remove unused secrets to reduce your attack surface.
If an org secret and an enterprise secret have the same name, the org secret wins. Same for repo secrets overriding org secrets. Use this intentionally. For example, an org might override the enterprise registry token with a team-specific token that has different permissions.

​
Build health monitoring

At enterprise scale, build failures are inevitable. The key is catching them early and resolving them quickly.

​
Establish a review cadence

Check build health weekly across all organizations. Look for:
  • Failed builds: Critical failures in enterprise or org blueprints that block all repos.
  • Partial builds: Some repos failing. Often a sign of a dependency issue or a stale blueprint.
  • Stale builds: Orgs whose latest build is unusually old, which may indicate a stuck build queue.

​
Respond to enterprise blueprint failures

If an enterprise blueprint change causes widespread failures:
  1. Assess the blast radius. Check how many orgs are affected on the Rollout page.
  2. Revert the enterprise blueprint to the last known-good blueprint. Save immediately. This triggers rebuilds across all affected orgs.
  3. Investigate in isolation. Test your changes against a single pilot org before re-rolling them out.
Don’t leave a broken enterprise blueprint in place while debugging. Every minute it’s broken, orgs are getting failed builds.

​
Partial builds are a signal

A partial build means some repos in an org succeeded while others failed. This is usually caused by:
  • A repo-specific dependency issue (broken lock file, removed package)
  • A missing system library that only one project needs
  • A stale blueprint that hasn’t been updated to match repo changes
Partial builds still produce usable snapshots for the repos that succeeded. But investigate the failures. They tend to accumulate if ignored.

​
When to pin builds

Build pinning freezes an org’s environment to a specific snapshot. Use it deliberately.

​
Good reasons to pin

  • Critical release in progress. You need a stable, known-good environment for the next 48 hours while shipping a release.
  • Active debugging. You’re investigating a build issue and don’t want auto-updates changing things under you.
  • Rollback. A new build introduced a regression and you need to revert immediately while you fix the blueprint.

​
Bad reasons to pin

  • Avoiding a fix. If a build is broken, fix the blueprint. Pinning masks the problem, and since pins don’t auto-expire, a forgotten pin can leave you running a stale environment indefinitely.
  • “Just in case.” Auto-updates keep dependencies fresh and catch issues early. Turning them off for no specific reason just delays problems.
You can only pin builds less than 7 days old. Once pinned, the pin stays active until manually removed. It does not expire. A forgotten pin means your team is running on an increasingly stale snapshot.

​
Migrating your enterprise

For the recommended phased migration playbook (from initial testing through full rollout), see Migrating your enterprise.

​
Common architectural patterns

Different enterprise structures call for different blueprint strategies.

​
Monorepo organizations

Setup: One org with a single large repository containing multiple projects. Approach: The enterprise blueprint handles all shared tooling (runtimes, global CLI tools, registries). Put project-specific setup (npm install in the frontend directory, uv sync in the backend directory) in the repo blueprint. The org blueprint is only needed if this org has tools or config that shouldn’t apply to other orgs. 
# Repo blueprint for a monorepo
maintenance:
  - name: "Frontend dependencies"
    run: (cd frontend && npm install)

  - name: "Backend dependencies"
    run: (cd backend && uv sync)

knowledge:
  - name: lint
    contents: |
      Frontend: cd frontend && npm run lint
      Backend: cd backend && uv run ruff check .

​
Multi-repo organizations

Setup: An org with multiple related repositories (e.g., a microservices team). Approach: Put shared tooling and registry configuration in the org blueprint. Each repo has its own blueprint with just maintenance and knowledge. This avoids duplicating setup commands across repos.

​
Shared infrastructure org

Setup: A platform or DevOps org that provides shared services used by other teams. Approach: The enterprise blueprint covers the common base. The shared infra org’s blueprint installs platform-specific tools (Terraform, kubectl, cloud CLIs) that its repos need. Other orgs don’t get these tools. They only get what’s in the enterprise blueprint plus their own org config.

​
Isolated project orgs

Setup: Independent teams with no shared tooling beyond the basics. Approach: The enterprise blueprint still handles the common base: all your standard language runtimes, security tools, and corporate infrastructure. Each org uses its own blueprint only for tools or config that are genuinely unique to that team and shouldn’t be shared with others. Repo blueprints handle per-project setup.
When in doubt, put it in the enterprise blueprint. If an org has a specific reason to exclude something (conflicting tool versions, restricted access), they can override it at the org level. It’s easier to have a comprehensive enterprise baseline than to duplicate setup across many org blueprints.