pushしてもVMには届かない — GitHub ActionsとCI/CD

GitHub ActionsとCI/CD。コードの書類からチェックを経てサーバーへ進む作業カード、歯車。

※本記事はアフィリエイト広告(PR)を含みます。

いま ~/server は GitHub に上がっています。そして、上がっているだけです。

roadmap.sh のどこをやっているか

DevOps›CI/CD
  • GitHub Actions
  • セルフホストランナー
  • Secrets の扱い

この記事は、上の項目を実際に手を動かして確かめる回です。

前回: GitとGitHubは別物 — VMのコードを初めて上げる(この回はその続きです。順路の並びでは ArgoCD の回の次に置いていますが、ArgoCD の回はこの回を読んだ前提で書いているので、こちらを先に読んでください) 作業場所はVMの中(Ubuntu)です。前回 GitHub に上げた ~/server をそのまま使います。

前回の最後に、こう書きました。

push したら自動でテストを回す CI は、まだ何もやっていません。

コードを直して push しても、誰も何も確かめてくれません。 動かないコードでも同じように上がります。VMに反映するのも手作業です。git pull して、npm install して、マイグレーションを流して、サービスを再起動する。この4つを、毎回、順番どおりに、忘れずに。

この回で、そこを機械にやらせます。ただし、半分だけです。

理由は、この記事の一番大事なところに書いてあります。⑥です。 先に結論だけ言うと、GitHub の実行環境は、あなたのVMに絶対に到達できません。 よくある「push したら自動でデプロイ」の記事は、インターネットから届くサーバーを前提にしています。あなたのVMは、そうではありません。

対象レベル: 中級 / 区分: 必修

目次

この記事でわかること

  • CI と CD は別物だということ(統合の自動化 / 配布の自動化)。混ぜて覚えると詰まる
  • GitHub の実行環境(ランナー)は、NATの内側のVMに到達できないこと。だから「push で自動デプロイ」はそのままでは成立しない
  • npm ci と npm install は別のコマンドで、CI で使うのは ci のほうだということ
  • セルフホストランナーは便利だが、公開リポジトリでは他人のコードを自分のVMで実行しうること

この記事でやること

  1. テストを1本書く(~/server にはまだ1本も無いので、そこから)
  2. ワークフローを1本書いて、push のたびに自動でテストが走るようにする
  3. セルフホストランナーをVMの中で動かし、GitHub から仕事を取りに来させる
  4. デプロイを手動ボタンで実行し、失敗したときに戻す手順まで用意する

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
CIContinuous Integration。変更を頻繁に合流させ、そのたびに自動で確かめるやり方
CDContinuous Delivery / Deployment。確かめたものを、自動で配るやり方
ワークフローGitHub Actions で「いつ・何をするか」を書いたファイル。.github/workflows/ に置く
ジョブ / ステップワークフローの中身。ジョブが実行のかたまり、ステップがその中の1コマンド
ランナーワークフローを実際に実行するマシン。GitHub が貸すものと、自分で用意するものがある
セルフホストランナー自分のマシンをランナーとして登録したもの。今回はVMがこれになる
SecretsGitHub に預ける秘密の値。ワークフローの中から名前で呼び出せる
ワークフローディスパッチワークフローを 画面のボタンから手で起動できるようにする設定

① CI と CD は別物

この2つは「CI/CD」と続けて書かれるので、1つの物だと思われがちです。違います。

正式には何を自動化しているか無いとどうなるか
CI継続的インテグレーション合流したコードを確かめること壊れたコードが気づかれずに溜まる
CD継続的デリバリー / デプロイ確かめたものを配ること反映が手作業。手順を1つ飛ばして事故る

CI が答えるのは「これは壊れていないか」です。 テストを走らせ、書式を確認し、ビルドが通るかを見ます。結果は「○か×か」だけで、どこにも配りません。

CD が答えるのは「これをどこへ、どうやって置くか」です。 動くと分かったものを、実際に動く場所へ運びます。

順番があります。CI が無いまま CD だけ作ると、「壊れたコードを、より速く、より確実に本番へ届ける仕組み」になります。 手作業のほうがまだマシです。必ず CI から作ります。

CD の中の、もう1つの分かれ目

CD には2つあって、これも別物です。

何が自動かボタンを押す人
継続的デリバリー(Delivery)「いつでも配れる状態」までが自動人が最後に押す
継続的デプロイ(Deployment)配るところまで自動誰も押さない

この記事で作るのはデリバリーのほうです。 最後は自分でボタンを押します。理由は⑩に書きます。

② CI を作る前に — テストが1本も無い

~/server にテストは1本もありません。 つまり、いま CI を組んでも確かめるものがありません。

「ビルドが通るか」も確かめられません。Node.js はビルドしないからです(ビルドツールの回でやったのはフロント側の話です)。

だからテストを書くところから始めます。

追加のライブラリは入れません

テストというと Jest や Vitest の名前が出てきますが、この記事では何も入れません。

