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

これはブループリントの完全なフィールドリファレンスです。ブループリントの概要と、Devin の環境内でどのように機能するかについては、宣言的環境設定を参照してください。

ブループリントは、Devin の環境をどのように構成するかを定義します。具体的には、どのツールをインストールするか、依存関係をどのように最新の状態に保つか、そして Devin が認識しておくべきコマンドを定めます。

概要

ブループリントは、次の 3 つのトップレベルセクションで構成されています。

initialize: ...   # ツールとランタイムをインストール
maintenance: ...  # プロジェクトの依存関係をインストール
knowledge: ...    # Devin向けの参照情報（実行されない）

Section	目的	実行されるか
`initialize`	システムツール、言語ランタイム、グローバル CLI をインストールする	はい。各ビルド時に実行されます
`maintenance`	プロジェクトの依存関係をインストールし、更新する	はい。ビルド時に実行されます。セッション開始時にエージェントに提示されます (自動実行はされません) 。
`knowledge`	lint、test、build の方法や、その他のプロジェクト固有の情報を Devin に伝える	いいえ。参照情報として提供されます

3 つのセクションはすべて任意です。任意の組み合わせで含めることができます。 initialize はビルド時にのみ実行されます。結果はスナップショットに保存されます。maintenance はビルド時 (initialize の後) に実行されます。各セッションの開始時には、maintenance コマンドは 自動実行されません。代わりに、必要に応じて (たとえば最新のコードを pull した後に) どの依存関係コマンドを実行すべきかをエージェントが把握できるよう、前提情報として提示されます。コマンドは高速で、差分的に実行できるものにしてください。ビルドはブループリントが変更されたときと、定期的 (約 24 時間ごと) に自動実行されます。

initialize

initialize は、コードの特定の状態に依存しないツールやランタイム (言語ランタイム、システムパッケージ、グローバル CLI など) をインストールする際に利用します。

シンプルな形式

単純なシェルコマンドには、ブロックスカラーを利用します:

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  apt-get update && apt-get install -y build-essential
  npm install -g pnpm

構造化された形式

名前付きステップ、環境変数、または GitHub Actions には、リスト形式を利用します:

initialize:
  - name: "Install Python 3.12"
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

  - name: "Install system packages"
    run: |
      apt-get update
      apt-get install -y libpq-dev

  - name: "Install global tools"
    run: pip install uv
    env:
      PIP_BREAK_SYSTEM_PACKAGES: "1"

両方の形式は混在させて使用できます。シンプルな形式は、run を含む 1 つのステップと同等です。

initialize と maintenance の使い分け

`initialize` に入れるもの	`maintenance` に入れるもの
言語ランタイムのインストール	`npm install` / `pip install`
システムパッケージ (`apt-get`)	`bundle install`
グローバル CLI ツール	`go mod download`
1回限りの設定	依存関係キャッシュの更新
GitHub Actions (`setup-python` など)	リポジトリ固有のセットアップスクリプト

どちらのセクションもビルドのたびに実行されますが、分けておくことで設定が読みやすくなります。ツールやランタイムは initialize に、コードのロックファイルに追従する依存関係コマンドは maintenance に入れます。

maintenance

maintenance は、コードのクローン後に実行する依存関係のインストールやその他のコマンドに利用します。これらのコマンドはビルド中に実行され、セッション開始時にエージェントにも共有されるため、依存関係が変更された場合はエージェントが再実行できます。npm install、pip install、uv sync などのコマンドはここに含めます。

maintenance: |
  npm install
  pip install -r requirements.txt

あるいは、構造化された形式では次のとおりです:

maintenance:
  - name: "Install npm dependencies"
    run: npm install

  - name: "Install Python dependencies"
    run: uv sync
    env:
      UV_CACHE_DIR: /tmp/uv-cache

リポジトリレベルのブループリントでは、maintenance コマンドはリポジトリのルートディレクトリで実行されます。org レベルのブループリントでは、ホームディレクトリ (~) で実行されます。

knowledge

knowledge セクションは実行されません。これは、Devin がプロジェクトで作業する際に参照する情報です。ここでは、lint、テスト、ビルド、その他のプロジェクト固有のワークフローで使用する正しいコマンドを Devin に伝えます。

knowledge:
  - name: lint
    contents: |
      Run linting with:
      npm run lint

      For auto-fix:
      npm run lint -- --fix

  - name: test
    contents: |
      Run the full test suite:
      npm test

      Run a single test file:
      npm test -- path/to/test.ts

  - name: build
    contents: |
      npm run build

      Build output goes to dist/

