Declarative configuration

Getting started

Prerequisites: Devin must have access to your repositories before you can configure its environment. If you haven’t set up your Git integration yet, see Before you start for setup steps. Enterprise users also need to grant each org access to its repos in Enterprise Settings > Repository Permissions.

Still on classic configuration? You can migrate to declarative configuration at any time. Devin can handle most of the migration for you. See Migrating to declarative configuration.

Let Devin do it (recommended)
Manual setup

Best for most users. Devin analyzes your project, figures out what tools and dependencies are needed, and generates the blueprint for you. You just review and approve.

Start a Devin session

Open a new session and ask Devin to configure the repository. For example: “Set up your environment for this repo.”

Review and approve

Devin proposes a blueprint. You’ll see suggestion cards in your timeline. Review them and click Approve.

Verify

Once the build completes, start a new session. Devin boots from the new snapshot with everything pre-configured. Try asking Devin to run your lint or test commands to confirm everything works.

Best when you know exactly what your environment needs, or want full control over every step. Faster if you already have your commands ready.

Navigate to environment configuration

Go to Settings > Environment configuration in your organization’s sidebar.If you don’t see this option, your organization may still be on classic setup. See Migrating to declarative configuration to get started.

Add repositories

Click Add in the Repositories section. Select the repositories you want Devin to work with, then confirm.Repositories added here are cloned into Devin’s environment during each build. You can add more at any time.

Write your blueprint

Click on a repository to open its blueprint editor. Here’s a simple example:

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: uv run ruff check .
  - name: test
    contents: uv run pytest

For more languages and patterns, see the Template library.

Save and build

Click Save. A build starts automatically (typically 2–10 minutes). Monitor progress from the Environment configuration page under Current build.

Verify

Once the build shows Success, start a new Devin session. Devin boots from the new snapshot with everything pre-configured. Try asking Devin to run your lint or test commands to verify the environment works.

The rest of this guide covers the manual path in detail. It’s also useful for understanding what Devin generated if you used the recommended path.

How it works

Declarative configuration uses three concepts:

Concept	What it is	Analogy
Blueprint	A YAML configuration that describes what to install and how to set up Devin’s environment	Dockerfile
Build	The process that runs your blueprint, clones repos, and produces a snapshot	`docker build`
Snapshot	A frozen, bootable image of the environment that sessions start from	Docker image

Blueprints describe what you want. You author them and edit them in the Settings UI. Builds run your blueprints to produce snapshots. Builds run automatically when you save a blueprint and periodically (~every 24 hours) to keep dependencies fresh. Snapshots are what sessions boot from. Each organization has one active snapshot. Every session boots a fresh copy. Session changes don’t persist back to the snapshot.

Blueprint sections

A blueprint has three sections:

Section	Purpose	When it runs
`initialize`	Install tools, runtimes, system packages	During builds only. Results are saved in the snapshot.
`maintenance`	Install/update project dependencies, write credential configs	During builds + at the start of every session
`knowledge`	Reference info for Devin (lint, test, build commands)	Not executed. Loaded into Devin’s context at session start.

initialize is for things that only need to happen once: language runtimes, system packages, global CLI tools. maintenance is for dependency installation that should stay current. It runs during builds and again at session start after pulling the latest code, so commands should be fast and incremental (use npm install, not npm ci). knowledge is reference information, not executed. This is how you tell Devin the correct commands for linting, testing, and building. Keep entries lightweight and focused on executable commands.

Knowledge here vs the Knowledge product feature: The knowledge section in your blueprint is for short command references tied to the environment. For architecture docs, conventions, and team workflows, use the standalone Knowledge feature instead.

For the complete field specification (step types, GitHub Actions support, environment variables, secrets, and file attachments), see the Blueprint reference.

Blueprint scope

You can define blueprints at two levels:

Level	Where to configure	What to put here
Organization	Settings > Environment configuration > Org-wide setup	Tools shared across all repos: language runtimes, package managers, Docker auth
Repository	Settings > Environment configuration > [repo name]	Project-specific setup: `npm install`, lint/test/build commands

