> ## 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.

# Git-backed blueprints

> Store blueprints as .devin/blueprint.yaml in your repository and sync them via the API or UI.

## Overview

Git-backed blueprints let you store your environment configuration directly in your repository as a `.devin/blueprint.yaml` file. You sync the file to Devin via the API or the UI, and then trigger a snapshot build to apply the changes.

This gives you the same workflow you use for application code: edit in your IDE, open a pull request, get a review, merge, and then sync + build via a CI step or the UI.

| Approach               | Where the blueprint lives            | How you edit it              | How changes apply                                                 |
| ---------------------- | ------------------------------------ | ---------------------------- | ----------------------------------------------------------------- |
| **Database (default)** | Devin's settings UI                  | Edit in the browser          | Saved immediately on click                                        |
| **Git-backed**         | `.devin/blueprint.yaml` in your repo | Edit in your IDE, merge a PR | Call the sync API (or click Sync in the UI), then trigger a build |

<Info>
  Git-backed blueprints use the same YAML format as the UI editor. See the [Blueprint reference](/onboard-devin/environment/blueprint-reference) for the complete field specification.
</Info>

## Getting started

### 1. Create the blueprint file

Add a `.devin/blueprint.yaml` file to the root of your repository:

```
my-repo/
  .devin/
    blueprint.yaml
  src/
  package.json
  ...
```

The file uses the same YAML format as the UI editor:

```yaml theme={null}
initialize:
  - name: Install Node.js 22
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "22"

maintenance:
  - name: Install dependencies
    run: npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
```

### 2. Push to the default branch

Commit and push `.devin/blueprint.yaml` to your repository's default branch (typically `main` or `master`).

If the repository is already connected to Devin's environment, you need to trigger a sync (via the API or the UI Sync button) for Devin to pick up the file. If you're adding the repo for the first time, the initial discovery reads the blueprint from Git.

### 3. Verify in the UI

Go to **Settings > Environment > Blueprints** and click on the repository. The editor shows the blueprint contents from Git, and the source indicator displays the provider name (e.g., "GitHub") with the synced commit SHA.

## How sync works

Sync is the process of pulling `.devin/blueprint.yaml` from the repo's default branch HEAD and updating Devin's stored blueprint versions. Sync does **not** happen automatically on push — you trigger it explicitly:

