> ## 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連携ブループリント

> リポジトリ内の .devin/blueprint.yaml にブループリントを保存し、API または UI で同期します。

<div id="overview">
  ## 概要
</div>

Git 連携のブループリントを使うと、環境設定を `.devin/blueprint.yaml` ファイルとしてリポジトリに直接保存できます。API または UI からそのファイルを Devin に同期し、その後スナップショットのビルドをトリガーして変更を適用します。

これにより、アプリケーションコードと同じワークフローを利用できます。つまり、IDE で編集し、プルリクエスト を作成し、レビューを受けてマージしたうえで、CI ステップまたは UI から同期とビルドを行えます。

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

<Info>
  Git 連携のブループリントでは、UI エディタと同じ YAML 形式を使用します。利用可能なすべてのフィールドと構文については、[Blueprint reference](/ja/onboard-devin/environment/blueprint-reference)を参照してください。
</Info>

<div id="getting-started">
  ## 利用開始
</div>

<div id="1-create-the-blueprint-file">
  ### 1. ブループリントファイルを作成する
</div>

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

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

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

```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
```

<div id="2-push-to-the-default-branch">
  ### 2. デフォルトブランチにプッシュする
</div>

`.devin/blueprint.yaml` をコミットし、リポジトリのデフォルトブランチ (通常は `main` または `master`) にプッシュします。

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

<div id="3-verify-in-the-ui">
  ### 3. UIで確認する
</div>

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

<div id="how-sync-works">
  ## 同期の仕組み
</div>

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

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

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

<div id="sync-vs-build">
  ### 同期とビルド
</div>

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

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

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

<div id="sync-via-the-api">
  ## API 経由で同期
</div>

ブループリントを同期した状態に保つ推奨方法は、`.devin/blueprint.yaml` への変更をマージした後に v3 API を呼び出すことです。これは通常、CI/CD パイプライン (例: GitHub Actions のマージ後のステップ) から実行します。

<div id="end-to-end-flow">
  ### エンドツーエンドの流れ
</div>

```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)
```

<div id="step-1-sync-the-blueprint">
  ### ステップ 1: ブループリントを同期する
</div>

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

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

レスポンス:

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

`repo_name` フィールドには、GitHub の場合は `owner/repo`、それ以外のホストの場合はプロバイダーの完全な URL (例: `https://gitlab.com/org/repo`) を指定できます。

<div id="step-2-trigger-a-build">
  ### ステップ 2: ビルドをトリガーする
</div>

同期後、新しいブループリントを適用するには、スナップショットのビルドをトリガーします：

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

レスポンス:

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

<div id="step-3-poll-build-status-optional">
  ### ステップ 3: ビルドのステータスをポーリングする (任意)
</div>

CI でビルドの完了を待つ場合:

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

`status` フィールドは次のように遷移します：`running` → `succeeded` または `failed`。

<div id="enterprise-wide-sync">
  ### Enterprise全体の同期
</div>

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

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

レスポンスには、同期済みのorgs数が含まれます：

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

<div id="example-github-actions-workflow">
  ### 例: GitHub Actions ワークフロー
</div>

ブループリントファイルに変更が含まれるデフォルトブランチへのプッシュごとに、同期とビルドを自動化します:

```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>
  [サービスユーザー](/ja/api-reference/overview) または Environment への書き込み権限を持つパーソナルアクセストークンが必要です。トークンを `DEVIN_API_TOKEN`、org ID を `DEVIN_ORG_ID` としてリポジトリのシークレットに保存してください。
</Info>

<div id="editing-git-backed-blueprints">
  ## Git で管理されるブループリントの編集
</div>

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

<div id="create-a-pr-from-the-editor">
  ### エディタから PR を作成する
</div>

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

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

<div id="edit-directly-in-your-repository">
  ### リポジトリを直接編集する
</div>

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

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

<div id="devin-suggestions">
  ### Devin の提案
</div>

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

<div id="monorepos-and-workspaces">
  ## モノレポとワークスペース
</div>

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

<div id="root-blueprint-with-includes">
  ### インクルード付きのルートブループリント
</div>

ルートの `.devin/blueprint.yaml` では、どのワークスペースが独自のブループリントを持つかを指定します:

```yaml theme={null}
# my-repo/.devin/blueprint.yaml（ルートブループリント）
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install
```

<div id="workspace-blueprints">
  ### ワークスペースのブループリント
</div>

含まれる各ワークスペースには、固有の `.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
```

<div id="include-rules">
  ### インクルードのルール
</div>

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

<div id="switching-between-git-and-database-modes">
  ## Gitモードとデータベースモードの切り替え
</div>

<div id="switch-to-git">
  ### Git に切り替える
</div>

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

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

<div id="switch-to-database">
  ### データベースに切り替える
</div>

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

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

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

<div id="detached-workspaces">
  ### デタッチされたワークスペース
</div>

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

デタッチされたワークスペースを再度アタッチするには、ソースのドロップダウンでソースを Git に戻します。

<div id="version-history">
  ## バージョン履歴
</div>

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

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

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

<div id="multi-document-yaml">
  ## マルチドキュメントYAML
</div>

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

```yaml theme={null}
# 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 サポート](/ja/onboard-devin/environment/windows-support)を参照してください。

<div id="troubleshooting">
  ## トラブルシューティング
</div>

<div id="blueprint-not-syncing">
  ### ブループリントが同期されない
</div>

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

<div id="invalid-yaml-errors">
  ### 無効な YAML に関するエラー
</div>

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

<div id="blueprint-shows-database-after-pushing">
  ### プッシュ後も Blueprint に "Database" と表示される
</div>

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