GitLab Advent Calendar 2025

GitLabからHerokuにデプロイする方法

Posted at 2025-12-22

こんにちは。ものすごく久しぶりにQiitaの投稿を書きました。
最近はAIを使って記事を書けるので便利ですね。

1. GitLab CI/CDから直接Herokuにデプロイする（コンテナデプロイ）の詳細

このパターンは、GitLab CI/CDランナー上でDockerイメージをビルドし、Herokuが提供するコンテナレジストリを経由してHerokuアプリケーションを更新する、最も高度に自動化された方法です。

ステップ	手順（GitLab CI/CDジョブ内）	内部で起きていること
1. 認証とログイン	`docker login -u _ --password-stdin registry.heroku.com`	GitLab変数に登録された`HEROKU_API_KEY`をパスワードとして使用し、CI/CDランナーがHeroku Container Registryへのアクセス権を取得します。
2. イメージのビルド	`docker build -t ... .`	プロジェクトルートの`Dockerfile`に基づき、アプリケーションと依存関係を含む自己完結型のDockerイメージが作成されます。このイメージには、Herokuが期待するタグ（例：`registry.heroku.com/app-name/web`）が付与されます。
3. イメージのプッシュ	`docker push ...`	ビルドされたDockerイメージが、認証済みのHeroku Container Registryにアップロードされます。これは、アプリケーションの新しいバージョンがHerokuのインフラに格納された状態です。
4. リリース	`heroku container:release web --app $HEROKU_APP_NAME`	Heroku CLIがHeroku APIに対し、「プッシュされた最新の`web`イメージを、ターゲットアプリ（`$HEROKU_APP_NAME`）の新しいバージョンとしてデプロイせよ」という指示を送ります。Herokuは既存のDynoを新しいイメージに切り替え（ローリングデプロイ）、トラフィックを新しいバージョンに向けます。

Dockerfile: HerokuはProcfileではなく、DockerfileのCMDやENTRYPOINTの指示に従ってプロセス（Dyno）を起動します。
ゼロダウンタイム: Herokuのリリースプロセスは、通常、新しいDynoが起動して正常性を確認してからトラフィックを切り替えるため、ゼロダウンタイムデプロイが実現されます。

この方法は、Herokuのネイティブな「GitHubデプロイ」機能を利用するために、GitLabをGitHubのミラーリング元として利用します。

ステップ	手順	内部で起きていること
1. GitLabへのプッシュ	開発者が`git push`をGitLabに実行	コードがGitLabのリモートリポジトリに格納されます。
2. リポジトリのミラーリング	GitLabが設定に基づき自動実行	GitLabは、新しいコミットを検知し、設定されたGitHubリポジトリに対し、`git push`処理を実行します。GitHubのリポジトリがGitLabと同じ状態に保たれます。
3. Herokuによる検知	GitHub WebhookがHerokuに通知	GitHubに設定されているWebhook（Herokuとの連携時に自動設定される）が、新しいコミットがプッシュされたことをHerokuに通知します。
4. Herokuのビルド開始	Herokuが自動実行	HerokuはGitHubから最新のコードを取得し、Slug Compiler（ビルドシステム）を起動します。アプリケーションの言語に基づき、Buildpackが実行され、依存関係のインストールやアセットのコンパイルが行われ、実行可能なSlug（アプリケーションのバイナリパッケージ）が作成されます。
5. リリースとデプロイ	Herokuが自動実行	作成されたSlugがHerokuのDyno（実行環境）に展開され、アプリが再起動されます。

Buildpack: Herokuがコードを自動で認識し、最適なBuildpack（例：Ruby Buildpack、Node.js Buildpack）を選択・適用してビルドを行います。
ミラーリングの遅延: GitLabからGitHubへのミラーリングに数秒〜数十秒の遅延が発生する可能性があるため、デプロイ完了までの時間はパターン1より長くなる場合があります。

これは、HerokuのGitリモート機能を利用する最も伝統的な手動デプロイ方法です。

ステップ	手順（ローカルPCでの実行）	内部で起きていること
1. リモートの追加	`heroku create my-app`	Heroku上に新しいアプリが作成され、ローカルの`.git/config`ファイルに`heroku`という名前のGitリモートが追加されます。
2. デプロイの実行	`git push heroku main`	ローカルの`main`ブランチの全ファイルが、SSHプロトコル経由でHerokuサーバーのGitリポジトリに送信されます。
3. Herokuのビルド開始	Herokuが自動実行	Herokuサーバーはプッシュを受信すると、パターン2と同様にSlug Compilerを起動し、Buildpackを使用してコードをコンパイルし、実行可能なSlugを作成します。
4. リリースとデプロイ	Herokuが自動実行	作成されたSlugがDynoにロードされ、アプリケーションが再起動されます。

Gitの裏ワザ: Herokuは、デプロイ時に受け取ったGitコミットを単なるコードの転送手段として利用し、その場でビルドを開始します。これは通常のGit操作（ピアリポジトリへのプッシュ）とは異なり、サーバー側でデプロイ処理をトリガーする特殊な挙動です。
手動トリガー: 開発者が手動でgit pushコマンドを実行する必要があるため、自動化はされません。