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

この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。

最終更新日 2019年10月09日(水)

要件
app.json ファイルを作成する
app.json ファイルをテストする
Heroku ボタンを追加する
カスタム Git ブランチを使用する
Heroku Button をデバッグする
非公開の GitHub リポジトリ
参考情報

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

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

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

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

要件

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

Heroku Button は、Git のサブモジュールが存在するリポジトリでは動作しません。Heroku Button は Build API に依存しており、GitHub から取得された tarball を使用します。repo-content の tarball が生成される場合は、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 Add-ons、カスタム環境変数、または postdeploy スクリプトが必要な場合は、それらも指定できます。詳細については、app.json のスキーマのドキュメントを参照してください。

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

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

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

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)

Here’s the equivalent content as HTML if you’d prefer not to use Markdown:

<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)

Here’s the equivalent content as HTML if you’d prefer not to use Markdown:

<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 があらかじめ入力されます。

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

ボタンのパラメータ化。たとえば、同じ app.json ファイルを使用する同じソースリポジトリで、それぞれ少しずつ異なる方法でアプリを設定する複数のボタンをホストすることができます。
ボタンのパーソナライズ。たとえば、ユーザーがあなたのドキュメントにログインして閲覧している場合、ボタンの 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 のサンプルを例として使用すると、以下のようになります。

git clone https://github.com/heroku/node-js-getting-started.git で、新しいディレクトリにコードをクローンします。
cd node-js-getting-started
heroku create で Heroku アプリを作成します。
app.json ファイルで指定されているアドオンを heroku addons:create でプロビジョニングします。
app.json で指定されているアプリの環境設定を heroku config:set KEY=VALUE で追加します。
git push heroku master で、コードを Git にプッシュします。
忘れずにアプリをビルドします。
heroku run で postdeploy コマンド (存在する場合) を実行します。
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 プラットフォームと統合する方法については、次のドキュメントを参照してください。

Introducing the app.json Application Manifest (app.json アプリケーションマニフェストの導入)
Heroku Platform API Reference: App Setups (Heroku Platform API リファレンス: アプリの設定)
app.json Schema (app.json のスキーマ)

Categories