> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scenarios: growing with ACME Corp

> How blueprint configuration evolves from a single repository, to a multi-repository application with shared dependencies, to a multi-organization enterprise.

Blueprints have three tiers — repository, organization, and enterprise — and the most common question is *which tier should this go in?*

This page answers that by following one fictional company, **ACME Corp**, through three stages of growth. Each stage introduces exactly one new problem, and each problem is solved by the next tier up. Skip to the stage that looks like your company.

| Stage                                                                                                  | What ACME looks like                                                            | What they configure                                         |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [1. One repository](#stage-1-one-repository)                                                           | A single Rails application, one team                                            | One repository blueprint                                    |
| [2. Several repositories, shared dependencies](#stage-2-several-repositories-with-shared-dependencies) | Five repositories, a shared development CLI, services that depend on each other | An organization blueprint plus one blueprint per repository |
| [3. Multiple organizations](#stage-3-multiple-organizations-the-enterprise-blueprint)                  | Several teams, each with its own organization, plus a security team             | An enterprise blueprint plus per-organization blueprints    |

<Info>
  The rule of thumb, up front: **repository blueprints install project dependencies, organization blueprints install anything shared by more than one repository, and enterprise blueprints install anything every organization must have.** Tiers are additive and run top-down: enterprise → organization → clone repositories → repository.
</Info>

***

## Stage 1: one repository

ACME has one product: `acme-web`, a Rails application with Postgres and Redis. Two engineers, one repository. There is nothing to share yet, so **everything goes in the repository blueprint**.

They add the repository in **Settings > Environment > Blueprints > Add**, open its editor, and write:

```yaml acme-web (repository blueprint) theme={null}
initialize:
  - name: Install Ruby 3.3
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: Install Postgres and Redis
    run: |
      sudo apt-get update -qq
      sudo apt-get install -y postgresql redis-server libpq-dev
      sudo systemctl enable --now postgresql redis-server
      sudo -u postgres createuser -s "$USER"

maintenance:
  - name: Install gems and prepare the database
    run: |
      bundle install
      bin/rails db:prepare

knowledge:
  - name: lint
    contents: bundle exec rubocop
  - name: test
    contents: bundle exec rspec
  - name: startup
    contents: bin/rails server -p 3000
```

That is the whole configuration. They save it, a build runs, and every session boots with Ruby installed, Postgres running, gems installed, and the database migrated.

**Why no organization blueprint yet?** An organization blueprint that serves only one repository is just indirection. Wait until a second repository needs the same thing.

<Tip>
  ACME did not hand-write this. They asked Devin *"set up your environment for this repository"*, reviewed the suggestion card, and clicked **Approve**. See [Getting started](/onboard-devin/environment/blueprints#getting-started).
</Tip>

***

## Stage 2: several repositories with shared dependencies

Two years later, ACME has five repositories:

| Repository      | What it is                                                                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `acme-devtools` | A CLI (`acme`) that spins up containers, wires services together, and serves local hostnames (`acme.local`, `portal.acme.local`). It also owns the internal documentation search (`acme docs:search`). |
| `acme-web`      | The main application. Most features land here.                                                                                                                                                         |
| `acme-portal`   | Customer-facing portal. It calls `acme-web`.                                                                                                                                                           |
| `acme-sso`      | Authentication service. Both applications depend on it.                                                                                                                                                |
| `acme-events`   | Event consumer.                                                                                                                                                                                        |

This is the interesting case, because the repositories are **not independent**: no useful work happens in `acme-portal` unless `acme-devtools` is installed and `acme-sso` is running. Two questions come up.

### "One blueprint per application, or just one for the development CLI?"

**Both — they do different jobs.** Devin builds *one snapshot* containing *all* configured repositories, so this is not an either/or choice:

* Add **all five repositories** to the environment so that all of them are cloned into the snapshot.
* Put the **shared, cross-repository setup once** in the **organization blueprint**: language runtimes, Docker, local hostnames, and credentials for the internal registry.
* Give each repository its own **repository blueprint** for its own dependencies and its own `knowledge` entries (lint, test, and startup commands).

Here is why you should not collapse everything into the `acme-devtools` blueprint: repository blueprints run after all repositories are cloned, but their steps run **in that repository's directory**, and their `knowledge` entries are loaded only when Devin is working in that repository. If `acme-devtools` installed everything, a session working in `acme-portal` would see none of the portal's lint and test commands, and a single failing `acme-devtools` step would leave the other four repositories looking healthy but unusable.

### The organization blueprint

```yaml Organization-wide setup theme={null}
initialize:
  - name: Install Ruby 3.3
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: Install Node.js 20
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: Install Docker and Compose
    run: |
      curl -fsSL https://get.docker.com | sh
      sudo usermod -aG docker "$USER"

  - name: Local hostnames for the development CLI
    run: |
      for host in acme.local portal.acme.local sso.acme.local; do
        grep -q " $host$" /etc/hosts \
          || echo "127.0.0.1 $host" | sudo tee -a /etc/hosts > /dev/null
      done

maintenance:
  - name: Authenticate to the internal registry
    run: |
      bundle config set --global https://gems.acme.internal "$ACME_REGISTRY_TOKEN"
      npm config set //npm.acme.internal/:_authToken "$ACME_REGISTRY_TOKEN"

post-build:
  - name: Verify the stack comes up
    run: |
      acme up --detach
      acme status
      acme down
```

Three things to notice:

1. **`initialize` versus `maintenance`.** Docker, runtimes, and hostnames are one-time system setup, so they belong in `initialize`. Registry credentials should be refreshed on every periodic build, so they belong in `maintenance`.

   The `acme` CLI itself is deliberately absent here. It lives inside `acme-devtools`, and organization steps run **before any repository is cloned**, so it is installed from that repository's own blueprint (shown below). That install runs during the build and persists into the snapshot, where every other repository can use it.
2. **`post-build` is the payoff for multi-repository setups.** It runs after *every* repository has been cloned and set up, so it is the only place where you can validate that the whole stack boots together. A non-zero exit code fails the build, so you learn about a broken stack at build time instead of mid-session. See [`post-build`](/onboard-devin/environment/blueprint-reference#post-build).
3. **Secrets belong to the organization**, not to each repository. One `ACME_REGISTRY_TOKEN` in the organization blueprint's **Secrets** tab serves every repository's `bundle install` and `npm install`.

<Warning>
  **Ordering gotcha:** organization `initialize` and `maintenance` both run **before** repositories are cloned (see [build order](/onboard-devin/environment/blueprints#how-builds-work)). Anything that needs checked-out source — such as a CLI that lives *inside* one of your repositories — must go in that repository's blueprint or in `post-build`, not in organization `maintenance`. Keep it in the organization tier only if you can install it from a released artifact, such as a tarball, a package, or a container image.
</Warning>

### The repository blueprints

Each repository blueprint stays small, because everything shared already exists:

```yaml acme-devtools (repository blueprint) theme={null}
initialize: |
  ./bin/install            # puts `acme` on the PATH for the whole snapshot

maintenance: |
  acme docs:index          # refresh the internal documentation index each build

knowledge:
  - name: cli
    contents: |
      `acme` manages every local service. Common commands:
        acme up <service>     start a service and its dependencies
        acme status           list running services
        acme docs:search <q>  search internal ACME engineering documentation
      Prefer `acme docs:search` over guessing at conventions.
```

```yaml acme-portal (repository blueprint) theme={null}
maintenance: |
  npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
  - name: startup
    contents: |
      The portal needs SSO running first:
        acme up sso
        acme up portal
      Then visit https://portal.acme.local
```

`acme-web`, `acme-sso`, and `acme-events` follow the same shape: a `maintenance` step for their own dependencies, and `knowledge` entries for their own lint, test, and startup commands.

<Tip>
  **Order `acme-devtools` first** in the repository list. Repository blueprints run in the order shown in Settings, so the repository that provides the shared CLI should be set up before the repositories that call it.
</Tip>

<Info>
  **Knowledge is per-repository.** With five repositories configured, a session working in `acme-portal` sees the portal's knowledge entries, plus organization and enterprise knowledge — it does not see the entries for `acme-web`. This is why every repository deserves its own blueprint, even when its `maintenance` section is a single line.
</Info>

<Tip>
  Because the `acme` CLI already knows how to run everything, the highest-value part of these blueprints is the **`knowledge`** section: it teaches Devin which CLI command to reach for. Point it at your internal documentation search if you have one.
</Tip>

### If your services live in a monorepo instead

The idea is the same, one tier down: use [workspaces](/onboard-devin/environment/workspaces) to give each package its own scoped setup and knowledge inside a single repository, instead of one blueprint per repository.

***

## Stage 3: multiple organizations — the enterprise blueprint

ACME now has 400 engineers. Platform, Payments, and Data each have their own Devin **organization**, with separate repositories, separate members, and separate snapshots. A security team has requirements that apply to all of them:

* All traffic goes through a corporate proxy, with an internal certificate authority.
* All packages come from Artifactory, never from public registries.
* Every environment must have the company's dependency and secret scanning tools installed.
* Python is 3.12 and Node.js is 20, company-wide, with no exceptions.

None of this belongs in an organization blueprint, because it would have to be **copied into every organization**, and it would drift the moment one team forgot to update it. This is what the **enterprise blueprint** is for: a base environment that runs first, in every organization's build, across the whole enterprise.

```yaml Devin's base environment (enterprise blueprint) theme={null}
initialize:
  - name: Corporate certificate authority and proxy
    run: |
      sudo cp "$FILE_ACME_CA_CERT" /usr/local/share/ca-certificates/acme-ca.crt
      sudo update-ca-certificates
      cat <<'EOF' >> ~/.bashrc
      export HTTPS_PROXY=http://proxy.acme.internal:8080
      export NO_PROXY=localhost,127.0.0.1,.acme.internal
      export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/acme-ca.crt
      export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
      EOF

  - name: Standard Python runtime
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

  - name: Security tooling
    run: |
      pip install bandit safety
      curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh

maintenance:
  - name: Point every package manager at Artifactory
    run: |
      pip config set global.index-url \
        "https://devin:$ARTIFACTORY_TOKEN@artifactory.acme.internal/api/pypi/pypi/simple/"
      npm config set registry https://artifactory.acme.internal/api/npm/npm/
      npm config set //artifactory.acme.internal/api/npm/npm/:_authToken "$ARTIFACTORY_TOKEN"

knowledge:
  - name: security-policy
    contents: |
      All dependencies must resolve through artifactory.acme.internal.
      Never add a public registry to a lockfile or a CI configuration.
```

`ARTIFACTORY_TOKEN` is an **enterprise secret**, defined once in **Settings > Devin's base environment > Secrets** and available in every build and every session across every organization. The certificate is a file attachment, surfaced to the build as `$FILE_ACME_CA_CERT`.

### What each tier owns now

| Tier             | Owner                                | ACME example                                                                       |
| ---------------- | ------------------------------------ | ---------------------------------------------------------------------------------- |
| **Enterprise**   | Security and platform administrators | Certificate authority, proxy, Artifactory, Python 3.12, scanners, one shared token |
| **Organization** | Each team's administrators           | Payments: Docker, the `acme` CLI, and team hostnames. Data: Spark and JDK 17.      |
| **Repository**   | Whoever owns the repository          | `bundle install`, `npm install`, and lint, test, and startup knowledge             |

The Payments organization blueprint from Stage 2 keeps working **unchanged**. It simply no longer needs to install Python or configure registries, because the enterprise tier already did. The Data organization blueprint installs Spark and a JDK, which Payments never sees. Repository blueprints are untouched.

### Operating it

* **Upgrading Python from 3.12 to 3.13** is a one-line edit plus an [enterprise-wide rebuild](/enterprise/environment-management/overview#enterprise-wide-rebuilds), which cascades to every organization.
* **When one team needs a different credential** — say the Data organization has its own Artifactory realm — that team defines an organization secret with the same name, and it **overrides** the enterprise secret.
* **To roll this out gradually** across organizations, see [Migrating your enterprise](/enterprise/environment-management/rollout).

***

## Deciding where something goes

Work down the list. The first "yes" is your answer:

<Steps>
  <Step title="Does every organization in the company need it?">
    → **Enterprise blueprint.** Certificates, proxies, internal registries, mandated runtimes, security tools, and company-wide secrets.
  </Step>

  <Step title="Do two or more repositories in this organization need it?">
    → **Organization blueprint.** Docker, shared development CLIs, local hostnames, cross-repository service orchestration, and registry credentials. Validate the assembled stack in `post-build`.
  </Step>

  <Step title="Does only this repository need it?">
    → **Repository blueprint.** Dependency installs, migrations, and the `knowledge` entries for its lint, test, and startup commands.
  </Step>

  <Step title="Is it a fact rather than a command to run?">
    → **`knowledge`**, at whichever tier it applies to. It is never executed; it is loaded into Devin's context.
  </Step>
</Steps>

Common mistakes this avoids:

* **Putting everything in one repository's blueprint.** The other repositories get no knowledge entries, and one broken step makes the whole setup look unhealthy.
* **Duplicating shared tools per repository.** When two repositories install different versions of the same global tool, the last one to run wins. Put the tool in the organization blueprint instead.
* **Skipping cross-repository verification.** When your repositories only work together, `post-build` is the only place that proves they do — before a session starts, rather than during one.

## Related pages

* [Declarative configuration](/onboard-devin/environment/blueprints) — build order, snapshots, and troubleshooting
* [Blueprint reference](/onboard-devin/environment/blueprint-reference) — every field, including `post-build` and `clone`
* [Template library](/onboard-devin/environment/templates) — copy-paste blueprints per language and registry
* [Workspaces and monorepos](/onboard-devin/environment/workspaces) — the monorepo equivalent of Stage 2
* [Enterprise environment overview](/enterprise/environment-management/overview) — Stage 3 in full detail