宣言的構成 - Devin Docs

はじめに

前提条件: 環境を設定する前に、Devin があなたのリポジトリにアクセスできる必要があります。Git 統合がまだ設定されていない場合は、設定手順について開始前にを参照してください。Enterprise ユーザーは、Enterprise Settings > Repository Permissions で各 org に対応するリポジトリへのアクセスも付与する必要があります。

まだクラシック構成を利用していますか？ 宣言的構成にはいつでも移行できます。移行作業の大半は Devin に任せられます。宣言的構成への移行を参照してください。

Devin に任せる（推奨）
手動セットアップ

ほとんどのユーザーに最適です。Devin がプロジェクトを分析し、必要なツールや依存関係を判断して、ブループリントを生成します。あとは内容を確認して承認するだけです。

Devin セッションを開始する

新しいセッションを開き、Devin にリポジトリの設定を依頼します。たとえば、“この repo の環境を設定してください。“

確認して承認する

Devin がブループリントを提案します。タイムラインに suggestion cards が表示されるので、内容を確認して Approve をクリックしてください。

確認する

ビルドが完了したら、新しいセッションを開始します。Devin は、必要な設定がすべて事前に反映された新しいスナップショットから起動します。lint や test のコマンドを実行するよう Devin に依頼し、問題なく動作することを確認してみてください。

環境に何が必要か正確にわかっている場合や、各手順を完全に制御したい場合に最適です。必要なコマンドがすでに用意されていれば、より早く進められます。

環境設定に移動する

組織のサイドバーで Settings > Environment > Blueprints に移動します。このオプションが表示されない場合、組織はまだ従来のセットアップのままの可能性があります。開始するには宣言的構成への移行を参照してください。

リポジトリを追加する

Repositories セクションで Add をクリックします。Devin に作業させたいリポジトリを選択し、確認します。ここで追加したリポジトリは、各ビルド時に Devin の環境へクローンされます。必要に応じていつでも追加できます。

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

リポジトリをクリックして、そのブループリントエディタを開きます。以下はシンプルな例です。

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 を参照してください。

保存してビルドする

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 を参照してください。

ここでの Knowledge と Knowledge プロダクト機能の違い: ブループリント内の knowledge セクションは、環境に紐づいた短いコマンド参照のためのものです。アーキテクチャドキュメント、慣例、チームのワークフローには、代わりに独立した Knowledge 機能を利用してください。

複数ドキュメント YAML: ブループリントエディタは、--- 区切りを使った複数ドキュメント YAML をサポートしています。これにより、複雑なブループリントを 1 つのエディタ内で論理的なセクションに整理できます。

完全なフィールド仕様 (step types、環境変数、secrets、ファイル添付) については、ブループリントリファレンスを参照してください。

ブループリントの適用範囲

ブループリントは次の 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 を参照してください。

ビルドとセッション

スナップショット

組織には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/<repo-name>):
   a. initialize
   b. maintenance
5. Health check, then snapshot is saved

レイヤーは追加式です。repo 固有のコマンドでは、org ブループリントまたは Enterprise ブループリントでインストールされたツールを利用できます。下位レベルで、上位レベルの設定を上書きすることはできません。ビルドには通常 5～15 分かかります。各ステップは 1 時間でタイムアウトします。

セッションの仕組み

各セッションは、スナップショットのクリーンなコピーで起動します。セッションが終了すると、すべての変更は破棄されます。セッション開始時には、次の処理が行われます。

対象のリポジトリの最新コードが取得されます。
maintenance コマンド (Enterprise、org、repo) は前提情報としてエージェントに提示されますが、自動実行はされません。前回のビルド以降に依存関係が変更されたことをエージェントが検出した場合は、これらを再実行することがあります。
そのリポジトリの knowledge エントリが Devin の前提情報に読み込まれます。

Knowledge はリポジトリ単位です。 5 つのリポジトリを設定している場合、Devin が参照できるのは現在作業中のリポジトリの Knowledge エントリだけです。

ビルドがトリガーされる条件