Node.js 18 以降には、テストの仕組みが最初から入っています。 node:test というモジュールと、node --test というコマンドです。

まずVMの中で、Node のバージョンを確認します。

bash
$ node -v
v22.14.0

v18 以上なら進めます。 npmの回で nvm を入れているので、v22 系のはずです。

なぜ標準のものを使うのか。 ライブラリを入れると、そのライブラリの設定ファイルと使い方を、テストと同時に覚えることになります。いま覚えたいのは「テストとは何か」だけです。道具を増やすのは、標準で足りなくなってからで間に合います。

テストできる形に切り出す

テストは「入れたら出てくる」ものに対して書くのが一番簡単です。

いまの app.js の中身は、リクエストを受けて、データベースに触って、レスポンスを返します。これをテストするには、テスト側でデータベースを用意しないといけません。 最初の1本にしては重すぎます。

そこで、データベースに触らない部分を1つ切り出します。 タスクのタイトルを受け取って、使える形に整える関数です。

bash
$ mkdir -p ~/server/lib
$ nano ~/server/lib/validate.js
// タイトルを整える。使えない入力なら null を返す
function normalizeTitle(input) {
  if (typeof input !== "string") return null;

  const t = input.trim();
  if (t.length === 0) return null;
  if (t.length > 100) return null;

  return t;
}

module.exports = { normalizeTitle };

この関数は、外の世界に一切触りません。 引数だけを見て、戻り値だけを返します。だから、どこでも同じ結果になります。

テストが書きにくいコードは、たいてい「1つの関数が、いろいろやりすぎている」だけです。 「テストのために切り出す」というより、切り出したほうが読みやすいから切り出す、と考えたほうが正しいです。テストはその副産物です。

テストを書く

bash
$ mkdir -p ~/server/test
$ nano ~/server/test/validate.test.js
const test = require("node:test");
const assert = require("node:assert/strict");
const { normalizeTitle } = require("../lib/validate.js");

test("前後の空白を落とす", () => {
  assert.equal(normalizeTitle("  牛乳を買う  "), "牛乳を買う");
});

test("空文字は使えないので null", () => {
  assert.equal(normalizeTitle(""), null);
});

test("空白だけも使えないので null", () => {
  assert.equal(normalizeTitle("   "), null);
});

test("文字列でないものは null", () => {
  assert.equal(normalizeTitle(123), null);
  assert.equal(normalizeTitle(undefined), null);
});

test("100文字は通るが、101文字は通らない", () => {
  assert.equal(normalizeTitle("あ".repeat(100)).length, 100);
  assert.equal(normalizeTitle("あ".repeat(101)), null);
});
書いたもの意味
require("node:test")node: で始まるのは Node.js に最初から入っているモジュール。npm install は要らない
assert/strict== ではなく === で比べる版。JavaScriptの回でやった "1" == 1 の事故を、テストの中で起こさないため
test("説明", () => {...})1つのテスト。第1引数は失敗したときに画面に出る名前
assert.equal(実際, 期待)違っていたら、そこで失敗にする

テストの名前は日本語で構いません。 失敗したときに読むのは自分です。

走らせる

bash
$ cd ~/server
$ node --test
✔ 前後の空白を落とす (0.9ms)
✔ 空文字は使えないので null (0.1ms)
✔ 空白だけも使えないので null (0.1ms)
✔ 文字列でないものは null (0.1ms)
✔ 100文字は通るが、101文字は通らない (0.2ms)

ℹ tests 5
ℹ pass 5
ℹ fail 0

fail 0 が出れば通っています。

node --test は、引数を付けないと *.test.js のような名前のファイルと、test/ フォルダの中の .js ファイルを自分で探して回ります(node_modules/ は除きます)。test/ の中なら、名前に関係なくテストとして扱われます。 バージョンによって探し方の細部が違うので、見つからないときは node --test test/ のようにフォルダを指定してください。

わざと失敗させて、失敗の形も見ておきます。 validate.js の t.trim() を input に書き換えて、もう一度 node --test を打ってください。

