Git連携ブループリント

概要

Git 連携のブループリントを使うと、環境設定を .devin/blueprint.yaml ファイルとしてリポジトリに直接保存できます。API または UI からそのファイルを Devin に同期し、その後スナップショットのビルドをトリガーして変更を適用します。これにより、アプリケーションコードと同じワークフローを利用できます。つまり、IDE で編集し、プルリクエストを作成し、レビューを受けてマージしたうえで、CI ステップまたは UI から同期とビルドを行えます。

アプローチ	ブループリントの保存場所	編集方法	変更の適用方法
データベース (デフォルト)	Devin の設定 UI	ブラウザで編集	クリックするとすぐに保存
Git 連携	リポジトリ内の `.devin/blueprint.yaml`	IDE で編集し、PR をマージ	sync API を呼び出す (または UI で Sync をクリックする) → その後ビルドをトリガーする

Git 連携のブループリントでは、UI エディタと同じ YAML 形式を使用します。利用可能なすべてのフィールドと構文については、Blueprint referenceを参照してください。

利用開始

1. ブループリントファイルを作成する

リポジトリのルートに .devin/blueprint.yaml ファイルを追加します。

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

このファイルでは、UIエディタと同じYAML形式を利用します:

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 の環境に接続されている場合は、Devin がそのファイルを取り込めるよう、同期をトリガーする (API または UI の Sync ボタンから) 必要があります。初めてリポジトリを追加する場合は、初回の検出時に Git からブループリントが読み込まれます。

3. UIで確認する

Settings > Environment > Blueprints に移動し、リポジトリをクリックします。Editor には Git のブループリントの内容が表示され、ソースインジケーターにはプロバイダー名 (例: “GitHub”) と同期済みのコミット SHA が表示されます。

同期の仕組み

同期とは、repo のデフォルトブランチの HEAD から .devin/blueprint.yaml を取得し、Devin に保存されているブループリントのバージョンを更新する処理です。同期は push しても自動では実行されず、明示的にトリガーする必要があります。

API 同期 — v3 の sync エンドポイントを呼び出します (下のAPI を使った同期を参照) 。これは CI/CD パイプラインに推奨される方法です。
UI 同期 — ブループリントエディタの Sync ボタンをクリックします。内容が変更されていた場合は、これによりスナップショットのビルドもトリガーされます。
Environment に repo を追加するとき — デフォルトブランチに .devin/blueprint.yaml が存在する場合、初回検出時に Git からブループリントが自動的に取得されます。

同期は冪等です。前回の同期以降にファイルの内容が変わっていなければ、新しいバージョンは作成されません。

同期とビルド

同期とビルドは、それぞれ別の操作です。

同期では、Git から最新の .devin/blueprint.yaml を取得し、新しいブループリントのバージョンとして保存します。
ビルド では、現在のブループリントのバージョンをもとに新しいスナップショットイメージを作成します。

UI の同期ボタンは、これら 2 つの手順を 1 回の操作で実行します。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。

Enterprise全体の同期

同じリポジトリを共有する複数の組織があるEnterpriseでは、リポジトリに接続されているすべての組織間で同期を行うEnterpriseレベルのエンドポイントを利用できます。

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

サービスユーザーまたは Environment への書き込み権限を持つパーソナルアクセストークンが必要です。トークンを DEVIN_API_TOKEN、org ID を DEVIN_ORG_ID としてリポジトリのシークレットに保存してください。

Git で管理されるブループリントの編集

ブループリントが Git で管理されている場合、UI 上のエディターは直接保存できず、読み取り専用になります。代わりに、変更する方法は 2 つあります：

エディタから PR を作成する

Settings > Environment > Blueprints でブループリントエディタを開きます
エディタで YAML を編集します
Create PR をクリックします
Devin がリポジトリに .devin/blueprint.yaml を更新するプルリクエストを作成します
PR をレビューし、承認してマージします
次回の同期で変更が反映され、ビルドがトリガーされます

これは、Devin の UI を離れずにすばやく編集したい場合に便利です。

リポジトリを直接編集する

IDE または Gitプロバイダー上で .devin/blueprint.yaml を編集します
デフォルトブランチにコミットしてプッシュします (または PR を作成してマージします)
API 経由で同期をトリガーするか、UI で Sync をクリックします

これは、インフラストラクチャをコードとして管理するチーム向けの標準的なワークフローです。CI ステップと組み合わせることで、同期を自動化できます (API 経由で同期するを参照) 。

Devin の提案

Devin がセッション中にブループリントの変更を提案した場合 (たとえば、プロジェクトを分析した後) 、その提案はデータベースに直接保存されるのではなく、.devin/blueprint.yaml に対する PR を作成する形で適用されます。ほかのコード変更と同様に、その PR をレビューしてマージします。

モノレポとワークスペース

複数のパッケージを含むモノレポでは、includes ディレクティブを利用して、各ワークスペースごとに個別のブループリントを定義できます。各ワークスペースには、それぞれのサブディレクトリ内に固有の .devin/blueprint.yaml ファイルが配置されます。

インクルード付きのルートブループリント

ルートの .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

インクルードのルール

各 includes エントリにはサブディレクトリのパス (例: packages/frontend) を指定します。Devin はそのディレクトリ内の .devin/blueprint.yaml を探します。
完全なパス packages/frontend/.devin/blueprint.yaml を指定することもできます。
includes を含められるのはルートブループリントのみです。入れ子のインクルード (インクルード先のブループリント内でさらに includes を宣言すること) は許可されません。
各ワークスペースのパスは includes 内に 1 回だけ指定できます。
インクルードされたファイルがリポジトリ内に存在しない場合、そのワークスペースは削除されたものとして扱われ、対応するブループリントはクリーンアップされます。

