[Deploy to Heroku] (Heroku にデプロイ) ボタンを作成する

最終更新日 2022年03月09日(水)

「Deploy to Heroku」 (Heroku にデプロイ) ボタンを使用すると、Web ブラウザから離れずに、ほとんど設定なしで、アプリを Heroku にデプロイできます。このボタンは、Heroku アプリのデプロイと設定をすばやく簡単に行う方法を自社の顧客に提供することを希望するお客様、オープンソースプロジェクトのメンテナンスを行う方、アドオンプロバイダーに最適です。

このボタンは README ファイルでの使用に適しており、一般的にアプリの設定に必要な手作業のリストの代わりとしての機能を果たすことを目的としています。

サンプル Node.js アプリを Heroku にデプロイするボタンの例は次のとおりです。

デプロイ

このドキュメントでは、「Deploy to Heroku」 (Heroku にデプロイ) サービスを使用するアプリの要件と、これらのボタンを使用して、自分が管理するソースコードを簡単に Heroku にデプロイできるようにする方法について説明します。

要件

ボタンを作成するための基本要件は、アプリのルートディレクトリに有効な app.json​ ファイルがあることと、アプリのソースコードが GitHub リポジトリでホストされていることです。

Heroku Button は、Git のサブモジュールが存在するリポジトリでは動作しません。Heroku Button は Build API に依存しており、GitHub から取得された tarball を使用します。repo-content の tarball が生成される場合は、GitHub にサブモジュールのコンテンツはありません。

Button の利用規約

独自の利用規約を GitHub リポジトリに提供しない限り、ボタンの利用規約は Heroku 利用規約 (デフォルト)​ によって管理されます。一般的な習慣として、README ファイルに利用規約へのリンクを示すか、利用規約をライセンスファイルとして GitHub リポジトリに追加します。

app.json ファイルを作成する

app.json​ は、Web アプリを記述するためのマニフェスト形式です。このファイルで、環境変数、アドオン、および Heroku でアプリを実行するために必要なその他の情報を宣言します。

プロジェクトに app.json​ ファイルを作成するために必要な特別なツールはありません。app.json のスキーマ​ に必須フィールドはありませんが、name​、description​、logo​ などのフィールドはユーザーに役立つコンテンツを提供したり、アプリに個別の ID を指定したりするため、指定することをお勧めします。

サンプル app.json​ ファイルは次のとおりです。

{
  "name": "Node.js Sample",
  "description": "A barebones Node.js app using Express",
  "repository": "https://github.com/heroku/node-js-getting-started",
  "logo": "https://node-js-sample.herokuapp.com/node.png",
  "keywords": ["node", "express", "static"]
}

アプリに Heroku アドオン、カスタム環境変数、またはデプロイ後のスクリプトが必要な場合は、それらも指定できます。詳細については、app.json のスキーマのドキュメント​を参照してください。

app.json ファイルをテストする

アプリの app.json​ ファイルを作成してアプリのリポジトリに追加したら、いくつかの方法で、このファイルが有効であること、またアプリを正常にデプロイできることをテストできます。CLI を使用して検証とデプロイ​を行うことも、Web ブラウザを使用して Heroku の新しい Dashboard からデプロイすることもできます。

https://heroku.com/deploy?template=https://github.com/heroku/node-js-getting-started/tree/main

Heroku ボタンを追加する

app.json​ ファイルが有効で、想定どおりに動作することを検証したら、次に自分のリポジトリの README にボタンを追加します。

テンプレートのソースコードのリポジトリを参照するには 2 つの方法があります。

  • 暗黙的にテンプレートを解決する。GitHub でホストされているドキュメントの場合に便利です。template​ パラメータを指定しない場合は、referer​ ヘッダーを使用してボタンの場所からテンプレートが推測されます (referer ヘッダーは送信されないため、この方法は非公開の GitHub リポジトリでは機能しません)。この方法だと、リポジトリのフォークでもボタンが安定します。
  • リポジトリを示す template​ パラメータを明示的に使用する。GitHub リポジトリの外 (たとえばブログの投稿や非公開の GitHub リポジトリなど) にあるボタンの場合に便利です。

暗黙的なテンプレートを使用する

GitHub リポジトリの README ファイルにボタンを埋め込んでいる場合は、ボタンがクリックされたときに referer​ ヘッダーから自動的にリポジトリの URL が推測されます。

この方法は、ボタンに特定のリポジトリ URL がハードコードされないため、ボタンの href を変更しなくてもリポジトリのフォークやブランチが動作し、便利です。

次に例を示します。

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)

Markdown を使用しない場合、HTML と同等のコンテンツは次のとおりです。

<a href="https://heroku.com/deploy">
  <img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy">
</a>

button.svg​ も使用できます。

明示的なパラメータを追加する

次の Markdown スニペットをテンプレートとして使用して、template​ クエリパラメータをリポジトリの URL に変更します。

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/heroku/node-js-getting-started)