Blueprints are additive: repo blueprints build on top of the org blueprint. A repo’s maintenance can use tools installed by the org’s initialize. If only one repo needs a tool, put it in that repo’s blueprint. If every repo needs it, put it in the org blueprint.

Enterprise users: There’s a third tier, the enterprise blueprint, that applies across all organizations. See Enterprise environment overview for details.

Builds and sessions

The snapshot

Your organization has one active snapshot: a VM image with your tools, repos, and dependencies pre-installed. All configured repos are cloned and set up in that single image. Every session boots from a fresh copy.

How builds work

A build creates a new snapshot by running your blueprints in sequence:

1. Enterprise blueprint, if configured (runs in ~):
   a. initialize
   b. maintenance
2. Org blueprint (runs in ~):
   a. initialize
   b. maintenance
3. Clone all repositories (up to 10 concurrent)
4. For each configured repo, in the order shown in Settings
   (runs in ~/repos/<repo-name>):
   a. initialize
   b. maintenance
5. Health check, then snapshot is saved

Layers are additive: repo-specific commands can use tools installed by the org or enterprise blueprint. Lower levels cannot override what a higher level set up. Builds typically take 5–15 minutes. Individual steps time out after 1 hour.

How sessions work

Each session boots a fresh copy of the snapshot. When the session ends, all changes are discarded. At session start:

Enterprise and org-wide maintenance runs (in ~).
The latest code is pulled for the relevant repo(s).
That repo’s maintenance runs again to catch dependency changes since the last build.
That repo’s knowledge entries are loaded into Devin’s context.

Knowledge is per-repo. If you have 5 repos configured, Devin only sees the knowledge entries for the one it’s working on.

What triggers a build

Trigger	Description
Saving a blueprint	Creating, updating, or deleting a blueprint
Adding or removing a repository	Any change to the repository list
Adding a repository secret	New secrets require a rebuild to be available
Manual trigger	Clicking Build or Rebuild in the UI
Periodic refresh	Automatic, roughly every 24 hours
Devin suggestion	Devin proposes a blueprint change during a session

Only one build runs at a time. New triggers cancel any queued build and start fresh.

Build statuses

Status	Meaning
Success	All steps completed. Snapshot is ready.
Partial	Some repo-level steps failed, but the snapshot is usable. Repos that succeeded work normally; repos that failed need their blueprints fixed.
Failed	Critical failure (org or enterprise setup failed). Snapshot is not usable.
Cancelled	Superseded by a newer build or manually cancelled.

A partial build still produces a working snapshot. If one of five repos has a broken blueprint, the other four are fully functional.

Build failing? See Troubleshooting builds for a step-by-step debugging guide.

Managing your environment

Repository states

Repositories appear in three states in the Environment settings:

State	Meaning
Configured	Has a blueprint with initialize/maintenance/knowledge. Fully set up in the snapshot.
Included	Cloned into the snapshot but has no custom blueprint. Devin can access the code.
Available	Connected to the org but not added to the environment. Not cloned.

Included vs. configured: An “included” repo is cloned so Devin can access the code, but has no custom setup commands. A “configured” repo has explicit initialize/maintenance/knowledge instructions.

Secrets

Reference secrets with $VARIABLE_NAME syntax. Add them in Settings > Secrets.

maintenance:
  - name: Configure private registry
    run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN

Secrets are available as environment variables during builds and sessions. They are removed before the snapshot is saved, but if a command writes a secret value into a config file during initialize, that value persists in the snapshot. Always write credentials in maintenance. For details on secret scopes and behavior, see the Blueprint reference.

Multiple repositories

Each repo gets its own blueprint. During a build, all repos are set up in the same snapshot, cloned into separate directories with dependencies installed independently. If two repos install different versions of a global tool or modify shared files (like ~/.bashrc), the last one to run wins. Put shared tool installs in the org-wide blueprint to avoid conflicts.

Monorepos