各 Knowledge アイテムには、以下のフィールドがあります。

Field	Type	Description
`name`	string	この Knowledge アイテムの識別子 (例: `lint`、`test`、`build`)
`contents`	string	コマンド、指示、またはメモを自由形式のテキストで記述

name フィールドはラベルです。慣例として、lint、test、build が標準的な名前です。Devin は自身の作業を検証する際に、これらを参照します。任意のカスタム名で、追加の Knowledge アイテムを作成できます。

knowledge:
  - name: lint
    contents: ...
  - name: test
    contents: ...
  - name: build
    contents: ...
  - name: deploy
    contents: |
      Deploy to staging:
      npm run deploy:staging
  - name: database
    contents: |
      Run migrations:
      npm run db:migrate

      Seed test data:
      npm run db:seed

ステップの種類

initialize または maintenance の各ステップでは、シェルコマンド (run) または GitHub Actions (uses) の 2 種類のいずれかを利用します。

シェルコマンド (`run`)

bash で任意のシェルコマンドを実行します。

- name: "Install dependencies"
  run: |
    npm install
    pip install -r requirements.txt

フィールド	型	説明
`name`	string (optional)	ステップ用の、人が読んでわかるラベル
`run`	string	実行するシェルコマンド
`env`	map (optional)	このステップ用の追加の環境変数

実行の詳細:

コマンドは bash で実行されます。複数行スクリプト内のいずれかのコマンドが失敗すると、そのステップ全体が直ちに停止します。
org レベルのブループリントはホームディレクトリ (~) で実行されます。
リポジトリレベルのブループリントは、クローンされたリポジトリのルートディレクトリで実行されます。
各ステップのタイムアウトは 1 時間です。
シークレットは自動的に環境変数として利用できます。

GitHub Actions (`uses`)

Node.js ベースの GitHub Actions をブループリント内で直接実行できます:

- name: "Install Python"
  uses: github.com/actions/setup-python@v5
  with:
    python-version: "3.12"

Field	Type	説明
`name`	string (optional)	ステップの表示名
`uses`	string	GitHub Action の参照先
`with`	map (optional)	アクションの入力パラメータ
`env`	map (optional)	このステップ用の追加の環境変数

Action 参照形式:

github.com/<owner>/<repo>@<ref>
github.com/<owner>/<repo>/<subpath>@<ref>

github.com/ プレフィックスと @<ref> サフィックスは、どちらも必須です。ref は通常、v5 のようなバージョンタグです。 よく利用されるアクション:

Action	目的	例 `with`
`github.com/actions/setup-python@v5`	Python をインストール	`python-version: "3.12"`
`github.com/actions/setup-node@v4`	Node.js をインストール	`node-version: "20"`
`github.com/actions/setup-go@v5`	Go をインストール	`go-version: "1.22"`
`github.com/actions/setup-java@v4`	Java/JDK をインストール	`java-version: "21"`, `distribution: "temurin"`
`github.com/gradle/actions/setup-gradle@v4`	Gradle をインストール	(なし)
`github.com/ruby/setup-ruby@v1`	Ruby をインストール	`ruby-version: "3.3"`

サポートされているのは Node.js ベース の GitHub Actions のみです。Composite アクションと Docker ベースのアクションはサポートされていません。

with の値の仕組み: with で渡した値は、GitHub Actions のワークフローと同じ規則に従って、アクションへの入力として与えられます。すべての値は文字列に変換されます。

with:
  python-version: "3.12"
  check-latest: true
  cache: "pip"

アクションによる変更の伝播方法： アクションは、後続のステップで使用される環境を変更できます。たとえば、setup-python は Python の実行ファイルを PATH に追加するため、それ以降のすべてのステップと maintenance で引き続き利用できます。

run と uses: どちらを使うべきか

`run` を使うのはこんな場合…	`uses` を使うのはこんな場合…
システムパッケージをインストールする場合 (`apt-get`)	言語ランタイム (Python、Node、Go、Java、Ruby) をセットアップする場合
プロジェクト固有のスクリプトを実行する場合	必要な処理に対応する公式の GitHub Action がある場合
ファイルや環境を設定する場合	バージョン管理やキャッシュを自動で処理したい場合
コマンドがシンプルで自己完結している場合	GitHub Actions のワークフローでも同じ Action を使う場合