Markdown を使用しない場合、HTML と同等のコンテンツは次のとおりです。

<a href="https://heroku.com/deploy?template=https://github.com/heroku/node-js-getting-started">
  <img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy">
</a>

ボタンをパラメータ化する

app.json​ ファイル内の環境変数のデフォルト値をオーバーライドしたり指定したりするために使用されるボタン URL で、url パラメータを指定できます。env[SLACK_SUBDOMAIN]=testdomain​ という形式の url パラメータをボタン URL に追加できます。

たとえば、次のようなボタン URL があるとします。

https://heroku.com/deploy?template=https://github.com/rauchg/slackin/tree/0.5.1&env[SLACK_SUBDOMAIN]=testdomain

上記の例では、Heroku の app-set インターフェースで SLACK_SUBDOMAIN​ 環境変数に testdomain​ があらかじめ入力されます。

次のような使用例があります。

  1. ボタンのパラメータ化。たとえば、同じ app.json ファイルを使用する同じソースリポジトリで、それぞれ少しずつ異なる方法でアプリを設定する複数のボタンをホストすることができます。
  2. ボタンのパーソナライズ。たとえば、ユーザーがあなたのドキュメントにログインして閲覧している場合、ボタンの url で OAuth キーまたは auth を渡すと、ユーザーはそれらを探して Heroku で入力しなくて済みます。

ボタンのイメージ

Heroku Button の設定フローにリンクするときに、raw リンクまたはイメージリンクのいずれかを使用できます。イメージを使用する場合は、次の URL で PNG と SVG の両方のバージョンが用意されます。

  • https://www.herokucdn.com/deploy/button.png
  • https://www.herokucdn.com/deploy/button.svg

カスタム Git ブランチを使用する

特定の Git ブランチからボタンをデプロイする場合は、GitHub の完全修飾 URL を template​ パラメータとして使用できます。

https://github.com/heroku/node-js-getting-started/tree/master

Heroku Button をデバッグする

Heroku Button をリポジトリに追加し、アプリのデプロイ時にそのボタンクリックが正常に動作しないことがわかった場合、次の手順に従って問題をデバッグします。

ソースコードを確実にビルドしてデプロイする

まず、ボタン化しようとしているソースコードを確実に Heroku でビルドしてデプロイします。上記の Node.js のサンプルを例として使用すると、以下のようになります。

  1. git clone https://github.com/heroku/node-js-getting-started.git​ で、新しいディレクトリにコードをクローンします。
  2. cd node-js-getting-started
  3. heroku create​ で Heroku アプリを作成します。
  4. app.json​ ファイルで指定されているアドオンを heroku addons:create​ でプロビジョニングします。
  5. app.json​ で指定されているアプリの環境設定を heroku config:set KEY=VALUE​ で追加します。
  6. git push heroku master​ で、コードを Git にプッシュします。
  7. 忘れずにアプリをビルドします。
  8. heroku run​ で postdeploy​ コマンド (存在する場合) を実行します。
  9. heroku open​ でアプリを開き、正しく実行されていることを確認します。

Heroku Button で使用されるビルドプロセスには Git のサブモジュールのサポートはありません (デフォルトの Heroku の git-push プロセスではサブモジュールは復元されません)。

アプリの設定を起動する

上記の手順が正常に動作する場合、次のデバッグ手順は、app-setups​ API エンドポイントを直接起動することです。これは、アプリの作成と設定を行うために Heroku Button UI から呼び出される API エンドポイントです。API を使用して app-setup を作成したら、状態を確認して、ビルドの出力を検証できます。詳細は、Setting Up Apps Using the Heroku Platform API​(Heroku Platform API を使用してアプリを設定する) を参照してください。

非公開の GitHub リポジトリ

Heroku Button は、公開または非公開のどちらの GitHub リポジトリでも動作します。非公開リポジトリで Heroku Button を使用する場合は、いくつかの制限があります。

  • GitHub では非公開リポジトリの referer​ ヘッダーは送信されないため、ボタンリンクで template​ URL パラメータを指定する必要があります​。つまり、非公開リポジトリのフォークやブランチには、通常、親リポジトリまたはデフォルトブランチを示すボタンが存在します。
  • 非公開 GitHub リポジトリでホストされているボタンからアプリを設定する場合は、現在の Heroku ユーザーが GitHub にリンクされていて、リポジトリへのアクセス権を持っている必要があります。GitHub アカウントにリンクされていない Heroku ユーザーが非公開リポジトリの button-deploy を実行しようとすると、GitHub で認証するよう求められます。
  • Heroku Buttons for Private Repos は、Heroku Elements Buttons Gallery​ に表示されず、非公開の GitHub コードリポジトリへのアクセス権を持っていないユーザーが利用することはできません。

参考情報

app.json​ についての詳細と Heroku プラットフォームと統合する方法については、次のドキュメントを参照してください。