メインコンテンツへスキップ
一般的なビルド失敗の解決策、よくある質問への回答、レガシーな対話型セットアップから移行するためのガイドです。
一般的な環境設定については、Environment Configuration を参照してください。構文の詳細については、YAML Reference を参照してください。

​
build の失敗をデバッグする

​
ステップ 1: ビルドのステータスを確認する

Settings > Devin’s Environment > Build History に移動します。ビルドには、次のいずれかのステータスが表示されます。
ステータス意味対応
Successすべて正常に完了した対応不要 — マシンイメージの準備は完了しています
Partialコアのビルドは成功したが、一部の repo は失敗したどの repo が失敗したかを確認してください。該当するセッションに問題がある可能性があります
Failedビルド自体が失敗した失敗したステップのログを確認してください
Cancelledより新しいビルドによってこのビルドが置き換えられた正常です — 必要に応じて新しいビルドを開始してください
Skipped設定変更が検出されなかった対応不要 — ビルドは必要ありませんでした

​
ステップ 2: ビルドログを確認する

ビルドログはステップごとに整理されています。
  1. Shared setup — Enterprise + org-wide のコマンド
  2. Clone — リポジトリ のクローン
  3. Repo setup — リポジトリ ごとのコマンド
  4. Finalize — ヘルスチェックとイメージの作成
ログでは最初のエラーを探してください。後続のエラーは、多くの場合、最初のエラーに起因する連鎖的な失敗です。
name フィールドを含む expanded form を利用した場合、ログにはどのステップが失敗したかが正確に表示されます。これは、ステップに名前を付ける大きな利点の 1 つです。 
# 名前なし — デバッグが困難
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  npm install -g pnpm

# 名前あり — 失敗箇所を特定しやすい
initialize:
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh
  - name: Install pnpm
    run: npm install -g pnpm

​
ステップ 3: 失敗パターンを特定する

​
クローン失敗

症状: クローン中にビルドが失敗します。 よくある原因:
  • リポジトリへのアクセスが設定されていない — Enterprise Settings > Integrations を確認してください
  • 非公開リポジトリには認証トークンが必要です
  • リポジトリの名前が変更された、または削除された
  • ネットワーク接続の問題 (VPN またはプロキシが必要)
対処法: integration settings で、Devin がリポジトリにアクセスできることを確認してください。非公開レジストリの場合は、Secrets に認証情報が設定されていることを確認してください。

​
依存関係のインストール失敗

症状: リポジトリのセットアップ中にビルドが失敗し、通常は npm install、pip install、または同様の処理で発生します。 よくある原因:
  • 非公開パッケージレジストリで認証が必要 — Secrets にトークンを追加する
  • パッケージのバージョン競合 — 特定のバージョンに固定する
  • ネットワークのタイムアウト — VPN が必要か確認する
  • レジストリ URL の設定ミス
対処法: maintenance セクションにレジストリ認証を追加します。非公開レジストリのパターンについては、Configuration 使用例 を参照してください。

​
タイムアウトによる失敗

症状: ビルドが止まったように見えた後、失敗します。 よくある原因:
  • 対話型プロンプトが入力待ちになっている — -y フラグを追加し、DEBIAN_FRONTEND=noninteractive を利用する
  • 非常に大きな依存関係のインストールに時間がかかりすぎている
  • コマンドが1時間のタイムアウトを超えている
対処法: すべてのインストールコマンドに非対話型フラグを追加します。時間のかかる1回限りのインストールは initialize に移し、ビルド時にのみ実行されるようにします (すべてのセッションではなく) 。 
# 悪い例 — 入力待ちでハングする
initialize: |
  sudo apt-get install libpq-dev

# 良い例 — 非対話型
initialize: |
  sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq libpq-dev

​
権限エラー

症状: ログに「Permission denied」と表示される。 よくある原因:
  • システムパッケージのインストール時に sudo を付けていない
  • 保護されたディレクトリに書き込もうとしている
  • 前回のビルドで別のユーザーが所有者になったファイルが残っている
対処法: システムレベルの操作 (apt-get、/etc/ への書き込みなど) では sudo を利用します。ユーザーレベルのパッケージマネージャー (npm、pip、cargo) では、通常 sudo は不要です。

​
“Command not found” エラー

症状: initialize でインストールしたツールが、maintenance またはそれ以降のステップで利用できません。 よくある原因:
  • ツールが PATH に含まれていないディレクトリにインストールされている
  • シェルプロファイル (.bashrc) への変更が、後続のステップで反映されていない