1. **API sync** — Call the v3 sync endpoint (see [Sync via the API](#sync-via-the-api) below). This is the recommended approach for CI/CD pipelines.
2. **UI sync** — Click the **Sync** button in the blueprint editor. This also triggers a snapshot build if contents changed.
3. **On adding a repo to the environment** — If `.devin/blueprint.yaml` exists on the default branch, the blueprint is automatically sourced from Git during initial discovery.

Sync is idempotent: if the file contents haven't changed since the last sync, no new version is created.

### Sync vs. build

Sync and build are separate operations:

* **Sync** pulls the latest `.devin/blueprint.yaml` from Git and stores a new blueprint version.
* **Build** creates a new snapshot image from the current blueprint versions.

The UI sync button performs both steps in one action. The v3 API separates them so you have full control — call sync first, then trigger a build.

## Sync via the API

The recommended way to keep blueprints in sync is to call the v3 API after merging changes to `.devin/blueprint.yaml`. This is typically done from a CI/CD pipeline (e.g., a GitHub Actions post-merge step).

### End-to-end flow

```mermaid theme={null}
sequenceDiagram
    participant Dev as Developer
    participant Git as Git Provider
    participant CI as CI/CD Pipeline
    participant API as Devin API
    Dev->>Git: Push/merge .devin/blueprint.yaml
    Git->>CI: Trigger post-merge workflow
    CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/sync
    API-->>CI: 200 OK (repo_name)
    CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/builds
    API-->>CI: 201 Created (build_id, status)
    CI->>API: GET /v3/organizations/{org_id}/snapshot-setup/builds/{build_id}
    API-->>CI: 200 OK (status: succeeded)
```

### Step 1: Sync the blueprint

Pull the latest `.devin/blueprint.yaml` from the default branch:

```bash theme={null}
curl -X POST https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'
```

Response:

```json theme={null}
{"repo_name": "owner/repo"}
```

The `repo_name` field accepts `owner/repo` for GitHub, or a full provider URL for other hosts (e.g., `https://gitlab.com/org/repo`).

### Step 2: Trigger a build

After sync, trigger a snapshot build to apply the new blueprint:

```bash theme={null}
curl -X POST https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Response:

```json theme={null}
{
  "build_id": "sbj-abc123",
  "status": "running",
  "trigger": "api",
  "created_at": 1718000000,
  "updated_at": 1718000000
}
```

### Step 3: Poll build status (optional)

If you want to wait for the build to complete in CI:

```bash theme={null}
curl https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds/{build_id} \
  -H "Authorization: Bearer $DEVIN_API_TOKEN"
```

The `status` field transitions through: `running` → `succeeded` or `failed`.

### Enterprise-wide sync

For enterprises with multiple organizations sharing the same repository, there's an enterprise-level endpoint that syncs across all orgs with a connection to the repo:

```bash theme={null}
curl -X POST https://api.devin.ai/v3/enterprise/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'
```

Response includes the number of orgs synced:

```json theme={null}
{"repo_name": "owner/repo", "org_count": 3}
```

### Example: GitHub Actions workflow

Automate sync + build on every push to the default branch that touches the blueprint file:

```yaml theme={null}
# .github/workflows/sync-blueprint.yml
name: Sync Devin Blueprint

on:
  push:
    branches: [main]
    paths:
      - '.devin/blueprint.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync blueprint
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/sync" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"repo_name": "${{ github.repository }}"}'

      - name: Trigger build
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/builds" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{}'
```

<Info>
  You need a [service user](/api-reference/overview) or personal access token with environment write permissions. Store the token as `DEVIN_API_TOKEN` and your org ID as `DEVIN_ORG_ID` in your repository secrets.
</Info>

## Editing git-backed blueprints

When a blueprint is git-backed, the UI editor becomes read-only for direct saves. Instead, you have two options for making changes:

### Create a PR from the editor

1. Open the blueprint editor in **Settings > Environment > Blueprints**
2. Edit the YAML in the editor
3. Click **Create PR**
4. Devin opens a pull request on your repository that updates `.devin/blueprint.yaml`
5. Review, approve, and merge the PR
6. The next sync picks up the change and triggers a build

This is useful for quick edits without leaving the Devin UI.

### Edit directly in your repository

1. Edit `.devin/blueprint.yaml` in your IDE or on your Git provider
2. Commit and push to the default branch (or open a PR and merge it)
3. Trigger a sync via the API or click Sync in the UI

This is the standard workflow for teams that manage infrastructure as code. Pair it with a CI step to automate the sync (see [Sync via the API](#sync-via-the-api)).

### Devin suggestions

When Devin proposes a blueprint change during a session (e.g., after analyzing your project), the suggestion is applied by opening a PR against `.devin/blueprint.yaml` rather than saving directly to the database. You review and merge the PR just like any other code change.

## Monorepos and workspaces

For monorepos with multiple packages, you can use the `includes` directive to define separate blueprints for each workspace. Each workspace gets its own `.devin/blueprint.yaml` file in its subdirectory.

### Root blueprint with includes

The root `.devin/blueprint.yaml` declares which workspaces have their own blueprints:

```yaml theme={null}
# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install
```

### Workspace blueprints

Each included workspace has its own `.devin/blueprint.yaml`:

```yaml theme={null}
# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

knowledge:
  - name: lint
    contents: pnpm lint
  - name: test
    contents: pnpm test
```

```yaml theme={null}
# my-repo/packages/backend/.devin/blueprint.yaml
maintenance: |
  pip install -r requirements.txt

knowledge:
  - name: lint
    contents: ruff check .
  - name: test
    contents: pytest
```

### Include rules

* Each `includes` entry is a subdirectory path (e.g., `packages/frontend`). Devin looks for `.devin/blueprint.yaml` inside that directory.
* You can also use the full path: `packages/frontend/.devin/blueprint.yaml`.
* Only the root blueprint may contain `includes`. Nested includes (an included blueprint that itself declares `includes`) are not allowed.
* Each workspace path may only appear once in `includes`.
* If an included file is missing from the repository, that workspace is treated as removed and its blueprint is cleaned up.

## Switching between Git and database modes

### Switch to Git

If you have an existing database-managed blueprint and want to switch to Git:

1. Create `.devin/blueprint.yaml` in your repository with the desired contents
2. Push to the default branch
3. In the blueprint editor, click the source dropdown and select your Git provider (e.g., "GitHub")
4. Devin syncs the file from Git and switches to git-backed mode

### Switch to database

If you want to stop using git-backed mode and manage the blueprint in the UI:

1. In the blueprint editor, click the source dropdown and select **Database**
2. The current contents are preserved, but future pushes to `.devin/blueprint.yaml` no longer update the blueprint
3. You can now edit and save directly in the UI

<Warning>
  Switching the root blueprint to database mode switches all workspace blueprints for that repo to database mode as well, since sync operates at the repo level.
</Warning>

### Detached workspaces

You can detach individual workspace blueprints from Git while keeping the root in git-backed mode. A detached workspace is editable in the UI and skipped during sync. This is useful when one workspace needs a temporary override without affecting the rest of the repo.

To re-attach a detached workspace, switch its source back to Git from the source dropdown.

## Version history

Every sync creates a new version in the blueprint's history, tagged with:

* **Source**: `git_sync` for versions created by sync, `manual` for versions created in the UI
* **Commit SHA**: the default-branch commit the sync ran against (links to the commit on your Git provider)

You can view the full version history and diffs in the **Version history** tab of the blueprint editor.

## Multi-document YAML

Like the UI editor, `.devin/blueprint.yaml` supports multi-document YAML using the `---` separator. This lets you define platform-specific configurations in a single file:

```yaml theme={null}
# Linux configuration (default)
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync
---
runs-on: windows

initialize: |
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

maintenance: |
  uv sync
```

See [Windows support](/onboard-devin/environment/windows-support) for details on multi-platform blueprints.

## Troubleshooting

### Blueprint not syncing

* **Is the file at the right path?** It must be `.devin/blueprint.yaml` at the repository root (or `<workspace>/.devin/blueprint.yaml` for included workspaces).
* **Did you trigger a sync?** Sync does not happen automatically on push. Call the sync API endpoint or click the **Sync** button in the UI.
* **Is the repository in Devin's environment?** The repo must be added in **Settings > Environment > Blueprints** for sync to run.
* **Is git-backed mode enabled?** The blueprint must be in git-backed mode (not database mode) for sync to update it.

### Invalid YAML errors

If `.devin/blueprint.yaml` contains invalid YAML or doesn't conform to the blueprint schema, the sync fails with an error. Fix the file on the default branch and sync again. The blueprint editor in the UI validates the schema and shows errors before you create a PR, which helps catch issues before they reach the default branch.

### Blueprint shows "Database" after pushing

If you pushed a `.devin/blueprint.yaml` but the editor still shows "Database" as the source, the blueprint may not have been switched to git-backed mode yet. Use the source dropdown to switch to your Git provider, which triggers the initial sync.