For a monorepo, write a single blueprint covering all sub-projects. Use subshells to run commands in subdirectories:

maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)

The parentheses (cd ... && ...) run in a subshell so the working directory resets for the next step.

Pinning and auto-updates

By default, Devin uses the latest successful build’s snapshot. Pinning lets you lock to a specific build’s snapshot. This is useful when a new build introduces a regression, or when you want to freeze the environment for a batch of sessions. To pin: Go to Snapshot build history, find the build (must be success or partial, less than 7 days old), and click Pin. While pinned, periodic refreshes are skipped and the UI shows Auto-updates paused. To unpin: Click Resume auto-updates. Devin switches to the latest successful build.

Git-based blueprints

Git-based blueprints are not currently supported. This feature is coming soon. You’ll be able to store blueprints in your repository and have builds trigger automatically when they change. For now, configure blueprints through the UI.

Troubleshooting builds

Initialize step failed

Common causes: typo in a shell command, package not available, network timeout, incorrect GitHub Action reference. Fix: Check build logs for the exact error. Update initialize in your blueprint and save. A new build triggers automatically.

Repository clone failed

Common causes: Devin doesn’t have access to the repo, repo was renamed/moved/deleted, transient network issue. Fix: Verify repo access in your Git provider settings. Remove and re-add the repo if it was renamed.

Maintenance step failed

Common causes: dependency conflict, missing system library, disk space exhaustion, lock file out of sync. Fix: Check logs for the failing package/command. Update maintenance or initialize to install missing dependencies, or fix the lock file in your repository.

Build timeout

Each step has a 1-hour timeout. Common causes: compiling large native dependencies from source (use pre-built binaries), downloading large artifacts, commands that hang waiting for input (all commands must be non-interactive).

Iterating on fixes

Check build logs to identify the failure
Update the relevant blueprint
Save (a new build triggers automatically)
Monitor the new build’s logs
Repeat until the build succeeds

You don’t need to wait for a failed build to finish. Saving a new configuration cancels any queued build and starts fresh.

Next steps

Blueprint reference

Complete field reference: step types, GitHub Actions, environment variables, secrets, file attachments.

Template library

Copy-paste blueprints for Python, Node.js, Go, Java, Ruby, Rust, and advanced patterns.

Migrating from classic setup

Step-by-step guide to move from the interactive wizard to declarative blueprints.

Enterprise environment management

Enterprise-wide environment management: 3-tier hierarchy, secrets, and cross-org configuration.

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Declarative configuration

Getting started

How it works

Blueprint sections

Blueprint scope

Builds and sessions

The snapshot

How builds work

How sessions work

What triggers a build

Build statuses

Managing your environment

Repository states

Secrets

Multiple repositories

Monorepos

Pinning and auto-updates

Git-based blueprints

Troubleshooting builds

Initialize step failed

Repository clone failed

Maintenance step failed

Build timeout

Iterating on fixes

Next steps

Blueprint reference

Template library

Migrating from classic setup

Enterprise environment management

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

​Getting started

​How it works

​Blueprint sections

​Blueprint scope

​Builds and sessions

​The snapshot

​How builds work

​How sessions work

​What triggers a build

​Build statuses

​Managing your environment

​Repository states

​Secrets

​Multiple repositories

​Monorepos

​Pinning and auto-updates

​Git-based blueprints

​Troubleshooting builds

​Initialize step failed

​Repository clone failed

​Maintenance step failed

​Build timeout

​Iterating on fixes

​Next steps

Blueprint reference

Template library

Migrating from classic setup

Enterprise environment management

Getting started

How it works

Blueprint sections

Blueprint scope

Builds and sessions

The snapshot

How builds work

How sessions work

What triggers a build

Build statuses

Managing your environment

Repository states

Secrets

Multiple repositories

Monorepos

Pinning and auto-updates

Git-based blueprints

Troubleshooting builds

Initialize step failed

Repository clone failed

Maintenance step failed

Build timeout

Iterating on fixes

Next steps