Git連携のブループリント

概要

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

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

リポジトリを追加したときに Devin がモードを選択する仕組み

リポジトリ内にブループリントファイルがある場合、デフォルトでは常に Git 連携が選ばれます。環境にリポジトリを追加すると、Devin はデフォルトブランチに .devin/blueprint.yaml があるかどうかを確認します。

ファイルが存在する場合、Devin は Git からブループリントを取得し (Git 連携)、同期元のコミット SHA を記録します。
ファイルが存在しない場合 (または discovery に失敗した場合)、Devin は設定 UI で管理する空のブループリントを作成します (データベースモード)。

リポジトリはいつでも 2 つのモードを切り替えられます。詳細は Git モードとデータベースモードの切り替えを参照してください。

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

利用開始

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

リポジトリのルートに .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

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

.devin/blueprint.yaml をコミットし、リポジトリのデフォルトブランチ (通常は main または master) にプッシュします。リポジトリがすでに Devin の環境に接続されている場合は、Devin がそのファイルを取り込めるよう、同期をトリガーする (API または UI の Sync ボタンから) 必要があります。ただし、ブループリントがすでに Git 連携になっており、リポジトリでデフォルトブランチへのコミットごとに実行が有効になっている場合は不要です。ブループリントがデータベースモードの場合は、Git に切り替えてファイルをインポートしてください。初めてリポジトリを追加する場合は、初回の検出時に Git からブループリントが読み込まれます。

UIで確認する

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

同期の仕組み

同期とは、repo のデフォルトブランチの HEAD から .devin/blueprint.yaml を取得し、Devin に保存されているブループリントのバージョンを更新する処理です。デフォルトでは、同期は push しても自動では実行されません。同期は次の場合に実行されます。

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

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

デフォルトブランチへのコミットごとに同期してビルドする

GitHub.com のリポジトリでは、CI から API を呼び出したり Sync をクリックしたりする代わりに、自動同期とビルドをオプトインで有効にできます。

Settings > Environment > Blueprints に移動し、対象のリポジトリをクリックします。
Advanced タブを開きます。
デフォルトブランチへのコミットごとに実行 をオンにします。

この設定を有効にすると、デフォルトブランチへのプッシュのたびに git-backed ブループリントが同期され、各プラットフォーム向けのスナップショットのビルドがキューに追加されます。古いコミットのビルドがキューに残っている間に新しいコミットが届いた場合、キュー内のビルドはキャンセルされ、最新のコミットのみがビルドされます。すでに開始しているビルドは最後まで実行されます。リポジトリのブループリントがデータベースモードの場合は、コミット内のファイルではなく Devin に保存されているブループリントが使用されます。各ビルドの結果をコミット上の GitHub のチェック実行として表示するには、Report status checks for each commit をオンにします。

Advanced タブは、GitHub.com のリポジトリで、かつこのオプションが組織で利用可能な場合にのみ表示されます。他の Git プロバイダを利用している場合や、この設定がオフの場合は、API による同期または Sync ボタンを利用してください。

同期とビルド

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

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

UI の同期ボタンは、これら 2 つの手順を 1 回の操作で実行します。API ではこれらが分かれているため、より細かく制御できます。まず同期を呼び出し、その後ビルドをトリガーしてください。

API経由で同期

ブループリントおよびビルドのエンドポイントは、安定版の /v3/ API に含まれています。同期エンドポイントは現在もベータ版で、/v3beta1/ で提供されています。/v3/ に昇格するまでに、パスやリクエスト/レスポンスの形式が変更される可能性があります。

デフォルトブランチへのコミットごとに実行がリポジトリで利用できない、または無効になっている場合、ブループリントを同期した状態に保つ推奨方法は、.devin/blueprint.yaml への変更をマージした後に API を呼び出すことです。これは通常、CI/CD パイプライン (例: GitHub Actions のマージ後のステップ) から実行します。

エンドツーエンドの流れ

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

デフォルトブランチから最新の .devin/blueprint.yaml を取得します。

curl -X POST https://api.devin.ai/v3beta1/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": "pending",
  "trigger": "manual",
  "triggered_by_user_id": "user-abc123",
  "pinned": false,
  "started_at": null,
  "completed_at": null,
  "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 フィールドは次のように遷移します：pending → running → succeeded または failed (または cancelled) 。スナップショットが利用可能なため、部分ビルドは API では succeeded と報告されます。

Enterprise全体の同期

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

curl -X POST https://api.devin.ai/v3beta1/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/v3beta1/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 としてリポジトリのシークレットに保存してください。

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ボタンをクリックしてください。pushで自動的に同期されることを想定している場合は、リポジトリのAdvancedタブでデフォルトブランチへのコミットごとに実行が有効になっていること、およびデフォルトブランチにpushしたことを確認してください。
リポジトリはDevinの環境に追加されていますか？ 同期を実行するには、Settings > Environment > Blueprintsでそのリポジトリを追加しておく必要があります。
Git 連携は有効になっていますか？ 同期で更新されるには、ブループリントがGit 連携 (データベースモードではなく) になっている必要があります。

無効な YAML に関するエラー

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

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

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

​概要

​リポジトリを追加したときに Devin がモードを選択する仕組み

​利用開始

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

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

​ UIで確認する

​同期の仕組み

​デフォルトブランチへのコミットごとに同期してビルドする

​同期とビルド

​API経由で同期

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

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

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

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

​Enterprise全体の同期

​例: GitHub Actions ワークフロー

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

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

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

​Devin の提案

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

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

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

​インクルードのルール

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

​Git に切り替える

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

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

​バージョン履歴

​マルチドキュメントYAML

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

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

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

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

概要

リポジトリを追加したときに Devin がモードを選択する仕組み

利用開始

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

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

UIで確認する

同期の仕組み

デフォルトブランチへのコミットごとに同期してビルドする

同期とビルド

API経由で同期

エンドツーエンドの流れ

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

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

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

Enterprise全体の同期

例: GitHub Actions ワークフロー

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

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

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

Devin の提案

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

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

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

インクルードのルール

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

Git に切り替える

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

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

バージョン履歴

マルチドキュメントYAML

トラブルシューティング

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

無効な YAML に関するエラー

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