対処法: $ENVRC を使ってツールのディレクトリを PATH に追加します: 
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC

​
ステップ4: 調整を繰り返す

問題を特定したら:
  1. YAML 設定を修正する
  2. 保存する — 新しいビルドが自動的に自動的に開始される
  3. 新しいビルドのログを確認する
まずコマンドをテストしてください。 コマンドを設定に追加する前に、Devin セッションで実行して、正しく動作することを確認してください。こちらのほうが、ビルドサイクルが一通り終わるのを待つよりも速く済みます。

​
よくあるエラー早見表

エラー主な原因対処方法
command not foundツールがインストールされていない、または PATH が通っていないinitialize に追加するか、$ENVRC で PATH に追加する
Permission deniedsudo が付いていないシステムパッケージには sudo apt-get install を利用する
npm ERR! 404非公開パッケージで、認証が設定されていないmaintenance にレジストリの認証トークンを追加する (使用例)
E: Unable to locate package最初に apt-get update を実行していないapt-get install の前に sudo apt-get update -qq を追加する
Timeoutインストールに時間がかかっている、または対話式プロンプトがあるinitialize に移し、-y と DEBIAN_FRONTEND=noninteractive を追加する
セッション開始後に設定ファイルが空になる認証情報を initialize に書き込んでいる認証情報の設定手順を maintenance に移す
ビルドは成功するがセッションが正常に使えないセッション開始時に maintenance コマンドが失敗しているセッション内で maintenance コマンドを手動でテストする

​
対話型セットアップからの移行

現在レガシーな対話型セットアップ (ステップごとのウィザード) を利用している場合は、より高い再現性と複数のrepoへの対応のために、宣言的の設定へ移行できます。

​
移行の仕組み

レガシーセットアップと宣言的設定では、それぞれ別々のマシンイメージが生成されます。セッションで利用されるのはどちらか一方のみで、両者を組み合わせることはありません。どちらのイメージを利用するかは、“Use legacy machine snapshot” という org-level の切り替えで制御されます。
  • 切り替えが ON (既定) — すべてのセッションでレガシースナップショットが利用されます。影響はありません。
  • 切り替えが OFF — すべてのセッションで宣言的スナップショットが利用されます。
つまり、他の全員がレガシースナップショットで作業を続ける中でも、並行して宣言的設定を構成し、テストできます。

​
移行手順

1

設定を準備する

現在の対話型セットアップで使っているコマンドを確認し、YAML の各セクションに対応付けます。
レガシーウィザードの手順宣言的設定での対応先
Git pull自動 (組み込み)
Secrets を設定Secrets (変更なし)
依存関係をインストールinitialize セクション
依存関係を維持maintenance セクション
lint を設定名前が lint の knowledge エントリ
テストを設定名前が test の knowledge エントリ
ローカルアプリを実行名前が startup の knowledge エントリ
補足メモ名前が notes の knowledge エントリ
2

YAML を作成する

Settings > Devin’s Environment に移動し、対象のリポジトリを選択します。レガシー環境のコマンドを次のように対応付けます。
# レガシーの「Install Dependencies」→ initialize
initialize: |
  nvm use 18
  npm install -g pnpm

# レガシーの「Maintain Dependencies」→ maintenance
maintenance: |
  pnpm install

# レガシーの「Set up lint/tests/app/notes」→ knowledge
knowledge:
  - name: lint
    contents: |
      pnpm lint
  - name: test
    contents: |
      pnpm test
  - name: startup
    contents: |
      pnpm dev (port 3000)
  - name: notes
    contents: |
      Always run lint before committing.
または、Devin のセッションを開始してリポジトリのセットアップを依頼するだけでもかまいません。Devin が設定を自動生成できます。
3

保存してビルドを待つ

設定を保存します。ビルドは自動的に開始されます。進行状況は Build History で確認してください。ビルドは無料で、ACU は消費されません。
4

切り替え前にテストする

全員を移行する前に、manual override を使って個別のセッションで宣言的セットアップをテストしてください。これにより、設定を調整している人だけが宣言的スナップショットを利用し、それ以外のユーザーは引き続きレガシースナップショットを利用できます。宣言的セットアップがレガシー環境と完全に同等になるまで、設定を繰り返し調整してください。
5

切り替える

