基于 Git 的蓝图

概览

基于 Git 的蓝图让你可以将环境配置直接存储在代码仓库中的 .devin/blueprint.yaml 文件里。你可以通过 API 或 UI 将该文件同步到 Devin，然后触发一次快照构建来应用这些更改。这样一来，你就可以沿用管理应用程序代码时的同一套工作流程：在 IDE 中编辑、发起拉取请求、接受审查、完成合并，然后通过 CI 步骤或 UI 进行同步和构建。

方式	蓝图所在位置	编辑方式	更改如何生效
数据库 (默认)	Devin 的设置界面	在浏览器中编辑	点击后立即保存
Git-backed	代码仓库中的 `.devin/blueprint.yaml`	在 IDE 中编辑并合并 PR	调用同步 API (或在 UI 中点击 Sync) ，然后触发构建

基于 Git 的蓝图使用与 UI 编辑器相同的 YAML 格式。完整字段规范请参阅蓝图参考。

快速开始

1. 创建蓝图文件

在你的代码仓库根目录下添加 .devin/blueprint.yaml 文件：

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

该文件使用的 YAML 格式与 UI 中的编辑器相同：

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. 推送到默认分支

将 .devin/blueprint.yaml 提交并推送到你的代码仓库默认分支 (通常是 main 或 master) 。如果该代码仓库已连接到 Devin 的环境，你需要触发一次同步 (通过 API 或 UI 中的 Sync 按钮) ，Devin 才能读取到该文件。如果这是你第一次添加该代码仓库，初始自动发现会从 Git 读取该蓝图。

3. 在 UI 中验证

前往 Settings > Environment > Blueprints，然后点击相应的代码仓库。编辑器会显示来自 Git 的蓝图内容，来源指示器会显示提供商名称 (例如“GitHub”) 以及已同步的提交 SHA 值。

同步如何运作

同步是指从代码仓库默认分支的 HEAD 拉取 .devin/blueprint.yaml，并更新 Devin 中已存储蓝图版本的过程。同步不会在 push 时自动进行——需要你显式触发：

API 同步 —— 调用 v3 同步端点 (参见下方的通过 API 同步) 。这是 CI/CD 流水线的推荐方式。
UI 同步 —— 在蓝图编辑器中点击 Sync 按钮。如果内容发生变化，这还会触发一次快照构建。
将代码仓库添加到环境时 —— 如果默认分支上存在 .devin/blueprint.yaml，系统会在初始自动发现期间自动从 Git 获取该蓝图。

同步具有幂等性：如果文件内容自上次同步以来没有变化，则不会创建新版本。

同步与构建

同步和构建是两个独立的操作：

同步会从 Git 拉取最新的 .devin/blueprint.yaml，并保存为一个新的蓝图版本。
构建会基于当前的蓝图版本创建一个新的快照镜像。

UI 中的同步按钮会通过一次操作完成这两个步骤。v3 API 则将它们分开，让你可以完全掌控流程——先调用同步，再触发构建。

通过 API 同步

保持蓝图同步的推荐方式，是在将对 .devin/blueprint.yaml 的更改合并后调用 v3 API。通常这是通过 CI/CD 流水线完成的 (例如，作为 GitHub Actions 中的合并后步骤) 。

端到端流程

步骤 1：同步蓝图

从默认分支拉取最新的 .devin/blueprint.yaml：

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"}'

响应：

{"repo_name": "owner/repo"}