Gitモードとデータベースモードの切り替え

Git に切り替える

既存のデータベース管理のブループリントがあり、Git に切り替えたい場合:

リポジトリに、必要な内容を記述した .devin/blueprint.yaml を作成します
デフォルトブランチにプッシュします
ブループリントエディタでソースのドロップダウンをクリックし、Git プロバイダ (例: “GitHub”) を選択します
Devin が Git からファイルを同期し、Git 連携に切り替わります

データベースに切り替える

Git 連携の使用をやめて、UI でブループリントを管理したい場合:

ブループリントエディタでソースのドロップダウンをクリックし、Database を選択します
現在の内容は保持されますが、今後 .devin/blueprint.yaml にプッシュしてもブループリントは更新されなくなります
以降は UI で直接編集して保存できます

ルートブループリントをデータベースモードに切り替えると、そのリポジトリ内のすべてのワークスペースブループリントもデータベースモードに切り替わります。これは、同期がリポジトリ単位で行われるためです。

デタッチされたワークスペース

ルートは Git 連携のまま、個々のワークスペースのブループリントを Git からデタッチできます。デタッチされたワークスペースは UI で編集でき、同期時にはスキップされます。これは、リポジトリのほかの部分に影響を与えずに、特定のワークスペースに一時的なオーバーライドが必要な場合に便利です。デタッチされたワークスペースを再度アタッチするには、ソースのドロップダウンでソースを Git に戻します。

バージョン履歴

同期のたびに、ブループリントの履歴に新しいバージョンが作成され、次のタグが付きます。

ソース: 同期で作成されたバージョンは git_sync、UI で作成されたバージョンは manual
コミット SHA: 同期が実行されたデフォルトブランチのコミット (Git プロバイダー上の該当コミットへのリンク)

ブループリントエディタのバージョン履歴タブで、すべてのバージョン履歴と差分を閲覧できます。

マルチドキュメントYAML

UIのエディタと同様に、.devin/blueprint.yaml では --- 区切りを使ったマルチドキュメントYAMLをサポートしています。これにより、1つのファイルでプラットフォーム固有の設定を定義できます。

# Linux 設定 (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

マルチプラットフォーム対応のブループリントについて詳しくは、Windows サポートを参照してください。

トラブルシューティング

ブループリントが同期されない

ファイルは正しいパスにありますか？ リポジトリルートでは.devin/blueprint.yaml、含まれるワークスペースでは<workspace>/.devin/blueprint.yamlである必要があります。
同期をトリガーしましたか？ pushしても同期は自動では実行されません。同期用のAPIエンドポイントを呼び出すか、UIのSyncボタンをクリックしてください。
リポジトリはDevinの環境に追加されていますか？ 同期を実行するには、Settings > Environment > Blueprintsでそのリポジトリを追加しておく必要があります。
Git 連携は有効になっていますか？ 同期で更新されるには、ブループリントがGit 連携 (database modeではなく) になっている必要があります。

無効な YAML に関するエラー

.devin/blueprint.yaml に無効な YAML が含まれている場合、またはブループリントのスキーマに準拠していない場合、同期はエラーで失敗します。デフォルトブランチ上のファイルを修正して、再度同期してください。UI のブループリントエディタでは、PR を作成する前にスキーマが検証され、エラーが表示されるため、問題がデフォルトブランチに反映される前に見つけやすくなります。

プッシュ後も Blueprint に “Database” と表示される

.devin/blueprint.yaml をプッシュしても、エディタでソースが引き続き “Database” と表示される場合は、ブループリントがまだ Git 連携モードに切り替わっていない可能性があります。ソースのドロップダウンから Git プロバイダに切り替えてください。これにより初回同期が開始されます。

​概要

​利用開始

​1. ブループリントファイルを作成する

​2. デフォルトブランチにプッシュする

​3. UIで確認する

​同期の仕組み

​同期とビルド

​API 経由で同期

​エンドツーエンドの流れ

​ステップ 1: ブループリントを同期する

​ステップ 2: ビルドをトリガーする

​ステップ 3: ビルドのステータスをポーリングする (任意)

​Enterprise全体の同期

​例: GitHub Actions ワークフロー

​Git で管理されるブループリントの編集

​エディタから PR を作成する

​リポジトリを直接編集する

​Devin の提案

​モノレポとワークスペース

​インクルード付きのルートブループリント

​ワークスペースのブループリント

​インクルードのルール

​Gitモードとデータベースモードの切り替え

​Git に切り替える

​データベースに切り替える

​デタッチされたワークスペース

​バージョン履歴

​マルチドキュメントYAML

​トラブルシューティング

​ブループリントが同期されない

​無効な YAML に関するエラー

​プッシュ後も Blueprint に “Database” と表示される

概要

利用開始

1. ブループリントファイルを作成する

2. デフォルトブランチにプッシュする

3. UIで確認する

同期の仕組み

同期とビルド

API 経由で同期

エンドツーエンドの流れ

ステップ 1: ブループリントを同期する

ステップ 2: ビルドをトリガーする

ステップ 3: ビルドのステータスをポーリングする (任意)

Enterprise全体の同期

例: GitHub Actions ワークフロー

Git で管理されるブループリントの編集

エディタから PR を作成する

リポジトリを直接編集する

Devin の提案

モノレポとワークスペース

インクルード付きのルートブループリント

ワークスペースのブループリント

インクルードのルール

Gitモードとデータベースモードの切り替え

Git に切り替える

データベースに切り替える

デタッチされたワークスペース

バージョン履歴

マルチドキュメントYAML

トラブルシューティング

ブループリントが同期されない

無効な YAML に関するエラー

プッシュ後も Blueprint に “Database” と表示される