> ## 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.
# 宣言的構成
> YAML ブループリントで環境を定義します。ビルドは自動的に実行され、すべてのセッションの起動元となるスナップショットを生成します。
## はじめに
**前提条件**: 環境を設定する前に、Devin があなたのリポジトリにアクセスできる必要があります。Git 統合がまだ設定されていない場合は、設定手順について [開始前に](/ja/onboard-devin/environment#before-you-start) を参照してください。Enterprise ユーザーは、**Enterprise Settings > Repository Permissions** で各 org に対応するリポジトリへのアクセスも付与する必要があります。
**まだクラシック構成を利用していますか？** 宣言的構成にはいつでも移行できます。移行作業の大半は Devin に任せられます。[宣言的構成への移行
](/ja/onboard-devin/environment/migration) を参照してください。
ほとんどのユーザーに最適です。Devin がプロジェクトを分析し、必要なツールや依存関係を判断して、ブループリントを生成します。あとは内容を確認して承認するだけです。
新しいセッションを開き、Devin にリポジトリの設定を依頼します。たとえば、*"この repo の環境を設定してください。"*
Devin がブループリントを提案します。タイムラインに **suggestion cards** が表示されるので、内容を確認して **Approve** をクリックしてください。
ビルドが完了したら、新しいセッションを開始します。Devin は、必要な設定がすべて事前に反映された新しいスナップショットから起動します。lint や test のコマンドを実行するよう Devin に依頼し、問題なく動作することを確認してみてください。
環境に何が必要か正確にわかっている場合や、各手順を完全に制御したい場合に最適です。必要なコマンドがすでに用意されていれば、より早く進められます。
組織のサイドバーで **Settings > Environment > Blueprints** に移動します。
このオプションが表示されない場合、組織はまだ従来のセットアップのままの可能性があります。開始するには [宣言的構成への移行](/ja/onboard-devin/environment/migration) を参照してください。
Repositories セクションで **Add** をクリックします。Devin に作業させたいリポジトリを選択し、確認します。
ここで追加したリポジトリは、各ビルド時に Devin の環境へクローンされます。必要に応じていつでも追加できます。
リポジトリをクリックして、そのブループリントエディタを開きます。以下はシンプルな例です。
```yaml theme={null}
initialize: |
curl -LsSf https://astral.sh/uv/install.sh | sh
maintenance: |
uv sync
knowledge:
- name: lint
contents: uv run ruff check .
- name: test
contents: uv run pytest
```
より多くの言語やパターンについては、[Template library](/ja/onboard-devin/environment/templates) を参照してください。
**Save** をクリックします。ビルドは自動的に開始されます (通常 2～10 分) 。進行状況は、**Current build** の **Settings > Environment > Snapshots** で確認できます。
ビルドが **Success** と表示されたら、新しい Devin セッションを開始します。Devin は、必要な設定がすべて事前に反映された新しいスナップショットから起動します。環境が正しく動作することを確認するために、lint や test のコマンドを実行するよう Devin に依頼してみてください。
このガイドの残りの部分では、手動での進め方を詳しく説明します。推奨される方法を利用した場合でも、Devin が何を生成したのかを理解するうえで役立ちます。
## 仕組み
宣言的構成では、3 つの概念を使用します。
| Concept | What it is | Analogy |
| ------------- | -------------------------------------------- | -------------- |
| **Blueprint** | インストールする内容と Devin の環境の設定方法を記述した YAML 構成ファイル | Dockerfile |
| **ビルド** | ブループリント を実行し、repo をクローンして、スナップショット を生成するプロセス | `docker build` |
| **Snapshot** | セッションの起動元となる、固定された起動可能な環境イメージ | Docker image |
**ブループリント は必要な内容を記述します。** これらはユーザーが作成し、Settings UI で編集します。
**ビルド は ブループリント を実行して スナップショット を生成します。** ビルド は ブループリント を保存すると自動的に実行され、dependencies を最新の状態に保つために定期的 (約 24 時間ごと) にも実行されます。
**スナップショット はセッションの起動元です。** 各組織には 1 つのアクティブな スナップショット があります。すべてのセッションはクリーンなコピーから起動します。セッションでの changes は スナップショット には保持されません。
### ブループリント のセクション
ブループリント には 3 つのセクションに加え、repo-level のブループリント用に任意の `clone` ブロックがあります。
| セクション | 目的 | 実行されるタイミング |
| ------------- | --------------------------------------------- | ----------------------------------------- |
| `initialize` | ツール、ランタイム、システムパッケージをインストール | ビルド時のみ。結果はスナップショットに保存されます。 |
| `maintenance` | プロジェクトの依存関係をインストール/更新し、認証情報の設定を書き込む | ビルド時。セッション開始時にエージェントに提示されます (自動実行はされません)。 |
| `knowledge` | Devin 向けの参照情報 (lint、test、build コマンド) | 実行されません。セッション開始時に Devin の前提情報に読み込まれます。 |
| `clone` | リポジトリの git clone のデフォルトを上書きする (repo-level のみ) | ビルドの clone ステップ中に適用されます。 |
**`initialize`** は、一度だけ実行すればよい処理のためのセクションです。たとえば、言語ランタイム、システムパッケージ、グローバル CLI ツールなどです。
**`maintenance`** は、常に最新の状態に保つ必要がある依存関係のインストール向けです。ビルド時に実行され、セッション開始時にはエージェントに提示されるため、依存関係が変更されていれば再実行できます (たとえば最新コードを pull した後など)。コマンドはセッション開始時に自動実行されませんが、それでも高速で増分的なものにしてください (`npm ci` ではなく `npm install` を利用する) 。
**`knowledge`** は参照情報であり、実行はされません。ここで、lint、test、build の正しいコマンドを Devin に伝えます。項目は簡潔に保ち、実行可能なコマンドに絞ってください。
**`clone`** (repo-level のみ) は、リポジトリをスナップショットに clone する際に Devin が利用するデフォルトを上書きします。たとえば、デフォルト以外のブランチをチェックアウトする (`ref`)、clone 先 (`path`) を変更する、またはサブモジュールや LFS オブジェクトをスキップする、といったことができます。各フィールドは任意です。完全なフィールド一覧については、[ブループリントリファレンス → clone](/ja/onboard-devin/environment/blueprint-reference#clone) を参照してください。
**ここでの Knowledge と Knowledge プロダクト機能の違い:** ブループリント 内の `knowledge` セクションは、環境に紐づいた短いコマンド参照のためのものです。アーキテクチャドキュメント、慣例、チームの
ワークフローには、代わりに独立した [Knowledge](/ja/product-guides/knowledge) 機能を利用してください。
**複数ドキュメント YAML:** ブループリントエディタは、`---` 区切りを使った複数ドキュメント YAML をサポートしています。これにより、複雑なブループリントを 1 つのエディタ内で論理的なセクションに整理できます。
完全なフィールド仕様 (step types、環境変数、secrets、ファイル添付) については、[ブループリントリファレンス](/ja/onboard-devin/environment/blueprint-reference) を参照してください。
### ブループリント の適用範囲
ブループリント は次の 2 つのレベルで定義できます。
| Level | Where to configure | What to put here |
| --------- | ---------------------------------------------------- | --------------------------------------------------- |
| **組織** | Settings > Environment > Blueprints > Org-wide setup | すべてのリポジトリで共有するツール: 言語ランタイム、パッケージマネージャー、Docker 認証 |
| **リポジトリ** | Settings > Environment > Blueprints > \[repo name] | プロジェクト固有のセットアップ: `npm install`、lint/test/build コマンド |
ブループリント は**追加式**です。リポジトリの ブループリント は、組織の ブループリント を基盤としてその上に追加されます。リポジトリの `maintenance` では、組織の `initialize` でインストールされたツールを利用できます。特定のツールが 1 つのリポジトリでのみ必要な場合は、そのリポジトリの ブループリント に追加してください。すべてのリポジトリで必要な場合は、組織の ブループリント に追加してください。
**Enterprise ユーザー:** 3 つ目の階層として、すべての組織に適用される Enterprise ブループリント があります。詳しくは [Enterprise environment overview](/ja/enterprise/environment-management/overview) を参照してください。
## ビルドとセッション
### スナップショット
組織には**1つのアクティブなスナップショット**があります。これは、ツール、リポジトリ、依存関係があらかじめインストールされた VM イメージです。設定されたすべてのリポジトリは、この単一のイメージ内にクローンされ、セットアップされます。各セッションはクリーンなコピーから起動します。
### ビルドの仕組み
ビルドは、ブループリントを順番に実行して新しいスナップショットを作成します。
```
1. Enterprise blueprint, if configured (runs in ~):
a. initialize
b. maintenance
2. Org blueprint (runs in ~):
a. initialize
b. maintenance
3. Clone all repositories (up to 10 concurrent).
Each repo's blueprint may override clone defaults via the
`clone` block (branch/tag, depth, submodules, LFS, etc.).
4. For each configured repo, in the order shown in Settings
(runs in ~/repos/):
a. initialize
b. maintenance
5. Health check, then snapshot is saved
```
レイヤーは**追加式**です。repo 固有のコマンドでは、org ブループリント または Enterprise ブループリント でインストールされたツールを利用できます。下位レベルで、上位レベルの設定を上書きすることはできません。ビルドには通常 5～15 分かかります。各ステップは 1 時間でタイムアウトします。
### セッションの仕組み
各セッションは、スナップショットの**クリーンなコピー**で起動します。セッションが終了すると、すべての変更は破棄されます。セッション開始時には、次の処理が行われます。
1. 対象のリポジトリの最新コードが取得されます。
2. `maintenance` コマンド (Enterprise、org、repo) は前提情報としてエージェントに提示されますが、**自動実行はされません**。前回のビルド以降に依存関係が変更されたことをエージェントが検出した場合は、これらを再実行することがあります。
3. そのリポジトリの `knowledge` エントリが Devin の前提情報に読み込まれます。
**Knowledge はリポジトリ単位です。** 5 つのリポジトリを設定している場合、Devin が参照できるのは現在作業中のリポジトリの Knowledge エントリだけです。
### ビルドがトリガーされる条件
| トリガー | 説明 |
| -------------- | ----------------------------- |
| ブループリントの保存 | ブループリントの作成、更新、または削除 |
| リポジトリの追加または削除 | リポジトリ一覧への変更 |
| リポジトリシークレットの追加 | 新しいシークレットを利用できるようにするには再ビルドが必要 |
| 手動でのトリガー | UI で **Build snapshot** をクリック |
| 定期的な更新 | 自動。おおむね 24 時間ごと |
| Devin からの提案 | Devin がセッション中にブループリントの変更を提案 |
一度に実行できるビルドは 1 つだけです。新しいトリガーが発生すると、キューに入っているビルドはキャンセルされ、新しいビルドが最初から開始されます。
### ビルドステータス
| ステータス | 意味 |
| ----------- | -------------------------------------------------------------------------------------- |
| **成功** | すべてのステップが完了しました。スナップショットの準備ができています。 |
| **部分的** | リポジトリ単位の一部のステップは失敗しましたが、スナップショットは利用可能です。成功したリポジトリは通常どおり動作し、失敗したリポジトリではブループリントの修正が必要です。 |
| **失敗** | 重大な障害です (org または Enterprise のセットアップに失敗しました) 。スナップショットは利用できません。 |
| **キャンセル済み** | より新しいビルドに置き換えられたか、手動でキャンセルされました。 |
**部分的**なビルドでも、動作するスナップショットが生成されます。5 つのリポジトリのうち 1 つでブループリントに問題があっても、残り 4 つは完全に機能します。
**ビルドが失敗している場合**は、[ビルドのトラブルシューティング](#troubleshooting-builds)で段階的なデバッグガイドを確認してください。
## 環境の管理
### リポジトリの状態
リポジトリは、Environment の設定画面で次の 3 つの状態で表示されます。
| State | Meaning |
| -------------- | ------------------------------------------------------------------------------ |
| **Configured** | initialize/maintenance/knowledge を含む ブループリント があります。スナップショット 内で完全にセットアップされています。 |
| **Included** | スナップショット にクローンされていますが、カスタム ブループリント はありません。Devin はコードにアクセスできます。 |
| **Available** | org には接続されていますが、Environment には追加されていません。クローンもされていません。 |
**Included と Configured の違い:** 「Included」のリポジトリはクローンされているため Devin はコードにアクセスできますが、カスタムのセットアップコマンドはありません。一方、「Configured」のリポジトリには、initialize/maintenance/knowledge の instructions が明示的に設定されています。
### シークレット
`$VARIABLE_NAME` 構文でシークレットを参照します。追加するには、ブループリントエディタ内の **シークレット** タブを開きます。
```yaml theme={null}
maintenance:
- name: Configure private registry
run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
```
シークレットは、ビルド中およびセッション中に環境変数として利用できます。これらはスナップショットが保存される前に削除されますが、`initialize` 中にコマンドがシークレットの値を設定ファイルに書き込んだ場合、その値はスナップショットに残ります。認証情報を書き込む手順は `maintenance` に配置し、定期ビルド時に更新されるようにしてください。
シークレットのスコープと挙動の詳細については、[ブループリントリファレンス](/ja/onboard-devin/environment/blueprint-reference#environment-variables-and-secrets) を参照してください.
### 複数のリポジトリ
各リポジトリにはそれぞれ専用のブループリントが割り当てられます。ビルド中は、すべてのリポジトリが同じスナップショット内でセットアップされ、別々のディレクトリにクローンされ、依存関係もそれぞれ個別にインストールされます。
2つのリポジトリがグローバルツールの異なるバージョンをインストールしたり、共有ファイル (`~/.bashrc` など) を変更したりすると、最後に実行されたものが反映されます。競合を避けるには、共有ツールのインストールを org-wide ブループリントにまとめてください。
### GitHub Actions
ツールや実行環境をインストールするためのシェルスクリプトを作成する代わりに、ブループリントで GitHub Actions を直接参照できます。Devin はビルド中にそのアクションをダウンロードして実行します。これは、GitHub の CI ランナーがアクションのステップを実行するのと同じ仕組みです。
```yaml theme={null}
initialize:
- name: Install Python 3.12
uses: github.com/actions/setup-python@v5
with:
python-version: "3.12"
```
これは特に、バージョン管理や PATH の設定を自動で行う `setup-python`、`setup-node`、`setup-go` といった言語セットアップ用アクションで役立ちます。
構文の詳細、使用例、制限事項については、[ブループリントでのGitHub Actions](/ja/onboard-devin/environment/github-actions)を参照してください。
### モノレポ
サブシェルを使えばサブディレクトリでコマンドを実行でき、個々のパッケージ向けに専用のワークスペース単位のブループリントを作成することもできます。Devin はパッケージごとの Knowledge エントリにも対応しているため、各ワークスペースでそれぞれ独自の lint、test、build コマンドを設定できます。
セットアップ手順と使用例については、[ワークスペースとモノレポ](/ja/onboard-devin/environment/workspaces)を参照してください。
### ピン留めと自動更新
デフォルトでは、Devin は最新の成功したビルドのスナップショットを利用します。**ピン留め**を使うと、特定のビルドのスナップショットに固定できます。これは、新しいビルドで不具合が発生した場合や、一連のセッションで環境を固定したい場合に便利です。
**ピン留めするには:** **Settings > Environment > Snapshots** に移動し、履歴内で対象のビルド (`success` または `partial` で、7 日以内のもの) を見つけて、**Pin** をクリックします。ピン留め中は定期的な更新がスキップされ、UI には **Auto-updates paused** と表示されます。
**ピン留めを解除するには:** **Resume auto-updates** をクリックします。Devin は最新の成功したビルドに切り替わります。
### Gitベースのブループリント
ブループリントは、`.devin/blueprint.yaml` ファイルとしてリポジトリ内に直接保存できます。変更をマージしたら、sync API を呼び出すか、UI で Sync をクリックしてブループリントを更新し、その後ビルドをトリガーします。これにより、アプリケーションコードで利用しているのと同じコードレビューのワークフローを使いながら、CI ステップで sync を自動化できます。
セットアップ手順と詳細については、[Gitベースのブループリント](/ja/onboard-devin/environment/git-backed-blueprints) を参照してください。
## ビルドのトラブルシューティング
### Initialize ステップが失敗しました
**よくある原因:** シェルコマンドのタイプミス、パッケージが利用できない、ネットワークのタイムアウト、GitHub Action の参照先の誤り。
**対処法:** ビルドログで正確なエラー内容を確認してください。ブループリント 内の `initialize` を更新して保存してください。新しいビルドが自動的にトリガーされます。
### リポジトリのクローンに失敗しました
**主な原因:** Devin がリポジトリにアクセスできない、リポジトリの名前が変更された／移動された／削除された、一時的なネットワークの問題。
**対処法:** Git プロバイダーの設定でリポジトリへのアクセス権を確認してください。リポジトリ名が変更されていた場合は、いったん削除して再度追加してください。
### メンテナンス手順が失敗しました
**一般的な原因:** 依存関係の競合、必要なシステムライブラリの不足、ディスク容量不足、ロックファイルの不整合。
**対処法:** 失敗したパッケージまたはコマンドのログを確認してください。`maintenance` または `initialize` を更新して不足している依存関係をインストールするか、リポジトリ内のロックファイルを修正してください。
### ビルドのタイムアウト
各ステップのタイムアウトは1時間です。よくある原因: 大規模なネイティブ依存関係をソースからコンパイルしている (ビルド済みバイナリを利用する) 、大容量のアーティファクトをダウンロードしている、入力待ちで処理が止まるコマンドを実行している (すべてのコマンドは非対話型である必要があります) 。
### 修正を繰り返す
1. ビルドログを確認して失敗の原因を特定する
2. 該当するブループリントを更新する
3. 保存する (新しいビルドが自動的にトリガーされます)
4. 新しいビルドのログを確認する
5. ビルドが成功するまで繰り返す
失敗したビルドの完了を待つ必要はありません。新しい設定を保存すると、キューに入っているビルドはキャンセルされ、新しいビルドが最初から開始されます。
## 次のステップ
ブループリントが変更されたワークスペースだけを再ビルドして、ビルドを高速化します。
シェルスクリプトを書かずに、GitHub Actionsを利用して言語、ツール、SDKをインストールできます。
複数パッケージのリポジトリで使う、サブシェル、ワークスペースのスコープ、Knowledge エントリ。
完全なフィールドリファレンス：step types、環境変数、シークレット、ファイル添付。
Python、Node.js、Go、Java、Ruby、Rust、高度なパターン向けの、コピーしてすぐ使えるブループリント。
ブループリントをリポジトリ内の `.devin/blueprint.yaml` として保存し、APIまたはUI経由で同期します。
対話型ウィザードから宣言的なブループリントへ移行するための手順ガイド。
Enterprise全体の環境管理：3層階層、シークレット、組織横断の設定。