Deploy to Buildボタン

Deploy to Buildボタンを使うと、ダッシュボードで設定を行わなくても、誰でもワンクリックでアプリをBuild.ioにデプロイできます。オープンソースプロジェクトやスターターテンプレートのREADMEに設置すると、閲覧者は説明を読むだけでなく、実際にアプリを動かして試せます。

このボタンはHeroku Buttonの仕様に準拠しています。Herokuのボタンをすでに設置している場合は、Herokuボタンからの移行を参照してください。

事前に用意するもの

• GitHubリポジトリ。 デプロイされるのは、リポジトリのデフォルトブランチです。利用者には、GitHubを連携したBuild.ioアカウントが必要です。また、利用者のGitHubアカウントからリポジトリを読める必要があるため、オープンソースプロジェクトではリポジトリを公開してください。
• リポジトリのルートにあるapp.json。 buildpacks配列を含める必要があります。詳しくはapp.jsonの書き方を参照してください。
• Procfile。 アプリの起動方法を記述します。データベースのマイグレーションが必要な場合は、releaseプロセスも追加します。詳しくはマイグレーションの実行を参照してください。

READMEへのボタンの追加

Markdownの場合：

[![Deploy to Build](https://build.io/deploy-to-build-button.svg)](https://app.build.io/deploy?template=https://github.com/your-username/your-repo)

HTMLの場合：

<a href="https://app.build.io/deploy?template=https://github.com/your-username/your-repo">
  <img src="https://build.io/deploy-to-build-button.svg" alt="Deploy to Build">
</a>

your-username/your-repoは、自分のリポジトリに置き換えてください。ボタン画像のサイズは128×32ピクセルなので、widthの指定は不要です。

templateは常に指定してください。省略した場合、Build.ioはクリック元のGitHubのページからリポジトリを判別しようとしますが、この判別が機能するのは、利用者がすでにBuild.ioにサインインしている場合に限られます。

URLパラメータ

デプロイエンドポイント（https://app.build.io/deploy）では、次のクエリパラメータを指定できます。

パラメータ	説明	例
template	デプロイするGitHubリポジトリ。完全なURL、github.com/で始まるパス、owner/repoのいずれの形式でも指定できます。	template=https://github.com/myorg/myapp
app[name]	アプリ名の候補。名前の重複を避けるため、Build.ioは末尾に短いランダムな文字列を付加します。実際のアプリ名はmy-app-a1b2c3d4のようになります。省略するとリポジトリ名が使われます。	app[name]=my-app
app[region]	デプロイ先のリージョン。	app[region]=us-east-1
env[NAME]	新しいアプリに設定するConfig Var。変数ごとにパラメータを繰り返します。	env[GREETING]=Hello&env[LOG_LEVEL]=info
express	trueを指定すると、確認画面を表示せずに、利用者の個人チームへすぐにデプロイします。	express=true

複数のパラメータを組み合わせた例は次のとおりです：

https://app.build.io/deploy?template=https://github.com/myorg/myapp&app[name]=myapp&app[region]=us-east-1&env[NODE_ENV]=production

デプロイされるのは、常にデフォルトブランチです。別のブランチのページでボタンがクリックされた場合や、templateで別のブランチを指している場合も同じです。現時点では、特定のブランチやタグを指定する方法はありません。

URLに含めた値は、READMEを読む誰からも見えます。本物のシークレットはenv[...]に含めないでください。詳しくはConfig Varとシークレットを参照してください。

app.jsonの書き方

Build.ioは、デフォルトブランチのルートにあるapp.jsonをもとにアプリを設定します。このファイルは必須で、app.jsonがないリポジトリでは、app.jsonの追加を求めるメッセージが表示され、デプロイは失敗します。

PostgreSQLデータベースを使うRailsアプリの最小限のapp.jsonは、次のとおりです：

{
  "name": "My Application",
  "description": "A sample application",
  "repository": "https://github.com/myorg/myapp",
  "addons": [
    "schema-to-go:basic"
  ],
  "buildpacks": [
    { "url": "heroku/ruby" }
  ]
}

buildpacksは必須です。通常のデプロイと異なり、ボタンからのデプロイではビルドパックが自動検出されません。アプリに必要なビルドパックをすべて、それぞれurl付きで記述してください。詳しくはビルドパックを参照してください。

対応しているフィールド

スキーマはHerokuのapp.jsonに準拠していますが、次の点が異なります。

フィールド	ボタンからのデプロイでの扱い
buildpacks	必須。 各要素にurlが必要です。
addons	プロビジョニングされます。ただし、Build.ioのアドオン名とプランの明示が必要です。アドオンを参照してください。
formation	反映されます。sizeにはDynoサイズ（例：standard-1x）を指定します。
stack	反映されます。省略するとheroku-24になります。
name、description、keywords、website、repository、logo	アプリのメタデータとして保存されます。アプリ名にはnameではなく、app[name]またはリポジトリ名が使われます。
success_url	保存されますが、使われません。デプロイ後、利用者は新しいパイプラインの画面に移動します。
env	反映されません。 Config Varとシークレットを参照してください。
scripts	保存されますが、postdeployを含め実行されません。マイグレーションの実行を参照してください。
environments	ボタンでデプロイされるアプリには使われません。

上記以外のフィールドは無視されます。

アドオン

アドオンがプロビジョニングされるのは、サービスとプランの両方がBuild.ioのカタログに存在する場合だけです。heroku-postgresqlのようなHerokuのアドオン名はカタログにありません。schema-to-goのようにプランを省略した名前も同様です。どちらもエラーにならずに無視され、アドオンなしでデプロイが完了します。

必要なサービスに対応するBuild.ioのアドオンを、アドオンサービスに記載されたプランとあわせて指定してください。

サービス	Herokuのアドオン	Build.ioのアドオン	最小プラン
PostgreSQL	heroku-postgresql	schema-to-go	schema-to-go:basic
Redis	heroku-redis	cache-to-go	cache-to-go:mini
MySQL / MariaDB	jawsdb、cleardb	ave-to-go	ave-to-go:basic
Elasticsearch / OpenSearch	bonsai、searchbox	spandex-to-go	spandex-to-go:dachs
トランザクションメール	mailgun、sendgrid	mailertogo	mailertogo:micro

addonsの各要素は、"service:plan"形式の文字列か、planキーを持つオブジェクト（例：{ "plan": "schema-to-go:basic" }）で記述します。

プロビジョニングされたアドオンは、接続用のConfig Var（schema-to-goならDATABASE_URLなど）をアプリに設定します。最初にテストでデプロイした後、アプリのResourcesタブで、すべてのアドオンが作成されたことを確認してください。

Config Varとシークレット

app.jsonのenvブロックの値は、デプロイされたアプリに反映されません。ボタンからのデプロイでは、app.jsonをもとにアプリが作成された後、Config Varが置き換えられるためです。設定されるのは、URLのenv[...]で指定した値と、アドオンが設定する値だけです。また、requiredの値の入力を利用者に求める機能はなく、Herokuの"generator": "secret"にも対応していません。

そのため、次のように扱います。

• シークレットではないデフォルト値： 変数が未設定のときはアプリ側でデフォルト値を使うようにするか、ボタンのURLのenv[...]で指定します。

• シークレット： ボタンのURLには含めないでください。アプリが許容できる場合は起動時にフォールバック値を生成するか、デプロイ後に値を設定するようREADMEで利用者に案内します：

  bld config:set SECRET_KEY_BASE=$(openssl rand -hex 64) -a <app-name>

アプリが読み取る変数の説明として、app.jsonにenvブロックを残しておいてもかまいません。ただし、Build.ioがその値を反映することを前提にはしないでください。

マイグレーションの実行

Build.ioはscripts.postdeployを実行しません。マイグレーションは、代わりにリリースフェーズで実行します。Procfileにreleaseプロセスを追加してください：

release: bundle exec rails db:migrate
web: bundle exec puma -C config/puma.rb

リリースコマンドは、ビルドのたびに、新しいバージョンが公開される前に実行されます。実行時には、DATABASE_URLを含むアプリのConfig Varを使用できます。コマンドが失敗すると、デプロイは中止されます。

Herokuのpostdeployは1回しか実行されませんが、リリースフェーズはデプロイのたびに実行されます。データの投入（シード）など、postdeployから移す処理は、繰り返し実行しても問題がないようにしてください。

Herokuボタンからの移行

1. ボタンのURLを書き換える。 https://heroku.com/deployをhttps://app.build.io/deployに、ボタン画像をhttps://build.io/deploy-to-build-button.svgに置き換えます。template、app[...]、env[...]、expressの各パラメータは、そのまま使用できます。
2. app.jsonにbuildpacksを追加する。 すでにある場合は不要です。
3. アドオン名を書き換える。 Build.ioのアドオン名に、プランを付けて指定します。アドオンを参照してください。
4. generator: "secret"とrequiredのConfig Varを置き換える。 Build.ioはどちらにも対応していません。Config Varとシークレットを参照してください。
5. scripts.postdeployの処理を移す。 Procfileのreleaseプロセスに移します。マイグレーションの実行を参照してください。
6. ボタンをテストする。 READMEからボタンを押してデプロイし、アプリのアドオンとConfig Varを確認します。

変更前：

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/myorg/myapp)

変更後：

[![Deploy to Build](https://build.io/deploy-to-build-button.svg)](https://app.build.io/deploy?template=https://github.com/myorg/myapp)

ボタンをクリックしたときの流れ

1. 利用者は、GitHubを連携した状態でBuild.ioにサインインしている必要があります。GitHubが未連携の場合は、ダッシュボードに移動し、先に連携するよう求められます。
2. express=trueを指定していない場合は、確認画面が表示されます。利用者はアプリ名、チーム、リージョンを変更できます。env[...]で指定したConfig Varも一覧で表示されます。
3. Build.ioは、新しいパイプラインとアプリを作成します。アプリ名は、app[name]の値にランダムな文字列を付加したものです。app.jsonは、デフォルトブランチの最新コミットから読み込まれます。
4. Build.ioはアドオンをプロビジョニングし、アプリをビルドしてリリースフェーズを実行した後、アプリを起動します。
5. 利用者は新しいパイプラインの画面に移動し、そこでビルドの進行を確認したり、アプリを開いたりできます。