Contents
GitHub ActionsとDockerによる自動デプロイの概要
GitHub ActionsとDockerを組み合わせた自動デプロイは、Web開発やDevOpsエンジニアにとって非常に効率的な手法です。手動での環境構築やリリース作業に時間がかかる中、このワークフローによりバグのリスク削減やリリース遅延の防止が可能になります。本記事では、具体的なコード例とステップバイステップの手順を踏まえ、即座に実装できる知識をお届けします。
GitHub Actionsのワークフロー設定ファイル作成手順
GitHub Actionsで自動デプロイを構築するには、適切なYAMLファイルを作成することが不可欠です。以下に基本的な構造と定義方法を解説します。ワークフロー設定ファイルは、リポジトリの.github/workflows/ディレクトリ内に配置し、YAML形式で記述します。
ワークフローファイルの基本構造
ワークフロー設定ファイル（通常/.github/workflows/deploy.yml）は、以下のセクションで構成されます。各セクションの役割と使い方を以下にまとめます。
| セクション | 説明 |
|---|---|
name |
ワークフローの表示名（作業内容を簡潔に表記） |
on |
トリガーとなるイベント（例: push, pull_request） |
jobs |
実行するジョブの定義（複数のステップが含まれる） |
|
1 2 3 4 5 6 7 8 9 |
name: Deploy with Docker on: [push] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v3 |
注意点:
runs-onにはGitHub Actionsが提供する仮想マシンの種類を指定します。ubuntu-latestは最新バージョンのUbuntuを使用します。
ジョブとステップの定義方法
ジョブ内では、複数の「ステップ」を順番に実行します。各ステップはGitHub Actionsが提供するアクション（usesで指定）またはカスタムスクリプト（runで指定）で構成されます。
|
1 2 3 4 5 6 7 8 |
steps: - name: Build Docker image uses: docker/build-push-action@v5 with: context: . push: true tags: ghcr.io/your-username/your-app:latest |
ステップの順序: ビルド、プッシュ、デプロイを含め、必要に応じて検証や設定手順を追加してください。
Dockerイメージのビルドタスク設定
Dockerイメージをビルドする際は、docker/build-push-actionを使用します。このアクションでは、context（コンテキストディレクトリ）やtags（プッシュ先タグ）を指定できます。以下に主なパラメータと説明を示します。
| パラメータ | 説明 |
|---|---|
context |
Dockerfileのあるディレクトリ（.は現在の場所を指定） |
tags |
イメージがプッシュされるリポジトリとタグ（例: ghcr.io/your-username/app:latest） |
注意事項:
- 実際に本番環境に公開するイメージには、適切なセキュリティ設定が必須です。
- タグ名は一意で管理しやすくすることが重要です。
Dockerfileの作成と構文解説
Dockerfileは、アプリケーションをコンテナ化するために必要な手順を記述したファイルです。初心者向けに各ディレクティブの役割を明確に解説します。
Dockerfileの基本構文と例
|
1 2 3 4 5 6 |
FROM python:3.9-slim WORKDIR /app COPY . . RUN pip install -r requirements.txt CMD ["python", "app.py"] |
| ディレクティブ | 説明 |
|---|---|
FROM |
使用するベースイメージを指定（例: python:3.9-slim） |
WORKDIR |
コンテナ内で作業を行うディレクトリを設定（/appなど） |
COPY |
ローカルのファイルやフォルダをコンテナ内にコピー |
RUN |
コンテナで実行するコマンド（例: パッケージインストール） |
CMD |
コンテナ起動時に実行されるデフォルトコマンド |
初心者向けアドバイス:
FROMでは、アプリケーションに必要な最低限のベースイメージを選びましょう。- マルチステージビルドが必要な場合もあります（例: 開発環境と本番環境の分離）。
GitHub Packagesへのプッシュ設定
DockerイメージをGitHub Container Registry（ghcr.io）へプッシュするには、Personal Access Token（PAT）を使用します。以下に手順と注意点をまとめます。
認証設定の手順
- GitHubからPersonal Access Token (PAT) を作成し、リポジトリのSecretsに保存します。
- ワークフローで
GITHUB_TOKENやGHCR_ACCESS_TOKENなどの環境変数を参照します。
|
1 2 3 4 |
env: REGISTRY_USER: ${{ secrets.GHCR_USERNAME }} REGISTRY_TOKEN: ${{ secrets.GHCR_ACCESS_TOKEN }} |
注意: Secretはローカルに保存せず、GitHubのSettings > Secrets and variablesから管理してください。
マルチプラットフォーム対応（AMD64/ARM64）構成
Dockerイメージを複数アーキテクチャ向けにビルドするには、buildxが必須です。以下に構築手順と実践的な使い方を解説します。
Buildxのインストール確認
GitHub Actionsでは、docker/setup-buildx-actionを使用してBuildxを自動で設定できます。以下のようにワークフローに追加します。
|
1 2 3 4 5 6 7 |
jobs: build-multiarch: runs-on: ubuntu-latest steps: - name: Set up Buildx uses: docker/setup-buildx-action@v2.6.0 |
Platformsパラメータの指定方法
platformsパラメータで対象アーキテクチャを指定します。以下はAMD64とARM64を同時にビルドする例です。
|
1 2 3 4 5 6 7 8 |
- name: Build and push multi-arch image uses: docker/build-push-action@v5 with: context: . platforms: ["linux/amd64", "linux/arm64"] push: true tags: ghcr.io/your-username/your-app:latest |
Buildxのテスト:
ローカル環境で動作確認するには、docker run --platform linux/arm64 -it your-image-name:latestを使用します。
VPS環境でのDocker Composeによるデプロイ方法
ghcr.ioからプッシュされたイメージをVPSで実行するために、docker-compose-actionを使用します。以下に手順とセキュリティ設定のポイントを解説します。
SSH接続のための秘密管理
VPSにSSH接続する際は、ssh-actionを使用して秘密鍵をGitHub Secretsに保存します。
|
1 2 3 4 5 6 7 8 9 10 11 |
jobs: deploy-to-vps: runs-on: ubuntu-latest steps: - name: SSH into VPS uses: appleboy/ssh-action@v1.0.3 with: host: your-vps-ip username: deploy-user key: ${{ secrets.SSH_PRIVATE_KEY }} |
セキュリティ注意:
- 秘密鍵はローカル環境に保存せず、GitHub Secretsから取得するようにしましょう。
- デプロイユーザーの権限を最小限に保つことが重要です。
Docker Composeファイルのバージョン管理
VPSでのデプロイに使用するdocker-compose.ymlは、リポジトリ内に配置し、バージョンを厳密に管理します。以下の例をご覧ください。
|
1 2 3 4 5 6 7 |
version: '3' services: webapp: image: ghcr.io/your-username/your-app:latest ports: - "80:80" |
環境変数管理とセキュリティ設定
GitHub Actionsでは、機密情報をGitHub Secretsとして保存し、ワークフロー内で安全に参照します。以下に具体的な実施手順とベストプラクティスを示します。
GitHub Secretsの有効活用
重要な情報（APIキー・パスワード）は以下の手順でSecretsに登録してください。
- GitHubリポジトリ → Settings → Secrets and variables → Actions
- プライベートな環境変数を追加（例:
GHCR_ACCESS_TOKEN）
ベストプラクティス:
- トークンは定期的に更新し、過剰な権限を与えないようにしましょう。
- セキュリティ強化のために
--read-onlyなどのオプションを活用してください。
よくあるエラーの対処法
以下は、実務で頻出する問題とその解決方法です。
Dockerイメージプッシュ時の認証失敗
原因: PATの有効期限切れ、またはリポジトリへのアクセス権がない。
解決策:
- GitHubから新しいPATを生成し、Secretsに再登録
tagsの指定が正しいか確認（例:ghcr.io/your-username/app:latest）
VPS接続タイムアウト
原因: SSHポートがブロックされている、またはIPアドレスが変更された。
解決策:
- VPSプロバイダーの設定でSSHポートを確認
- 静的IPアドレスを使用しているか確認
まとめと自動デプロイワークフローのテンプレートコード
記事の要点を整理
- GitHub Actions + Dockerは、即時リリースと環境一貫性を実現する。
- ワークフロー設定ファイルを作成し、Dockerイメージをghcr.ioへプッシュ。
- VPS側では
docker-compose-actionを使用してデプロイを自動化。 - マルチプラットフォーム対応とセキュリティ設定は必須の手順。
GitHub Actions + Dockerワークフローのテンプレートコード
以下は、即座に導入可能なGitHub Actionsワークフローテンプレートです。/.github/workflows/deploy.ymlに保存してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
name: Deploy with Docker on: push: branches: [main] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v3 - name: Set up Buildx uses: docker/setup-buildx-action@v2.6.0 - name: Login to GitHub Container Registry uses: docker/login-action@v2.1.0 with: registry: ghcr.io username: ${{ secrets.GHCR_USERNAME }} password: ${{ secrets.GHCR_ACCESS_TOKEN }} - name: Build and push Docker image uses: docker/build-push-action@v5 with: context: . platforms: ["linux/amd64", "linux/arm64"] push: true tags: ghcr.io/your-username/your-app:latest - name: SSH into VPS and deploy uses: appleboy/ssh-action@v1.0.3 with: host: your-vps-ip username: deploy-user key: ${{ secrets.SSH_PRIVATE_KEY }} script: | cd /path/to/app docker-compose pull docker-compose up -d |