実際には、ほとんどの設定で、言語ランタイムには uses を使い、それ以外には run を使います。

環境変数とシークレット

ステップごとの環境変数

どのステップでも、env フィールドを使って追加の環境変数を定義できます。

- run: pip install -r requirements.txt
  env:
    PIP_INDEX_URL: "https://pypi.example.com/simple/"
    PIP_BREAK_SYSTEM_PACKAGES: "1"

これらはそのステップ内でのみ有効で、後続のステップには引き継がれません。

ステップ間の環境変数 (`$ENVRC`)

ステップ間で環境変数を引き継ぐには、$ENVRC ファイルに書き込みます。

- name: "Set shared variables"
  run: |
    echo "DATABASE_URL=postgresql://localhost:5432/myapp" >> $ENVRC
    echo "APP_ENV=development" >> $ENVRC

$ENVRC に書き込まれた変数は自動的にエクスポートされ、後続のすべてのステップおよび Devin セッションで利用できます。これは、GitHub Actions の $GITHUB_ENV と同様の仕組みです。

シークレット

Devin UI (各ブループリントエディタの Secrets タブから) で設定したシークレットは、自動的に環境変数として注入されます。ブループリントで宣言する必要はありません。名前で参照するだけです (例: $MY_SECRET) 。シークレットは、ビルド中に各ステップが実行される前に毎回注入され、さらに 各セッションの開始時にも再度注入されます。シークレット自体はスナップショットイメージから除去されるため、認証情報が保存済みのマシンイメージに埋め込まれることはありません。

組織のシークレット: 組織内のすべてのブループリントにあるすべてのステップで、環境変数として利用できます。これらは組織全体のブループリントエディタの Secrets タブで設定します。
Enterprise のシークレット: 組織のシークレットとマージされます (同名のシークレットが競合した場合は、組織のシークレットが優先されます) 。Enterprise 内のすべての組織で利用できます。
リポジトリのシークレット: リポジトリごとのファイル /run/repo_secrets/{owner/repo}/.env.secrets に書き込まれます。ビルド中は、そのリポジトリのブループリントのステップが実行される前に、リポジトリのシークレットが自動的に source されます。セッション時には、Devin がそのリポジトリで作業するときにそれらを source します。これらは、リポジトリのブループリントエディタの Secrets タブで設定します。

ビルド専用のシークレット: 「build only」としてマークされたシークレットは、スナップショットのビルド中は利用できますが、スナップショットが保存される前に削除されます。これは、ビルド時にのみ必要な認証情報 (例: initialize 中に非公開アーティファクトをダウンロードする場合) に利用してください。

maintenance はビルド中に実行されます。セッション開始時には、maintenance コマンドがエージェントに提示され (自動実行はされません) 、必要に応じてエージェントが再実行することがあります。maintenance ステップが設定ファイル (例: ~/.m2/settings.xml, ~/.npmrc) にシークレットを書き込むと、それらのファイルはスナップショットに組み込まれます。認証情報を書き込むステップは、定期的なビルド中に更新されるよう initialize ではなく maintenance に配置してください。ただし、書き込まれたファイルはイメージ内に保持される点に注意してください。最大限の安全性を確保するには、認証情報をディスクに書き込む代わりに、環境変数または $ENVRC を利用してください。

ファイルの添付

ブループリントエディタから、ファイル (.npmrc、settings.xml、設定ファイルなど) をアップロードできます。アップロードされたファイルは ~/.files/ に書き込まれ、各ファイルのパスを指す環境変数が設定されます。

$FILE_SETTINGS_XML    -> /home/ubuntu/.files/settings.xml
$FILE_NPMRC           -> /home/ubuntu/.files/.npmrc

変数名はファイル名に由来し、英数字以外の文字はアンダースコアに置き換えられ、先頭に FILE_ が付きます。ブループリントのステップでファイルを添付する:

maintenance:
  - name: "Configure Maven"
    run: |
      mkdir -p ~/.m2
      cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml

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

Gitベースのブループリントは現在サポートされていません。この機能は近日中に利用可能になる予定です。ブループリントをリポジトリに保存し、変更されると自動的にビルドがトリガーされるようになります。現時点では、UI の 設定 > 環境 > ブループリント からブループリントを設定してください。

完全な例