トリガー	説明
ブループリントの保存	ブループリントの作成、更新、または削除
リポジトリの追加または削除	リポジトリ一覧への変更
リポジトリシークレットの追加	新しいシークレットを利用できるようにするには再ビルドが必要
手動でのトリガー	UI で Build snapshot をクリック
定期的な更新	自動。おおむね 24 時間ごと
Devin からの提案	Devin がセッション中にブループリントの変更を提案

一度に実行できるビルドは 1 つだけです。新しいトリガーが発生すると、キューに入っているビルドはキャンセルされ、新しいビルドが最初から開始されます。

ビルドステータス

ステータス	意味
成功	すべてのステップが完了しました。スナップショットの準備ができています。
部分的	リポジトリ単位の一部のステップは失敗しましたが、スナップショットは利用可能です。成功したリポジトリは通常どおり動作し、失敗したリポジトリではブループリントの修正が必要です。
失敗	重大な障害です (org または Enterprise のセットアップに失敗しました) 。スナップショットは利用できません。
キャンセル済み	より新しいビルドに置き換えられたか、手動でキャンセルされました。

部分的なビルドでも、動作するスナップショットが生成されます。5 つのリポジトリのうち 1 つでブループリントに問題があっても、残り 4 つは完全に機能します。

ビルドが失敗している場合は、ビルドのトラブルシューティングで段階的なデバッグガイドを確認してください。

環境の管理

リポジトリの状態

リポジトリは、Environment の設定画面で次の 3 つの状態で表示されます。

State	Meaning
Configured	initialize/maintenance/knowledge を含むブループリントがあります。スナップショット内で完全にセットアップされています。
Included	スナップショットにクローンされていますが、カスタムブループリントはありません。Devin はコードにアクセスできます。
Available	org には接続されていますが、Environment には追加されていません。クローンもされていません。

Included と Configured の違い: 「Included」のリポジトリはクローンされているため Devin はコードにアクセスできますが、カスタムのセットアップコマンドはありません。一方、「Configured」のリポジトリには、initialize/maintenance/knowledge の instructions が明示的に設定されています。

シークレット

$VARIABLE_NAME 構文でシークレットを参照します。追加するには、ブループリントエディタ内の シークレット タブを開きます。

maintenance:
  - name: Configure private registry
    run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN

シークレットは、ビルド中およびセッション中に環境変数として利用できます。これらはスナップショットが保存される前に削除されますが、initialize 中にコマンドがシークレットの値を設定ファイルに書き込んだ場合、その値はスナップショットに残ります。認証情報を書き込む手順は maintenance に配置し、定期ビルド時に更新されるようにしてください。シークレットのスコープと挙動の詳細については、ブループリントリファレンスを参照してください.

複数のリポジトリ

各リポジトリにはそれぞれ専用のブループリントが割り当てられます。ビルド中は、すべてのリポジトリが同じスナップショット内でセットアップされ、別々のディレクトリにクローンされ、依存関係もそれぞれ個別にインストールされます。 2つのリポジトリがグローバルツールの異なるバージョンをインストールしたり、共有ファイル (~/.bashrc など) を変更したりすると、最後に実行されたものが反映されます。競合を避けるには、共有ツールのインストールを org-wide ブループリントにまとめてください。

GitHub Actions

ツールや実行環境をインストールするためのシェルスクリプトを作成する代わりに、ブループリントで GitHub Actions を直接参照できます。Devin はビルド中にそのアクションをダウンロードして実行します。これは、GitHub の CI ランナーがアクションのステップを実行するのと同じ仕組みです。

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を参照してください。

モノレポ

サブシェルを使えばサブディレクトリでコマンドを実行でき、個々のパッケージ向けに専用のワークスペース単位のブループリントを作成することもできます。Devin はパッケージごとの Knowledge エントリにも対応しているため、各ワークスペースでそれぞれ独自の lint、test、build コマンドを設定できます。セットアップ手順と使用例については、ワークスペースとモノレポを参照してください。

ピン留めと自動更新

デフォルトでは、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ベースのブループリントを参照してください。

ビルドのトラブルシューティング

Initialize ステップが失敗しました