repo_name 字段对于 GitHub 接受 owner/repo 格式；对于其他托管服务，则接受完整的提供商 URL (例如 https://gitlab.com/org/repo) 。

步骤 2：触发构建

同步后，触发一次快照构建，以应用新的蓝图：

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

响应：

{
  "build_id": "sbj-abc123",
  "status": "running",
  "trigger": "api",
  "created_at": 1718000000,
  "updated_at": 1718000000
}

步骤 3：轮询构建状态 (可选)

若要等待 CI 中的构建完成：

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

status 字段的状态会按以下方式变化：running → succeeded 或 failed。

企业范围内同步

对于在多个组织之间共享同一代码仓库的企业，有一个企业级端点，可通过与该代码仓库的连接在所有组织之间进行同步：

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"}'

响应中包含已同步的 orgs 数量：

{"repo_name": "owner/repo", "org_count": 3}

示例：GitHub Actions 工作流程

每次向默认分支推送且涉及蓝图文件时，自动执行同步和构建：

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

你需要一个服务用户或具有环境写权限的个人访问令牌。将该令牌保存为 DEVIN_API_TOKEN，并将你的 org ID 保存为 DEVIN_ORG_ID，存储在你的代码仓库 secrets 中。

编辑基于 Git 的蓝图

当蓝图基于 Git 时，UI 中的编辑器会变为只读，无法直接保存。要进行更改，可通过以下两种方式：

在编辑器中创建 PR

在 Settings > Environment > Blueprints 中打开蓝图编辑器
在编辑器中编辑 YAML
点击 创建 PR
Devin 会在你的代码仓库中创建一个拉取请求，以更新 .devin/blueprint.yaml
审查、批准并合并 PR
下次同步时会识别这一更改并触发构建

这让你无需离开 Devin UI 就能快速完成编辑。

直接在你的代码仓库中编辑

在你的 IDE 或 Git 提供商上编辑 .devin/blueprint.yaml
提交并推送到默认分支 (或创建 PR 并将其合并)
通过 API 触发同步，或在 UI 中点击 Sync

这是实行基础架构即代码管理的团队的标准工作流程。可结合一个 CI 步骤来自动同步 (请参阅通过 API 同步) 。

Devin 建议

当 Devin 在 session 期间提出蓝图修改建议时 (例如，在分析你的项目后) ，系统会通过创建一个针对 .devin/blueprint.yaml 的 PR 来应用该建议，而不是直接保存到数据库中。你只需像处理其他代码更改一样审查并合并该 PR。

monorepo 和工作区

对于包含多个软件包的 monorepo，你可以使用 includes 指令为每个工作区定义单独的蓝图。每个工作区都会在各自的子目录下拥有自己的 .devin/blueprint.yaml 文件。

使用 includes 的根蓝图

根 .devin/blueprint.yaml 声明了哪些工作区拥有各自的蓝图：

# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

工作区蓝图

每个已包含的工作区都有各自的 .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 规则

每个 includes 条目都是一个子目录路径 (例如 packages/frontend) 。Devin 会在该目录下查找 .devin/blueprint.yaml。
你也可以使用完整路径：packages/frontend/.devin/blueprint.yaml。
只有根蓝图可以包含 includes。不允许嵌套 include (即已包含的蓝图自身再声明 includes) 。
每个工作区路径在 includes 中只能出现一次。
如果代码仓库中缺少某个已包含的文件，则对应工作区会被视为已删除，其蓝图也会被清理。

在 Git 模式与数据库模式之间切换

切换到 Git

如果你已有一个由数据库管理的蓝图，并且想切换到 Git：

在你的代码仓库中创建 .devin/blueprint.yaml，并写入所需内容
推送到默认分支
在蓝图编辑器中，点击来源下拉菜单并选择你的 Git 提供商 (例如“GitHub”)
Devin 会从 Git 同步该文件，并切换到基于 Git 的模式

切换到数据库

如果你想停止使用 Git 模式，并改为在 UI 中管理蓝图：

在蓝图编辑器中，点击来源下拉菜单并选择 Database
当前内容会被保留，但之后再推送到 .devin/blueprint.yaml 将不再更新该蓝图
你现在可以直接在 UI 中编辑并保存

将根蓝图切换为数据库模式时，该代码仓库中的所有工作区蓝图也会一并切换为数据库模式，因为同步是在代码仓库级别进行的。

已分离的工作区

你可以将单个工作区蓝图从 Git 分离，同时让根目录保持为基于 Git 的模式。已分离的工作区可在 UI 中编辑，并且在同步时会被跳过。当某个工作区需要临时覆盖设置而又不影响仓库的其余部分时，这种方式就很有用。要重新附加已分离的工作区，请在来源下拉菜单中将其来源切回 Git。

版本历史

每次同步都会在蓝图的历史记录中创建一个新版本，并带有以下标记：

Source：由同步创建的版本标记为 git_sync，在 UI 中创建的版本标记为 manual
Commit SHA：同步所基于的默认分支提交 (链接到你的 Git 提供商上的该提交)

你可以在蓝图编辑器的 Version history 选项卡中查看完整的版本历史和 diff。

多文档 YAML

与 UI 编辑器一样，.devin/blueprint.yaml 也支持使用 --- 分隔符的多文档 YAML。这使你可以在单个文件中定义平台专用的配置：

# Linux 配置（默认）
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

有关多平台蓝图的详情，请参阅Windows 支持。

故障排查

蓝图未同步

文件路径是否正确？ 文件必须位于代码仓库根目录下的 .devin/blueprint.yaml (对于已包含的工作区，则应为 <workspace>/.devin/blueprint.yaml) 。
你是否触发了同步？ push 后不会自动同步。请调用同步 API 端点，或点击 UI 中的 Sync 按钮。
代码仓库是否已添加到 Devin 的环境中？ 要运行同步，必须先在 Settings > Environment > Blueprints 中添加该代码仓库。
是否已启用基于 Git 的模式？ 只有在基于 Git 的模式下 (而非数据库模式) ，同步才能更新该蓝图。

无效 YAML 错误

如果 .devin/blueprint.yaml 包含无效的 YAML，或不符合蓝图架构，同步就会报错并失败。请在默认分支上修复该文件，然后再次同步。UI 中的蓝图编辑器会验证架构，并在你创建 PR 之前显示错误，帮助你在问题进入默认分支之前发现它们。

推送后 Blueprint 显示“Database”

如果你已推送 .devin/blueprint.yaml，但编辑器中的来源仍显示为“Database”，则该蓝图可能尚未切换到基于 Git 的模式。使用来源下拉菜单切换到你的 Git 提供商，这会触发首次同步。

​概览

​快速开始

​1. 创建蓝图文件

​2. 推送到默认分支

​3. 在 UI 中验证

​同步如何运作

​同步与构建

​通过 API 同步

​端到端流程

​步骤 1：同步蓝图

​步骤 2：触发构建

​步骤 3：轮询构建状态 (可选)

​企业范围内同步

​示例：GitHub Actions 工作流程

​编辑基于 Git 的蓝图

​在编辑器中创建 PR

​直接在你的代码仓库中编辑

​Devin 建议

​monorepo 和工作区

​使用 includes 的根蓝图

​工作区蓝图

​include 规则

​在 Git 模式与数据库模式之间切换

​切换到 Git

​切换到数据库

​已分离的工作区

​版本历史

​多文档 YAML

​故障排查

​蓝图未同步

​无效 YAML 错误

​推送后 Blueprint 显示“Database”

概览

快速开始

1. 创建蓝图文件

2. 推送到默认分支

3. 在 UI 中验证

同步如何运作

同步与构建

通过 API 同步

端到端流程

步骤 1：同步蓝图

步骤 2：触发构建

步骤 3：轮询构建状态 (可选)

企业范围内同步

示例：GitHub Actions 工作流程

编辑基于 Git 的蓝图

在编辑器中创建 PR

直接在你的代码仓库中编辑

Devin 建议

monorepo 和工作区

使用 includes 的根蓝图

工作区蓝图

include 规则

在 Git 模式与数据库模式之间切换

切换到 Git

切换到数据库

已分离的工作区

版本历史

多文档 YAML

故障排查

蓝图未同步

无效 YAML 错误

推送后 Blueprint 显示“Database”