問題ないことを確認したら、org 設定で OFF の “Use legacy machine snapshot” を切り替えます。以降、新しいすべてのセッションで宣言的スナップショットが利用されます。
対話型の認証フロー (例: AWS SSO (シングルサインオン) のブラウザーログイン、ブラウザーが必要な OAuth フロー) は、宣言的形式では再現できません。レガシーセットアップでブラウザーベースの認証を利用している場合は、移行前にそれらのフローをヘッドレスな代替手段 (APIキー、service account token など) に置き換える必要があります。認証情報を Secrets に追加し、maintenance セクションで参照してください。

​
Enterprise への移行

複数の組織を持つ Enterprise の場合:
  1. まず Enterprise レベルの YAML を設定します — VPN、証明書、プロキシ設定などの共有インフラを対象とします。
  2. org は 1 つずつ移行します。 各 org には個別のレガシートグルがあるため、他のチームに影響を与えずに段階的に移行できます。
  3. テスト用の org を検討します。 大規模な Enterprise では、本番 org に展開する前に、宣言的な設定を検証するための専用のテスト組織を作成します。
  4. 大規模展開には Devin を利用します。 Devin は並列セッションで repo を設定できます — repo ごとに 1 つのセッションを起動すると、Devin が設定提案を自動生成します。これは 10〜100 以上の repo のオンボーディングに適しています。

​
古いスナップショットはどうなりますか？

古いスナップショットは保持されます。新しい宣言的ビルドが失敗した場合、Devin は直近で成功したスナップショット (レガシーのスナップショットである場合もあります) にフォールバックします。以前のスナップショットは、Build History から復元することもできます。

​
主な違い

機能レガシー (対話型)宣言的 (YAML)
再現性状態を保持 — スナップショットに変更が時間とともに蓄積されるYAML から完全に再現可能
マルチrepo一度に1つの repo のみ1回のビルドで複数の repo を同時にクローン可能
メンテナンス手動の「依存関係のメンテナンス」ステップ自動 — maintenance がセッション開始時に実行される
Enterprise/org レイヤー非対応3 層階層 (Enterprise → Org → Repo)
Devin の提案ウィザード内のみセッション内 — Devin が設定の更新を提案可能
コストウィザードのセッションで ACU を利用セットアップ セッションは約 1〜3 ACU、ビルドは無料

​
よくある質問

​
一般

セットアップされていないrepoでセッションを実行するとどうなりますか？ Devin は引き続き動作しますが、毎回プロジェクトをゼロから把握する必要があります。つまり、依存関係のインストール、ビルドやテストの方法の特定、規約の推測に時間がかかります。セッションは長くなり、消費する ACU も増えます。環境をセットアップしておけば、Devin は毎回のセッションを事前設定済みですぐに使える状態で開始できます。 ビルドにはどれくらい時間がかかりますか？ 通常は、repoの数や依存関係のサイズに応じて 5〜15 分です。ビルドは 2 時間でタイムアウトします。 費用はどれくらいかかりますか？ ビルドは 無料 で、ACU はかかりません。Devin のセッションを使ってrepoをセットアップする場合 (たとえば、Devin に設定の生成を依頼する場合) 、そのセッションには通常 1〜3 ACU かかります。設定が保存されると、それ以降その設定から行うすべてのビルドは無料です。 レガシーセットアップと宣言的セットアップの両方を利用できますか？ 組織では一度に 1 つのモードのみを利用でき、「Use legacy machine snapshot」トグルで制御されます。トグルがオンのまま (レガシーモード) でも、並行して宣言的セットアップを設定し、準備ができたら切り替えられます。詳しくは 移行ガイド を参照してください。 他のユーザーに影響を与えずに宣言的セットアップをテストできますか？ はい。個別のセッションで manual override を利用すると、他の全員がレガシー スナップショットを利用したまま、そのセッションだけ一時的に宣言的スナップショットを利用できます。Enterprise の場合は、専用のテスト組織を作成することもできます。 ビルドが失敗した場合はどうなりますか？ Devin は直近で成功したスナップショットを利用します。ビルドが失敗しても、既存のセッションが壊れることはありません。 initialize と maintenance はいつ使い分けるべきですか？ initialize は、1回限りのツールのインストール (apt-get install、言語ランタイムのセットアップ、グローバル CLI ツール) に利用します。maintenance は、常に最新の状態を保つ必要がある依存関係のインストール (npm install、pip install、uv sync) に利用します。 環境変数を追加するにはどうすればよいですか？ $ENVRC に書き込みます： 
initialize: |
  echo "MY_VAR=value" >> $ENVRC
