GitLab CI/CDとSSHによる本番反映¶
main の履歴に含まれるコミットに保護タグを作成・pushすると、所属確認・型チェック・静的ビルド・ブラウザー検査・バックエンド検証・本番反映を順に自動実行します。本体サイトの公開はタグで実行し、ブランチへのpush・マージでは実行しません。検査済みの同じ成果物を転送し、本番ではビルドしません。
別途、保護されたmainへリポジトリ直下のREADME.mdまたはdocs/配下の変更をpush・マージした場合は、docs:buildとdocs:deployでCloudflare Pagesの文書サイトを更新します。直接pushを禁止し、マージ時だけ実行する運用にします。必要な変数、閲覧制限はドキュメントサイトの公開・更新を参照してください。MRの作成・更新ではパイプラインを作成しません。
公開専用の release ブランチは使用しません。タグはブランチに所属する情報を持たないため、validate-main ジョブが main を取得し、タグの対象コミットがその履歴に含まれることを検証します。含まれない場合はパイプラインを失敗にし、ビルド・本番反映・切り戻しは実行しません。履歴に含まれる過去のコミットも対象になるため、通常は最新の main にタグを作成してください。
自動配置と手動更新の範囲¶
フロントは自動配置、バックエンドはCIで検証して手動配置する方針です。現在のパイプラインから内部アプリサーバーへ接続したり、APIを再起動したりする処理は追加しません。
| 対象 | 検証 | 配置 |
|---|---|---|
| フロントの静的サイト | 型チェック・ビルド・ブラウザー検査 | 保護タグのpush後にNGINXへ自動配置 |
| ドキュメントサイト | MkDocsの厳格ビルド・リンク検査 | mainの文書変更時にCloudflare Pagesへ自動配置 |
| お問い合わせバックエンド | Node.js 24系・22系のテスト、SAM検査 | 必要な更新時だけ担当者が手動配置 |
自前版は手動更新・切り戻し手順に従います。Runnerへバックエンド用のSSH接続先・鍵やSMTP認証情報を登録する必要はありません。AWS版を選ぶ場合は既存のSAM手順で別途配置します。
初回構築・設定変更¶
Runner、SSH、NGINX、GitLab変数、保護タグの準備は初回セットアップを参照してください。公開設定を変更した場合も、新しいタグで再ビルド・再配置します。
検証ジョブ¶
| ジョブ | 内容 |
|---|---|
validate-main |
タグの対象コミットがmainに含まれることを確認 |
build |
production環境の公開設定を使って型チェックと本番ビルドを実行。Turnstileの無効化を拒否 |
qa |
npm run qa:builtとnpm run qa:securityでビルド済みの成果物・CSPをブラウザー検査 |
backend:test |
Node.js 24系で自前版・共通処理を含む全テストを実行 |
backend:test:lambda-node22 |
Lambda経路をNode.js 22系で検証 |
infra:lint |
AWS SAMテンプレートをcfn-lintで検査 |
deploy-production |
同じ成果物をSSHで配置し、リンク切り替え後のHTTP応答を確認 |
rollback-production |
緊急時に手動で直前の版へ戻す。自動デプロイとは別に実行 |
定義は .gitlab-ci.yml です。
qa:contactとqa:searchは作業端末での追加検証用として維持しています。CIのqaは、LinuxではPlaywrightのChromium、WindowsではChromeを使用します。外部通信は遮断します。
通常の更新¶
- 作業ブランチでソースを変更し、ローカルで
npm run check→npm run build→npm run qa:builtを実行してからpushします。このpushではCIは実行されません。 - マージリクエストを確認し、
mainへマージします。本体の公開用CIはまだ実行されません。リポジトリ直下のREADME.mdまたはdocs/配下の変更を含む場合は、文書用CIだけが実行されます。 - 最新の
mainを取得し、公開用の新しい保護タグ(例:v1.0.0)を作成してpushします。GitLab画面でタグを作成する場合は、対象にmainの公開したいコミットを指定します。 - CIで
validate-main→npm ci→npm run check→npm run build→npm run qa:built→npm run qa:securityを実行し、既存のbackend:test(Node.js 24系)、backend:test:lambda-node22(Node.js 22系)、infra:lint(SAM検査)も実行し、すべて成功するとdeploy-productionが自動実行されます。 - 転送が完了すると公開リンクを原子的に切り替え、ループバック経由で取得した
/deploy-version.txtが今回のコミット・パイプラインと一致すること、および公開HTTPS URL経由でのトップページのHTTP応答を確認します。
ローカルでタグを作成する例です。v* の保護設定を済ませ、タグ名は未使用のものに置き換えてください。ローカルでのタグ作成だけではCIは実行されず、push時に実行されます。
git switch main
git pull --ff-only origin main
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
ヘルスチェックで失敗した場合は、元の公開リンクに戻してジョブを失敗にします。SSH切断や強制終了、サーバー停止では復元処理まで完了しない場合があるため、ジョブログと公開リンクを確認してください。HTTP応答確認は全ページの目視確認を代替しません。
デプロイと切り戻しは同じ resource_group で直列に実行します。サーバー側でも公開操作をflockで排他制御します。管理者がCI以外から公開リンクを書き換えると運用状態がずれるため、通常の更新はCIに統一してください。
本体の成果物と検査結果の保存期間は14日です。本体公開用パイプラインは保護タグだけを対象にします。文書用は保護されたmainの対象ファイル変更時だけ実行し、MR、保護されていないタグ、スケジュール、Run pipelineボタンからの新規パイプラインは作成しません。main 外のコミットへの保護タグはパイプラインを作成しますが、所属確認で失敗します。修正を再公開する場合は main へマージしたうえで新しい保護タグを作成します。build:preview のnoindex付き成果物は本番デプロイに使用しません。
バックエンドのテストとブラウザー検査はSMTP・Turnstileなどの外部サービスを代替し、実メールを送信しません。SAM検査にもAWS認証情報は不要です。テストで使う依存関係やブラウザーの取得には初回セットアップに記載したネットワーク接続が必要です。
切り戻しと保存容量¶
緊急時は進行中の自動デプロイがないことを確認し、validate-main が成功した既存のタグパイプラインで rollback-production を手動実行します。ビルド成果物やQAの完了を待たず、サーバーの previous へ戻します。対象はそのパイプラインのコミットではなく、サーバーに保存された直前の版です。切り戻し後も同じヘルスチェックを行い、失敗時は操作前のリンクへ戻します。
同じ切り戻しを繰り返すと「既に直前の版を公開中」として失敗します。さらに古い版へ戻す場合は、保持されたリリースとコミットを確認して管理者が対応してください。切り戻し後は原因を修正またはGitでrevertして main へマージし、新しい保護タグを作成して公開します。
キャッシュされたHTML/CSSから旧ファイルを参照できるよう、_astro/・assets/・hp_pdf/ の不足ファイルを直前の版から引き継ぎます。今回生成したファイルを優先し、削除したページのHTMLは引き継ぎません。同名で内容を変更した画像などは新版になります。旧版と新版を同時配信したい資産はファイル名を変えてください。
古いリリースや引き継いだ資産は自動削除しません。容量を監視し、current と previous の参照先を確認したうえで、必要な切り戻し期間・キャッシュ期間を過ぎたものを管理者が整理します。機密化などで即座に配信停止すべきファイルは、保持された各版からの除去とキャッシュ削除を別途行います。
デプロイジョブが失敗した場合¶
ジョブログの ERROR: と Deploy: を確認します。スクリプトは変数名・検証条件・実行段階を表示し、秘密鍵や変数の値は表示しません。秘密鍵を含むコマンドがログに出るため、原因調査で bash -x や set -x は使用しないでください。
| 表示・停止箇所 | 確認する設定 |
|---|---|
DEPLOY_HOST must ... |
DEPLOY_HOST は本番のホスト名またはIPv4のみ。https://、ユーザー名、ポート、空白を含めない |
DEPLOY_PATH must ... |
例は /var/www/tectas。末尾の / や空白を付けない。current へのリンク切り替えはスクリプトが行うため、この例では /var/www/tectas/current を設定しない |
SSH_PRIVATE_KEY_BASE64 ... |
Typeを Variable、Visibilityを Masked and hidden(未対応なら Masked)にし、秘密鍵ファイル全体をBase64にした改行・空白のない1行を登録する |
SSH_KNOWN_HOSTS must ... |
Typeを File にし、Valueにはknown_hostsの内容を登録する。本番上のファイルパスを登録しない |
not a valid unencrypted private key |
秘密鍵全体、末尾の改行、改行形式、パスフレーズが空であることを確認する |
Deploy: remote prepare 以降 |
SSHの接続・認証エラー、または本番側のパス・権限エラーを、その直後のメッセージで確認する |
Expected a release symlink |
本番の current・previous が、必要なファイルを含む releases/ 内のディレクトリへのリンクであるか確認する |
古いスクリプトで bash scripts/deploy.sh deploy の直後に理由なく終了する場合、入力値や本番側の検証で停止した可能性があります。そのログだけでは停止条件を特定できません。上表の設定を確認し、診断表示を追加した変更を main にマージしたうえで新しい保護タグを作成すると、実行段階と失敗理由を確認できます。既存タグのジョブをRetryしても、そのタグの古いスクリプトが実行されます。変数設定だけを修正した場合は、既存ジョブのRetryで反映を確認できます。