✖ 前後の空白を落とす (1.2ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  + actual - expected

  + '  牛乳を買う  '
  - '牛乳を買う'

+ actual(実際にこうなった)と - expected(こうなってほしかった) の2行を読みます。確認したら元に戻してください。

一度も失敗させていないテストは信用できません。 「実は何も確かめていない」テストは、書き間違いで簡単に生まれます。通ったら、わざと壊して、ちゃんと落ちることまで見ます。

npm test で呼べるようにする

package.json を開きます。

bash
$ nano ~/server/package.json

"scripts" の中を、こうします。

  "scripts": {
    "test": "node --test"
  },

元から "test": "echo \"Error: no test specified\" && exit 1" と書かれています。 npm init が置いていったもので、「テストが無い」と言って必ず失敗する中身です。そこを置き換えます。

bash
$ cd ~/server
$ npm test

さっきと同じ結果が出れば成功です。

これが後で効きます。 ワークフローには npm test とだけ書きます。テストの走らせ方を変えたくなったとき、直すのは package.json の1行だけで、ワークフローは触らずに済みます。

③ npm ci と npm install は別のコマンド

ワークフローを書く前に、ここを片付けます。

前回、こう書きました。

package-lock.json は上げます。 これは「実際に入れたバージョンの記録」で、他の人が同じバージョンを再現するために要ります。

その回収です。

何を見るかpackage-lock.json を既存の node_modules/ を
npm installpackage.json(範囲で書かれている)書き換えることがある残したまま差分だけ入れる
npm cipackage-lock.json(1つのバージョンに確定)絶対に書き換えないまるごと消してから入れ直す

package.json にはこう書かれています。

"express": "^4.19.2"

^ は「4系ならもっと新しくてもいい」という意味です。 だから npm install は、今日と明日で違うバージョンを入れることがあります。

package-lock.json には、実際に入れた1つのバージョンが書いてあります。 npm ci はそれしか見ません。だから、いつ・どのマシンで実行しても、まったく同じものが入ります。

CI で使うのは npm ci です。 「手元では通るのに CI では落ちる」「昨日は通ったのに今日は落ちる」の原因の多くが、バージョンが勝手に動いていることだからです。確かめる場所では、動くものを1つずつ減らします。

そして npm ci は、package-lock.json が無いと動きません。

npm error The `npm ci` command can only install with an existing package-lock.json

前回 package-lock.json を上げておいたのは、このためです。

もう1つ、npm ci は package.json と package-lock.json が食い違っていても止まります。 これは意地悪ではなく、「lock を更新せずに push した」ことを教えてくれています。 手元で npm install して、package-lock.json も一緒にコミットしてください。

④ ワークフローを1本書く

GitHub Actions は、リポジトリの中の .github/workflows/ に置いた YAML ファイルを見て動きます。 管理画面で設定するものではありません。設定そのものが、コードと一緒に履歴に残ります。

VMの中で作ります。

bash
$ mkdir -p ~/server/.github/workflows
$ nano ~/server/.github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: コードを取得する
        uses: actions/checkout@v4

      - name: Node.js を用意する
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: 依存を入れる
        run: npm ci

      - name: テストを走らせる
        run: npm test

1行ずつ読みます。

行意味
name: CI画面に出る名前。何でもいい
on:いつ動くか。ここでは main への push と、main 宛のプルリクエスト
jobs:やることのかたまり。複数書ける
runs-on: ubuntu-latestGitHub が貸してくれる Ubuntu のマシンで動かす。⑦で効いてきます
steps:上から順に実行される
uses:他人が作った部品を呼ぶ。@v4 はバージョンの指定
run:そのマシンでコマンドを打つ

uses: の2つは、GitHub 公式が配っている部品です。

  • actions/checkout — これが無いと、リポジトリのファイルが1つもありません。 ランナーは「まっさらなマシン」なので、自分でコードを持ってくる必要があります。 最頻出の書き忘れです
  • actions/setup-node — 指定したバージョンの Node.js を入れます

uses: は「他人のコードを、自分のワークフローの中で実行する」ということです。 actions/ で始まるものは GitHub 公式ですが、それ以外は他人のリポジトリです。 @v4 のようにバージョンを固定しておかないと、相手が中身を差し替えた瞬間に、自分のワークフローの動きも変わります。 nvm の回で「タグでバージョンを固定する」と書いたのと、同じ話です。

インデント(行頭の空白)が意味を持ちます。 タブは使えません。半角スペースだけです。

push する

bash
$ cd ~/server
$ git add .github package.json lib test
$ git status

.env と .env.migrate と node_modules/ が一覧に無いことを、ここでもう一度確認してください。

bash
$ git commit -m "テストとCIのワークフローを追加"
$ git push

.github はドット始まりのフォルダです。 git add . でも入りますが、ls では見えません。 見るときは ls -a ~/server です(Linuxの基本コマンドの回)。

SSH鍵で push しているので、ここは何も追加設定が要りません。 PAT(トークン)で push している場合だけ、ワークフローファイルの push には専用の権限が要ることがあります。前回SSH鍵にしておいた分、ここが楽になっています。

⑤ 自動で走ったことを確認する

ブラウザで GitHub のリポジトリを開き、上のほうにある Actions タブを開いてください。

push した直後なら、実行が1件、動いているはずです。 黄色い丸が「実行中」、緑のチェックが「成功」、赤い×が「失敗」です。

[スクリーンショット: 01_actions_tab.png] Actions タブに、CI の実行が1件並んでいる画面を撮ってください。リポジトリ名やアカウント名が写るので、隠したければ塗りつぶして構いません。

実行をクリックすると、左に test というジョブが出ます。 さらにクリックすると、ステップごとのログが読めます。各ステップの左の > を押すと開きます。

[スクリーンショット: 02_workflow_run.png] テストを走らせる のステップを開いて、pass 5 fail 0 が見えている画面を撮ってください。

ここまでで CI が1つ完成しました。

これから先、あなたが push するたびに、GitHub が勝手にテストを走らせます。 落ちればメールが来ます。リポジトリのトップにも赤い×が出ます。

ここまでで、もう十分に価値があります。 この記事の残りを全部やらなくても、「壊れたまま気づかない」が消えます。 ⑪でもう一度書きます。

失敗も1回見ておく

成功だけ見て終わると、失敗したときに読めません。

lib/validate.js の t.length > 100 を t.length > 5 に書き換えて、push してみてください。

bash
$ cd ~/server
$ git add lib/validate.js
$ git commit -m "わざと壊す"
$ git push

数十秒後、Actions タブに赤い×が付きます。 開くと、手元で見たのと同じ AssertionError が出ています。

確認したら戻します。

bash
$ cd ~/server
$ git revert --no-edit HEAD
$ git push

git revert は「そのコミットを打ち消すコミットを、新しく作る」コマンドです。 履歴を消すのではなく、「戻した」という事実も履歴に残ります。 ⑩の考え方と同じです。

⑥ ここから CD — GitHub のランナーは、あなたのVMに届かない

この記事の一番大事なところです。

「CI ができたので、次は push したら自動でVMにデプロイ」と続けたくなります。そのままでは成立しません。

理由は、ネットワークです。

どこにいるか外から入れるか
GitHub のランナー(ubuntu-latest)GitHub のデータセンター。実行のたびに作られて、終わったら捨てられる—
あなたのVM自宅PCの中の VMware。さらに NAT の内側入れない

あなたのVMには、グローバルIPアドレスがありません。 ドメイン名もありません。ネットワークの回でやったとおり、NATの内側にいるマシンは、外から名指しできません。

つまり、GitHub のランナーがあなたのVMに ssh することは、絶対にできません。

世の中の「GitHub Actions で自動デプロイ」の記事は、ほぼ全部が 「インターネットから ssh で入れるサーバー」を前提にしています。 レンタルサーバー、クラウドの仮想マシン、そういうものです。あなたのVMはそこに含まれません。 SSH_HOST に何を書いても届きません。 ここで詰まるのは、あなたの設定が悪いからではありません。

選べる道は3つ

やり方成立するかこの記事では
ランナーからVMに ssh で入る成立しない。届かないのでやらない
VMをインターネットに公開する(ポート開放・固定IP・トンネル)成立するが、練習用のVMを外に晒すことになるやらない
VMの中からGitHubへ、仕事を取りに行く成立するこれをやります

3つ目が、この記事の答えです。

入れないなら、出ればいい。 NAT は「外から入る」を止めますが、「中から出る」は止めません。ブラウザで GitHub を開けているのが、その証拠です。ufw も既定では出て行く通信は通します。

VMの中に「GitHubに仕事が無いか聞きに行き続けるプログラム」を置きます。 それがセルフホストランナーです。

届かない理由は、VM が自宅のネットワークの内側にいて、外から到達できるアドレスを持っていないからです。ランナーの置き場や CD の着地点として、シンVPSのようにインターネットから直接届き、API や CLI でサーバー操作を自動化できる VPS を使う構成もありますが、その場合は鍵の管理とファイアウォールの責任がそのまま自分に来ます。2026年11月時点では 2GB(2コア・50GB)が 1 ヶ月 1,040 円〜36 ヶ月 950 円(税込)で、無料のお試し期間は無く、最低利用期間は 3 ヶ月です。

⑦ セルフホストランナー — その前に、危険の話

手順の前に読んでください。順番を逆にしません。

セルフホストランナーは、「GitHub のワークフローに書かれたコマンドを、あなたのVMで実行する」仕組みです。

言い換えると、ワークフローファイルを書き換えられる人は、あなたのVMで好きなコマンドを実行できます。

危険何が起きるか
公開リポジトリ + プルリクエスト見知らぬ他人が送ってきたコードが、あなたのVMで動きます。 PRにはワークフローファイルの変更も含められます
ランナーは使い捨てではないGitHub のランナーは毎回捨てられますが、セルフホストは同じマシンが残ります。 前のジョブが置いていったファイルが、次のジョブから読めます
VMの中身が全部見えるランナーはあなたのユーザー権限で動きます。~/server/.env も、~/.ssh/id_ed25519 も読めます
VMの外も危ないVMは自宅のネットワークの中にいます。そこから見える機器に手が届きます

だからルールは1つです。

セルフホストランナーは、非公開リポジトリでだけ動かします。 GitHub 自身が、公開リポジトリでの使用を推奨しないと明記しています。 前回 Private を選んでいるので、そのままなら条件は満たしています。Public に変えたくなったら、先にランナーを外してください。

「自分しか使わないから大丈夫」は、公開リポジトリでは成り立ちません。 プルリクエストは、誰でも送れます。

⑧ セルフホストランナーをVMに入れる

GitHub の画面で、リポジトリの Settings → 左メニューの Actions → Runners を開きます。

New self-hosted runner を押し、Linux と x64 を選びます。

すると、VMの中で打つコマンドが、そのページに表示されます。

そのコマンドをここに書き写しません。 ランナー本体のダウンロードURLにはバージョン番号が入っていて、更新されます。./config.sh に渡すトークンは1時間ほどで失効する使い捨てです。 書き写したものは、読むころには古くなっています。画面のものをコピーしてください。 画面の項目名や配置も変わることがあります。 見つからなければ Settings の中を Runner で探してください。

[スクリーンショット: 03_runner_setup.png] New self-hosted runner の画面(Linux / x64 を選んだ状態)を撮ってください。./config.sh --token ... の行のトークンは、必ず塗りつぶしてください。

何をしているコマンドなのか

コピペで終わらせないために、4段階に分けて読みます。

段階だいたいの中身何をしているか
1mkdir actions-runner && cd actions-runner専用のフォルダを作る
2curl -o actions-runner-linux-x64-*.tar.gz -L https://github.com/actions/runner/releases/download/...ランナー本体をダウンロードする
3tar xzf ./actions-runner-linux-x64-*.tar.gz展開する
4./config.sh --url https://github.com/your-name/server --token ...このリポジトリのランナーとして登録する

your-name は、あなたのアカウント名です。

置き場所は ~/server の中にしないでください。 ~/actions-runner のように、アプリとは別の場所に置きます。中に入れると、Git の管理対象に紛れ込みます。

./config.sh は4つ質問してきます。

質問答え
runner groupEnter(既定のまま)
name of runnerEnter(ホスト名になる)か、ubuntu-vm など
additional labelsEnter でよい。既定で self-hosted Linux X64 が付く
name of work folderEnter(_work になる)

./config.sh を sudo で実行しないでください。 root で動くランナーになります。 ワークフローに書かれたコマンドが、VMの何でも変更できる状態になります。自分のユーザーのまま実行します(権限の回の「余計な権限を使わない」)。

まず手で動かして、確かめる

いきなりサービスにしません。 先に、目の前で動かして様子を見ます。

bash
$ cd ~/actions-runner
$ ./run.sh
√ Connected to GitHub

Current runner version: '2.xxx.x'
Listening for Jobs

Listening for Jobs(仕事を待っています)が、成功の合図です。

この1行が、⑥で書いたことの答えです。 GitHub がVMに繋ぎに来たのではありません。VMが GitHub に繋ぎに行きました。 だから NAT の内側でも成立します。

ブラウザの Settings → Actions → Runners を再読み込みすると、緑の Idle で並んでいます。

[スクリーンショット: 04_runner_idle.png] Runners の一覧に、登録したランナーが Idle で出ている画面を撮ってください。

確認できたら Ctrl + C で止めます。

サービスとして常駐させる

./run.sh は、ターミナルを閉じると止まります。 プロセスとサービスの回でやった systemd に任せます。ランナーには専用のスクリプトが付いてきます。

bash
$ cd ~/actions-runner
$ sudo ./svc.sh install
$ sudo ./svc.sh start
$ sudo ./svc.sh status

active (running) が出れば常駐しています。 VMを再起動しても自動で立ち上がります。

ここだけ sudo を使います。 systemd にサービスを登録する作業だからです。登録されるサービス自体は、config.sh を実行したユーザーの権限で動きます。 ./config.sh を root でやらなかったのは、このためです。

止め方と外し方は「後片づけ」に書きました。先にそちらを読んでおいてください。

⑨ 秘密の値をどう渡すか — GitHub Secrets

.env は Git に入っていません。 では、ワークフローの中でデータベースのパスワードが要るときはどうするのか。

まず、今回は要りません

セルフホストランナーは、あなたのVMです。 ~/server/.env は、もうそこにあります。

だから、この記事のデプロイでは Secrets を1つも使いません。 これは手抜きではなく、渡す必要が無いから渡さないという判断です。秘密の値は、置き場所が増えるほど漏れやすくなります。

それでも仕組みは知っておく

「機械の中に無い値」が要るときに使います。 外部サービスのAPIキー、通知先のURL、クラウドの認証情報などです。

入れ方は、リポジトリの Settings → Secrets and variables → Actions → New repository secret。名前と値を入れて保存します。

保存すると、二度と読めません。 上書きするか消すかだけです。「あとで確認しよう」ができないので、控えは手元に置いてください。

使い方はこうです。

      - name: 秘密の値を使う例
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: node scripts/notify.js

env: で環境変数に入れて、プログラムの中から process.env.API_KEY で読みます。

守ること

絶対に echo しないでください。

run: echo "$API_KEY"     # ← やらない

ログは、リポジトリを読める人全員が読めます。 そしてログはしばらく残ります。

GitHub は、ログに Secrets の値が出たら *** に置き換えます。 ただし完全ではありません。

隠れる隠れない
登録した文字列と、完全に一致するもの一部だけ出したとき(${API_KEY:0:8} など)
形を変えたとき(Base64、URLエンコード、JSONに入れて整形)
改行を含む値(行ごとに分かれると一致しなくなることがある)

マスクは保険であって、仕組みではありません。「出さない」が本体です。

もう2つ、勘違いしやすい点があります。

  • 他人のフォークから送られたプルリクエストには、Secrets が渡りません。 GitHub がそう作っています。「PRだと動かない」の原因はこれで、故障ではありません
  • Secrets は共同作業者から守るものではありません。 リポジトリに書き込める人は、値を使うワークフローを自由に書けます。 「読めないから安全」ではありません

⑩ デプロイを書く — そして、戻せるようにする

ランナーが動いたので、VMの中で仕事をさせられます。

bash
$ nano ~/server/.github/workflows/deploy.yml
name: Deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: self-hosted

    steps:
      - name: いまの位置を控える
        run: |
          cd ~/server
          echo "== 戻すときはこのコミット =="
          git rev-parse HEAD

      - name: 最新を取り込む
        run: |
          cd ~/server
          git fetch origin main
          git merge --ff-only origin/main

      - name: 依存を入れ直す
        run: |
          cd ~/server
          npm ci

      - name: マイグレーションを流す
        run: |
          cd ~/server
          node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:latest

      - name: サービスを再起動する
        run: sudo systemctl restart myserver

      - name: 起きているか確かめる
        run: |
          sleep 5
          systemctl is-active myserver

ここで説明が要る点が5つあります。

1. on: workflow_dispatch — push では動かしません

これは「画面のボタンで手動で起動する」という指定です。

push で自動デプロイにしていません。 理由は3つです。

  • いまのテストは関数1つ分です。 「テストが通った = 動く」とは、まだ全然言えません
  • VMは電源が入っていないことがあります。 ランナーが居ないときの push は、ジョブが止まったまま待ち続けます
  • 失敗したときに、自分が画面を見ているほうがいい

①で書いた「継続的デリバリー」がこれです。 配れる状態までは自動、押すのは人。

workflow_dispatch のボタンは、そのワークフローファイルが main(既定のブランチ)に入っていないと出ません。 「Run workflow ボタンが無い」の原因は、ほぼこれです。まず push してください。

2. runs-on: self-hosted — ここが切り替えです

ubuntu-latest と書けば GitHub のマシン、self-hosted と書けばあなたのVM。 この1行だけで行き先が変わります。

ci.yml は ubuntu-latest のままにしておいてください。 テストはVMで動かす必要がありませんし、VMの電源が落ちていてもテストは走ってほしいからです。

3. actions/checkout を書いていません

ここは意図的です。

セルフホストランナーは、既定では自分の作業フォルダ(~/actions-runner/_work/...)にリポジトリを展開します。 しかし動かしたいアプリは ~/server にあります。 systemd の myserver.service も、WorkingDirectory として ~/server を見ています。

だから、ランナーの作業フォルダは使いません。 代わりに、すでにVMにある ~/server を git で更新します。 checkout を書くと、関係ない場所にもう1つコピーができるだけです。

4. merge --ff-only — 黙って上書きさせない

git pull ではなく fetch と merge --ff-only に分けています。

--ff-only は「まっすぐ進める場合だけ進む」という指定です。 VMの中でファイルを直接いじっていて履歴が枝分かれしていたら、マージせずに、その場で失敗します。

fatal: Not possible to fast-forward, aborting.

これは失敗ではなく、正しい停止です。 「何が入るか分からない自動マージ」を本番のフォルダで走らせないための線引きです。出たときの直し方は「つまずいたところ」に書きました。

5. sudo systemctl restart は、そのままでは止まります

ランナーは、あなたのユーザーの権限で動いています。 sudo を打つとパスワードを聞かれます。

そして、そこには誰も座っていません。 ジョブはパスワード待ちのまま止まるか、こうなります。

sudo: a terminal is required to read the password

解決は、「このコマンドだけはパスワード無しで許す」という設定を1つ足すことです。

bash
$ sudo visudo -f /etc/sudoers.d/myserver-deploy
ユーザー名 ALL=(root) NOPASSWD: /usr/bin/systemctl restart myserver

ユーザー名 は自分のログイン名に置き換えてください。 whoami で分かります。

書いたもの意味
sudo visudo -f ...nano で直接開かない。 visudo は保存時に文法を検査します
NOPASSWD:パスワードを聞かない
/usr/bin/systemctl restart myserverこのコマンドだけ。他は今までどおり聞かれます

NOPASSWD: ALL と書かないでください。 それは「このユーザーは、いつでも無条件に root になれる」という意味です。ランナーがVMを完全に支配できる状態になります。許すのは1コマンドだけです。

sudoers を壊すと sudo が一切使えなくなります。 だから visudo を使います。文法が間違っていると保存時に警告が出るので、そのときは e を押して直してください。 Q(無視して保存)を選ばないでください。

パスは環境で違うことがあるので、確認してから書きます。

bash
$ which systemctl
$ whoami

which systemctl が返したパスを、そのまま書いてください。

動かす

まず push します。

bash
$ cd ~/server
$ git add .github/workflows/deploy.yml
$ git commit -m "デプロイのワークフローを追加"
$ git push

Actions タブを開くと、左に Deploy が増えています。 選ぶと右上に Run workflow のボタンが出ます。押します。

[スクリーンショット: 05_deploy_run.png] Deploy が緑のチェックで終わり、起きているか確かめる のステップに active が出ている画面を撮ってください。

VMの側でも見えます。

bash
$ systemctl status myserver
$ journalctl -u myserver -n 20

失敗したときに、どう戻すか

ここを書かない自動デプロイは、事故装置です。

戻すものは2つあり、難易度が違います。

戻すもの難しさ
コード簡単。 Git が全部覚えている
データベースの構造難しい。 そしてデータが消えることがある

コードを戻す。 ワークフローの最初のステップに git rev-parse HEAD を入れておいたのは、このためです。ログにコミットIDが残っています。

bash
$ cd ~/server
$ git checkout 控えたコミットID
$ npm ci
$ sudo systemctl restart myserver
$ systemctl is-active myserver

戻し終わって、直したものを取り込むときは、枝に戻ります。

bash
$ cd ~/server
$ git checkout main

git checkout コミットID をすると、detached HEAD という状態になります。 「どの枝にも乗っていない、その瞬間だけを見ている」状態です。壊れてはいません。 git checkout main でいつでも戻れます。

データベースの構造は、コードと一緒には戻りません。

git checkout で戻るのはファイルだけです。 migrate:latest で足した列は、そのまま残っています。

ORMとマイグレーションの回で down を書いたのが、ここで効きます。

bash
$ cd ~/server
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:rollback

migrate:rollback は、down に書いたとおりのことをします。 down が「列を削除する」なら、その列に入っていたデータは消えます。 ロールバックは「無かったことにする」ではなく、「削除という操作を実行する」です。練習用のデータでしか気軽に打たないでください。

だから、順番で身を守ります。

やりたいこと安全な順番
列を足す先にマイグレーション、あとでコード。 古いコードは、知らない列があっても普通は動きます
列を消す・名前を変える先にコードから使うのをやめて、しばらく置いてから消す。 いきなり消すと、古いコードが即座に落ちます

「コードとデータベースを、同時に切り替えなくても動く形にしておく」 のが、戻せるデプロイの本体です。自動化はその上に乗るだけです。

⑪ やりすぎない

ここまでで、やりたくなることが山ほど出てきます。

全部あとでいいです。

よく足したくなるものいま要るか
MySQL を CI で立てて、DBを使うテストも回すまだ。services: で書けますが、先に普通のテストを増やすほうが効きます
Lint(ESLint など)を CI に足すテストが安定してからで十分
push で自動デプロイにするテストが薄いうちは危ない
Docker イメージを作って配るDocker の回の内容と繋がりますが、いまは分けたほうが読める
通知(Slack など)を飛ばすメールで届いています

この記事の到達点は、これだけです。

push すると、GitHub が勝手にテストを走らせて、通ったか教えてくれる。

それで十分です。 「壊れているのに気づかない」が消えるだけで、手作業のときとは別の安心があります。

CI/CD の記事は、たいてい完成形から始まります。 そして完成形は、そこに至った理由が全部消えた状態です。1本のテストと1本のワークフローから始めたほうが、後で足すときに「なぜ足すのか」が自分で分かります。

つまずいたところ

4つ詰まりました。

1. npm ci が CI で落ちた

npm error `npm ci` can only install packages when your package.json and package-lock.json are in sync

knex を入れたとき npm install knex はしたのに、package-lock.json をコミットしていませんでした。 手元には node_modules/ があるので、手元では最後まで気づきません。

bash
$ cd ~/server
$ npm install
$ git add package.json package-lock.json
$ git commit -m "package-lock.json を更新"
$ git push

これは CI が正しく仕事をした例です。 「自分のマシンにしか無い状態」に依存していたことを、push した瞬間に教えてくれました。

2. node --test がテストを見つけない

ℹ tests 0
ℹ pass 0

テストのファイルを、test/ ではなく ~/server の直下に validate.js という名前で置いていました。 node --test は、test/ フォルダの中の .js なら名前に関係なく拾いますが、それ以外の場所では *.test.js のような形の名前でないと見つけません。

bash
$ ls ~/server/test/

test/ の中に validate.test.js があるか確認してください。

3. sudo でジョブが止まった

Deploy を初めて動かしたとき、サービスを再起動する のステップで進まなくなりました。

sudo: a terminal is required to read the password

⑩の sudoers の設定を、あとから足しました。 順番としては、先に設定してからワークフローを動かすのが正解です。

ジョブが止まったままのときは、Actions の実行画面の右上から Cancel workflow で止められます。

4. merge --ff-only で止まった

fatal: Not possible to fast-forward, aborting.

VMの中で nano で直接ファイルを直して、そのままにしていました。 手元(VM)に、GitHub に無いコミットがある状態です。

何が違うかを、まず見ます。

bash
$ cd ~/server
$ git status
$ git log --oneline origin/main..HEAD

下のコマンドで出てくるのが「VMにしか無いコミット」です。 要るものなら push し、要らないものなら捨てます。

bash
$ git push          # 要るとき

この失敗は、実は設計の問題を教えています。 ~/server は「動かす場所」であって、「書く場所」ではありません。 両方を兼ねると、こうなります。

書くのは手元、動かすのはVM、と決めるのが本来です。ただし、いまは学習中で、書く場所もVMです。 そこは無理に分けず、「デプロイの前に、VM側の変更を push しておく」 を手順にしました。分かっていて兼ねるのと、気づかずに兼ねるのは別です。

後片づけ

この記事で足したものは、全部戻せます。

ランナーを止める。

bash
$ cd ~/actions-runner
$ sudo ./svc.sh stop

ランナーを完全に外す。

bash
$ cd ~/actions-runner
$ sudo ./svc.sh uninstall
$ ./config.sh remove

./config.sh remove はトークンを聞いてきます。 GitHub の Settings → Actions → Runners で、該当のランナーから取得できます。 取れないときは、GitHub の一覧側から削除すれば登録は消えます。

そのあとフォルダごと消せます。

bash
$ rm -rf ~/actions-runner

sudoers の設定を消す。

bash
$ sudo rm /etc/sudoers.d/myserver-deploy
$ sudo -k
$ whoami

sudo -k は「パスワードを覚えている状態を忘れる」コマンドです。 そのあと sudo を打ってパスワードを聞かれれば、元に戻っています。

ワークフローを止める。

ファイルを消して push すれば止まります。 残したまま一時的に止めたいだけなら、Actions タブでワークフローを選び、右上のメニューから Disable workflow を選びます。

課金の話。 セルフホストランナーは、自分のマシンなので GitHub への支払いは発生しません。 GitHub が貸すランナー(ubuntu-latest)は、公開リポジトリでは無料、非公開リポジトリでは無料枠の分数を消費します。 枠の数字はここに書きません。 変わるからです。Settings → Billing で、いまの使用量が見られます。 今回のテストは1回あたり1分もかからないので、普通に使っている分で枠を使い切ることは、まずありません。

まとめ

  • CI と CD は別物。 CI は確かめる自動化、CD は配る自動化。CI が先
  • CD にも2つある。 配れる状態までが自動=デリバリー、配るところまで自動=デプロイ。今回はデリバリー
  • テストが無いと CI は組めない。 ライブラリは要らない。Node.js 標準の node:test と node --test で始まる
  • テストしやすい形は、読みやすい形。 外に触らない関数に切り出しただけで、テストは簡単になる
  • 一度は必ず失敗させる。 落ちないテストは、何も確かめていないことがある
  • npm ci と npm install は別のコマンド。 CI で使うのは ci。そのために package-lock.json を Git に入れてある
  • ワークフローは .github/workflows/ に置く。 設定がコードと一緒に履歴に残るのが利点
  • actions/checkout を忘れると、ランナーにファイルが1つも無い
  • GitHub のランナーは、NATの内側のVMに絶対に到達できない。 「push で自動デプロイ」は、そのままでは成立しない
  • 解は「VMから GitHub に取りに行く」=セルフホストランナー。 外から入れなくても、中から出られれば成立する
  • セルフホストランナーは非公開リポジトリでだけ使う。 公開だと、他人のPRのコードが自分のVMで動きうる
  • ./config.sh を sudo で実行しない。 root のランナーは、VMを何でもできる状態になる
  • 秘密の値は Secrets に置き、絶対に echo しない。 マスクは完全ではない(形を変えると素通りする)
  • 今回は Secrets を使わない。 .env はもうVMにある。置き場所を増やさないのも安全策
  • sudo systemctl restart は、そのままでは止まる。 sudoers でそのコマンドだけを許す。NOPASSWD: ALL は書かない
  • 戻せるかを先に決める。 コードは git checkout で戻るが、データベースの構造は戻らない
  • 列は「足す→使う→消す」の順で。 コードとDBを同時に切り替えないと動かない形にしない
  • 最初は「テストが通ったか教えてくれる」だけで十分。 足すのは後からできる

ここまでで、機械が代わりに確かめてくれる状態になりました。 ただし、確かめているのは「push した瞬間」だけです。動き続けているサービスが、いま元気かどうかは、まだ誰も見ていません。そこは次以降で扱います。

参考リンク

GitHub Docs は改編が多く、URLも画面も変わります。 リンク先が見当たらないときは、上の日本語トップから 「セルフホストランナー」「シークレット」「ワークフロー構文」 で探してください。


次に読む

この記事は 【第6段階】インフラとコンテナ の 11 / 25 本目です。

記事
← 前の記事手で直した設定は勝手に戻る — ArgoCDでGitOps
→ 次の記事Prometheusは取りに行く — 監視とログの入口

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次