よくある原因: シェルコマンドのタイプミス、パッケージが利用できない、ネットワークのタイムアウト、GitHub Action の参照先の誤り。 対処法: ビルドログで正確なエラー内容を確認してください。ブループリント内の initialize を更新して保存してください。新しいビルドが自動的にトリガーされます。

リポジトリのクローンに失敗しました

主な原因: Devin がリポジトリにアクセスできない、リポジトリの名前が変更された／移動された／削除された、一時的なネットワークの問題。 対処法: Git プロバイダーの設定でリポジトリへのアクセス権を確認してください。リポジトリ名が変更されていた場合は、いったん削除して再度追加してください。

メンテナンス手順が失敗しました

一般的な原因: 依存関係の競合、必要なシステムライブラリの不足、ディスク容量不足、ロックファイルの不整合。 対処法: 失敗したパッケージまたはコマンドのログを確認してください。maintenance または initialize を更新して不足している依存関係をインストールするか、リポジトリ内のロックファイルを修正してください。

ビルドのタイムアウト

各ステップのタイムアウトは1時間です。よくある原因: 大規模なネイティブ依存関係をソースからコンパイルしている (ビルド済みバイナリを利用する) 、大容量のアーティファクトをダウンロードしている、入力待ちで処理が止まるコマンドを実行している (すべてのコマンドは非対話型である必要があります) 。

修正を繰り返す

ビルドログを確認して失敗の原因を特定する
該当するブループリントを更新する
保存する (新しいビルドが自動的にトリガーされます)
新しいビルドのログを確認する
ビルドが成功するまで繰り返す

失敗したビルドの完了を待つ必要はありません。新しい設定を保存すると、キューに入っているビルドはキャンセルされ、新しいビルドが最初から開始されます。

次のステップ

差分ビルド

ブループリントが変更されたワークスペースだけを再ビルドして、ビルドを高速化します。

ブループリントでのGitHub Actions

シェルスクリプトを書かずに、GitHub Actionsを利用して言語、ツール、SDKをインストールできます。

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

複数パッケージのリポジトリで使う、サブシェル、ワークスペースのスコープ、Knowledge エントリ。

ブループリントリファレンス

完全なフィールドリファレンス：step types、環境変数、シークレット、ファイル添付。

Template library

Python、Node.js、Go、Java、Ruby、Rust、高度なパターン向けの、コピーしてすぐ使えるブループリント。

Gitベースのブループリント

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

従来のセットアップからの移行

対話型ウィザードから宣言的なブループリントへ移行するための手順ガイド。

Enterprise環境管理

Enterprise全体の環境管理：3層階層、シークレット、組織横断の設定。

​はじめに

​仕組み

​ブループリント のセクション

​ブループリント の適用範囲

​ビルドとセッション

​スナップショット

​ビルドの仕組み

​セッションの仕組み

​ビルドがトリガーされる条件

​ビルドステータス

​環境の管理

​リポジトリの状態

​シークレット

​複数のリポジトリ

​GitHub Actions

​モノレポ

​ピン留めと自動更新

​Gitベースのブループリント

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

​Initialize ステップが失敗しました

​リポジトリのクローンに失敗しました

​メンテナンス手順が失敗しました

​ビルドのタイムアウト

​修正を繰り返す

​次のステップ

差分ビルド

ブループリントでのGitHub Actions

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

ブループリントリファレンス

Template library

Gitベースのブループリント

従来のセットアップからの移行

Enterprise環境管理

はじめに

仕組み

ブループリントのセクション

ブループリントの適用範囲

ビルドとセッション

スナップショット

ビルドの仕組み

セッションの仕組み

ビルドがトリガーされる条件

ビルドステータス

環境の管理

リポジトリの状態

シークレット

複数のリポジトリ

GitHub Actions

モノレポ

ピン留めと自動更新

Gitベースのブループリント

ビルドのトラブルシューティング

Initialize ステップが失敗しました

リポジトリのクローンに失敗しました

メンテナンス手順が失敗しました

ビルドのタイムアウト

修正を繰り返す

次のステップ