ブループリントが階層 (enterprise → org → repo) をまたいでどのように組み合わされるか、ビルドステータス、リポジトリの状態、再ビルドのトリガーになる条件については、宣言的構成ページのビルドとセッションを参照してください。

組織全体のブループリント

組織内のすべてのリポジトリで必要となる共有ツールです。これは最初に (Enterprise ブループリントがある場合はその後に) 、ホームディレクトリで実行されます。

initialize:
  - name: "Install Node.js 20"
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: "Install Python 3.12 and uv"
    run: |
      curl -LsSf https://astral.sh/uv/install.sh | sh

  - name: "Install shared tools"
    run: |
      npm install -g pnpm turbo
      apt-get update && apt-get install -y jq ripgrep

  - name: "Configure private registry"
    run: |
      echo "//npm.corp.example.com/:_authToken=$NPM_REGISTRY_TOKEN" >> ~/.npmrc

リポジトリレベルのブループリント

Node.js + Python のモノレポ向けの、プロジェクト固有のセットアップです。これは組織全体向けのブループリントの後に、リポジトリディレクトリ内で実行されます。

initialize:
  - name: "Install Playwright browsers"
    run: npx playwright install --with-deps chromium

  - name: "Set up project environment variables"
    run: |
      echo "DATABASE_URL=postgresql://localhost:5432/myapp_dev" >> $ENVRC
      echo "REDIS_URL=redis://localhost:6379" >> $ENVRC
      echo "APP_ENV=development" >> $ENVRC

maintenance:
  - name: "Install frontend dependencies"
    run: |
      cd frontend
      pnpm install

  - name: "Install backend dependencies"
    run: |
      cd backend
      uv sync

  - name: "Run database migrations"
    run: |
      cd backend
      uv run alembic upgrade head
    env:
      DATABASE_URL: "postgresql://localhost:5432/myapp_dev"

knowledge:
  - name: lint
    contents: |
      Frontend:
      cd frontend && pnpm lint

      Backend:
      cd backend && uv run ruff check .

      Auto-fix:
      cd frontend && pnpm lint --fix
      cd backend && uv run ruff check --fix .

  - name: test
    contents: |
      Frontend unit tests:
      cd frontend && pnpm test

      Backend unit tests:
      cd backend && uv run pytest

      E2E tests (requires dev server running):
      cd frontend && pnpm test:e2e

  - name: build
    contents: |
      Frontend:
      cd frontend && pnpm build

      Backend:
      cd backend && uv run python -m build

  - name: dev-server
    contents: |
      Start the full development stack:
      cd backend && uv run uvicorn main:app --reload &
      cd frontend && pnpm dev

      Frontend: http://localhost:3000
      Backend API: http://localhost:8000
      API docs: http://localhost:8000/docs

  - name: database
    contents: |
      Run migrations:
      cd backend && uv run alembic upgrade head

      Create a new migration:
      cd backend && uv run alembic revision --autogenerate -m "description"

      Reset the database:
      cd backend && uv run alembic downgrade base && uv run alembic upgrade head

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

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

概要

initialize

シンプルな形式

構造化された形式

initialize と maintenance の使い分け

maintenance

knowledge

ステップの種類

シェルコマンド (`run`)

GitHub Actions (`uses`)

run と uses: どちらを使うべきか

環境変数とシークレット

ステップごとの環境変数

ステップ間の環境変数 (`$ENVRC`)

シークレット

ファイルの添付

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

完全な例

組織全体のブループリント

リポジトリレベルのブループリント

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Documentation Index

​概要

​initialize

​シンプルな形式

​構造化された形式

​initialize と maintenance の使い分け

​maintenance

​knowledge

​ステップの種類

​シェルコマンド (run)

​GitHub Actions (uses)

​run と uses: どちらを使うべきか

​環境変数とシークレット

​ステップごとの環境変数

​ステップ間の環境変数 ($ENVRC)

​シークレット

​ファイルの添付

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

​完全な例

​組織全体のブループリント

​リポジトリレベルのブループリント

概要

initialize

シンプルな形式

構造化された形式

initialize と maintenance の使い分け

maintenance

knowledge

ステップの種類

シェルコマンド (`run`)

GitHub Actions (`uses`)

run と uses: どちらを使うべきか

環境変数とシークレット

ステップごとの環境変数

ステップ間の環境変数 (`$ENVRC`)

シークレット

ファイルの添付

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

完全な例

組織全体のブループリント

リポジトリレベルのブループリント