システムパッケージをインストールできますか？ はい。initialize セクションで sudo apt-get install を利用してください。対話式のプロンプトが表示されないよう、常に DEBIAN_FRONTEND=noninteractive と -y フラグを利用してください。 repoごとに異なる Node バージョンが必要な場合はどうすればよいですか？ repo単位の設定で nvm を利用してください。 
initialize: |
  nvm install 18
  nvm use 18
対話型の認証フローはサポートされていますか？ いいえ。ブラウザベースの認証 (AWS SSO (シングルサインオン) ログインや、ブラウザウィンドウを必要とする OAuth フローなど) は、宣言的な形式では再現できません。これらはヘッドレスな代替手段に置き換えてください。APIキー、サービスアカウントのトークン、またはその他の認証情報ベースの方法を利用し、それらをSecretsに保存してください。 現在のところ、ブラウザベースの SSO (シングルサインオン) を厳密に必要とするワークフローに対する回避策はありません。こうしたrepoでは、ヘッドレスな代替手段が利用可能になるまで、引き続き対話型セットアップを利用する必要があります.

​
ビルド固有

「partial success」とはどういう意味ですか？ コアとなるビルド (enterprise + org のセットアップ + クローン作成) は成功しましたが、1 つ以上のリポジトリ単位のセットアップに失敗しました。セッションは動作しますが、失敗した repo では依存関係が正しくインストールされていない可能性があります。 ビルドがキャンセルされたのはなぜですか？ ビルドが完了する前に、より新しいビルドがトリガーされました。実行されるのは最新のビルドのみで、キューに入っていた古いビルドは自動的にキャンセルされます。 1 つの repo の設定を変更すると、すべて再ビルドされますか？ はい。ビルドでは、設定済みのすべての repo を含む 1 つの machine image が作成されます。どの設定を変更しても、完全な再ビルドがトリガーされます。 以前のビルドにロールバックできますか？ はい。Environment Settings の Build History から行えます。以前に成功した snapshot はどれでも復元できます。 含められる repo の数はいくつまでですか？ ビルド中は、最大 10 個の repo が同時にクローンされます。repo の総数に厳密な上限はありませんが、repo が多いほどビルド時間は長くなります。Devin は並列セッションを使って、多数の repo を大規模に設定できます。10～100 個以上の repo を扱う場合は、repo ごとに 1 つのセッションを起動してください。

​
Enterprise 固有

Enterprise レベルの設定を編集できるのは誰ですか？ Enterprise Admin のみです。org admin は org-wide 設定と repo レベルの設定を編集できます。通常のメンバーは、ManageOrgSnapshots 権限があれば repo レベルの設定を編集できます。権限の一覧は、Enterprise Environment Setup を参照してください。 Enterprise 設定を変更すると、すべての org が rebuild されますか？ はい。Enterprise レベルの変更により、Enterprise 内のすべての組織で build がトリガーされます。 org ごとに異なる設定を使えますか？ はい。各 org には、それぞれ独自の org-wide 設定と repo レベルの設定があります。Enterprise 設定は共有され、追加で適用されます。実行されるのは各 org の設定より前です。 下位レベルの設定で上位レベルの設定を上書きできますか？ いいえ。階層 (Enterprise → Org → Repo) は厳密に追加のみです。各レベルのコマンドは、前のレベルの完了後に順番に実行されます。下位レベルでは、上位レベルで設定された内容を無効化したり変更したりすることはできません。 Enterprise レベルの設定でリポジトリ を clone できますか？ いいえ。リポジトリ の clone には org レベルのアクセスが必要です。Enterprise レベルの設定では、共有のツールやインフラストラクチャをインストールできますが、repo の clone は org レベルまたは repo レベルで設定する必要があります。

​
既知の制限事項

  • ビルドプレビュー/サンドボックスなし — 設定を変更するたびにフルビルドがトリガーされます。まずセッションでコマンドをテストしてください。
  • リポジトリのセットアップは順次実行 — リポジトリ単位のセットアップは、一度に 1 つのリポジトリずつ実行されます (アルファベット順) 。リポジトリ数が多いほど、ビルドに時間がかかります。
  • YAML に条件分岐ロジックなし — この形式は if/else をサポートしていません。必要に応じて、コマンド内でシェルの条件分岐を利用してください (例: [ -f package.json ] && npm install) 。
  • ビルドログの検索不可 — ビルドログは手動でスクロールする必要があります。名前付きステップを利用すると、失敗箇所を見つけやすくなります。

​
次のステップ

  • 環境設定 — 設定ファイルを作成するためのメインガイド
  • 設定の使用例 — スタック別・レイヤー別にコピー＆ペーストして使える使用例