Git-backed blueprints

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

Git-backed blueprints use the same YAML format as the UI editor. See the Blueprint reference for the complete field specification.

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:

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:

API sync — Call the v3 sync endpoint (see Sync via the API below). This is the recommended approach for CI/CD pipelines.
UI sync — Click the Sync button in the blueprint editor. This also triggers a snapshot build if contents changed.
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

Step 1: Sync the blueprint

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

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:

{"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:

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:

{
  "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:

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:

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:

{"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:

# .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 '{}'

You need a service user 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.

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

Open the blueprint editor in Settings > Environment > Blueprints
Edit the YAML in the editor
Click Create PR
Devin opens a pull request on your repository that updates .devin/blueprint.yaml
Review, approve, and merge the PR
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

Edit .devin/blueprint.yaml in your IDE or on your Git provider
Commit and push to the default branch (or open a PR and merge it)
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).

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:

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

# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

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

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

Create .devin/blueprint.yaml in your repository with the desired contents
Push to the default branch
In the blueprint editor, click the source dropdown and select your Git provider (e.g., “GitHub”)
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:

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

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.

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:

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

​Overview

​Getting started

​1. Create the blueprint file

​2. Push to the default branch

​3. Verify in the UI

​How sync works

​Sync vs. build

​Sync via the API

​End-to-end flow

​Step 1: Sync the blueprint

​Step 2: Trigger a build

​Step 3: Poll build status (optional)

​Enterprise-wide sync

​Example: GitHub Actions workflow

​Editing git-backed blueprints

​Create a PR from the editor

​Edit directly in your repository

​Devin suggestions

​Monorepos and workspaces

​Root blueprint with includes

​Workspace blueprints

​Include rules

​Switching between Git and database modes

​Switch to Git

​Switch to database

​Detached workspaces

​Version history

​Multi-document YAML

​Troubleshooting

​Blueprint not syncing

​Invalid YAML errors

​Blueprint shows “Database” after pushing

Overview

Getting started

1. Create the blueprint file

2. Push to the default branch

3. Verify in the UI

How sync works

Sync vs. build

Sync via the API

End-to-end flow

Step 1: Sync the blueprint

Step 2: Trigger a build

Step 3: Poll build status (optional)

Enterprise-wide sync

Example: GitHub Actions workflow

Editing git-backed blueprints

Create a PR from the editor

Edit directly in your repository

Devin suggestions

Monorepos and workspaces

Root blueprint with includes

Workspace blueprints

Include rules

Switching between Git and database modes

Switch to Git

Switch to database

Detached workspaces

Version history

Multi-document YAML

Troubleshooting

Blueprint not syncing

Invalid YAML errors

Blueprint shows “Database” after pushing