GitHub Actions¶

GitHub Actions を使えば、例えば main ブランチに push したら、まず pytest を実行して、PASS したら自分のローカルネットワークにあるサーバーでデプロイする、っていう CI(Continuous Integrity)/CD(Continuous Deployment) パイプラインを構築できる。

必要なのは、ワークフローファイルを .github/workflows/my-actions.yml (ファイル名はなんでもいい)のように作成しておいて、 GitHub にソースコードと一緒にあげること。

ワークフローファイルのサンプル¶

.github/workflows/my-actions.yml

name: CI/CD pipeline

on:
  push:
    branches: [ "main" ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@v8.0.0
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Install dependencies
        run: uv sync --frozen

      - name: Run tests
        run: uv run pytest

  deploy:
    needs: test
    runs-on: self-hosted
    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Install dependencies
        run: uv sync --frozen

      - name: Restart service
        run: sudo systemctl restart fastapi-app

テストが成功したときだけデプロイする

deploy に needs: test をつけてるので、 test ジョブが成功したときだけ deploy ジョブが走る。
pytest が失敗したらデプロイされない: cf. Defining prerequisite jobs (needs)

`test` ジョブ（ubuntu-latest）¶

cf. GitHub-hosted runners

runs-on: ubuntu-latest — GitHub がホストするサーバーで pytest を実行する。
actions/checkout@v6 — リポジトリのコードを GitHub サーバーにコピーする。
astral-sh/setup-uv@v8.0.0 — uv をインストールする。 enable-cache と cache-dependency-glob: "uv.lock" で、 uv.lock が変わらない限り依存をキャッシュして高速化する。
uv sync --frozen — uv.lock の内容そのままで依存をインストールする。 --frozen をつけると uv.lock を更新せず、ロックと pyproject.toml がズレてたらエラーにする。 CI ではロックを勝手に書き換えてほしくないので --frozen にしておく方がいいか。
uv run pytest — テストの実行: cf. pytest

`deploy` ジョブ（self-hosted）¶

cf. About self-hosted runners

デプロイ先のサーバーに self-hosted runner をセットアップしておくと、そのサーバー上でジョブが走る。ここではコードを取得して uv で同期した後で、 systemd で FastAPI のサービスを再起動する。

runs-on: self-hosted — 自前のサーバー（self-hosted runner）で実行する。 runner がチェックアウトした場所で、そのまま依存の同期とサービス再起動をやる。
uv sync --frozen — デプロイ先でも同じロックファイルから依存をそろえる。
sudo systemctl restart fastapi-app — FastAPI を動かしてる systemd サービスを再起動して、新しいコードを反映する。

Note

このサンプルは、デプロイ先サーバーに self-hosted runner と FastAPI の systemd サービス、 sudoers が用意されてる前提。セットアップ手順は self-hosted runner のセットアップを参照。

self-hosted runner のセットアップ¶

cf. Adding self-hosted runners

デプロイ先のサーバー（ここでは RockyLinux、ユーザーは alice）に runner をインストールする。 GitHub リポジトリの Settings → Actions → Runners → New self-hosted runner → Linux を選ぶと、ダウンロードと config.sh での登録（ token 付き）のコマンドが表示されるので、それをサーバーで順に実行する。

alice は wheel グループ（sudo できる）前提

この手順の後半に出てくる sudo（ svc.sh install など）は、 alice が wheel グループに入っていて sudo できることが前提。

# usermod -aG wheel alice

グループ追加は今開いているセッションには即反映されないので、 usermod のあとはログインし直す（ id で wheel が出れば反映済み）。

ダウンロードして展開する。 URL / バージョン / token は GitHub の画面に出てくるものを使う。

$ cd ~

$ mkdir actions-runner && cd actions-runner

$ curl -o actions-runner-linux-x64-2.333.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.333.1/actions-runner-linux-x64-2.333.1.tar.gz

$ tar xzf ./actions-runner-linux-x64-2.333.1.tar.gz

config.sh で runner を登録する。いくつか聞かれるけど、基本そのまま Enter でいい。
```
$ ./config.sh --url https://github.com/<your-account>/my-fastapi-app --token <TOKEN>
```

./run.sh で起動すると、 GitHub を監視してるような状態（ Listening for Jobs ）になる。

$ ./run.sh

√ Connected to GitHub
Current runner version: '2.333.1'
2026-04-20 02:02:44Z: Listening for Jobs

この状態で main に push すると、ジョブが自動で走る。

2026-04-20 02:02:44Z: Listening for Jobs
2026-04-20 02:04:43Z: Running job: test
2026-04-20 02:05:12Z: Job test completed with result: Succeeded

./run.sh はターミナルを閉じると止まるので、常時 Listening for Jobs を維持するにはサービスとして登録する。
```
$ sudo ./svc.sh install

$ sudo ./svc.sh start
```
Note

svc.sh install は、 runner のファイルを持ってるユーザー（ここでは alice）で動くサービスとして登録される。なのでジョブも alice で走り、チェックアウト先は /home/alice/actions-runner/_work/my-fastapi-app/my-fastapi-app のようになる。
- <runnerインストール先>/_work/ は、 config.sh の work フォルダ設定（デフォルト _work ）で決まる。
- リポジトリ名が 2 回繰り返される部分は、 GITHUB_WORKSPACE を参照

runner のセットアップができたら、 FastAPI 本体を systemd サービスとして登録する。 runner と同じユーザー（ alice ）で動かすシステムサービス設定例。

systemd の設定

WorkingDirectory を runner のチェックアウト先（ <runnerインストール先>/_work/<リポジトリ名>/<リポジトリ名> ）にしておけば、デプロイステップの uv sync と再起動がそのまま反映される（コピー処理は不要）。

/etc/systemd/system/fastapi-app.service

[Unit]
Description=FastAPI App
After=network.target

[Service]
User=alice
Group=alice
WorkingDirectory=/home/alice/actions-runner/_work/my-fastapi-app/my-fastapi-app
ExecStart=/home/alice/.local/bin/uv run gunicorn -c gunicorn_config.py app.main:app
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudoers の設定

alice ユーザーがパスワードなしで sudo systemctl restart fastapi-app を実行できるようにしておく。
/etc/sudoers.d/fastapi-deploy
```
alice ALL=(root) NOPASSWD: /usr/bin/systemctl restart fastapi-app
```

Gunicorn の設定

gunicorn_config.py を作成しておく。

gunicorn_config.py

import multiprocessing

worker_class = "uvicorn_worker.UvicornWorker"
workers = multiprocessing.cpu_count() * 2 + 1
bind = "0.0.0.0:8000"

SSH 鍵と Deploy Key の登録¶

self-hosted runner は GitHub がくれるトークンでチェックアウトするけど、デプロイ先サーバーから自分で git pull したりプライベートリポジトリにアクセスするには、 SSH 鍵を作って GitHub に Deploy Key として登録しておくのが楽。 Deploy Key は「1つのリポジトリだけにアクセスできる SSH 公開鍵」で、アカウント全体に効く個人の SSH 鍵より権限を絞れる: cf. Managing deploy keys

デプロイ先サーバーで SSH 鍵（ ed25519 ）を生成する。自動化で使うならパスフレーズは空でいい: cf. Generating a new SSH key
```
$ ssh-keygen -t ed25519 -C "alice@fastapi deploy key" -f ~/.ssh/id_ed25519
```

公開鍵の中身をコピーしておく。

$ cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... alice@fastapi deploy key

GitHub リポジトリの Settings → Deploy keys → Add deploy key を開いて、コピーした公開鍵を貼る。 push もさせたいとき以外は Allow write access は off のままでいい。

リモート URL を HTTPS から SSH に切り替えて、接続を確認する。 ssh -T git@github.com で Hi <your-account>/my-fastapi-app! と返ってくれば、その鍵でリポジトリにアクセスできてる。

$ cd my-fastapi-app/

$ git remote -v
origin  https://github.com/<your-account>/my-fastapi-app.git (fetch)
origin  https://github.com/<your-account>/my-fastapi-app.git (push)

$ git remote set-url origin git@github.com:<your-account>/my-fastapi-app.git

$ ssh -T git@github.com
Hi <your-account>/my-fastapi-app! You've successfully authenticated, but GitHub does not provide shell access.

$ git remote -v
origin  git@github.com:<your-account>/my-fastapi-app.git (fetch)
origin  git@github.com:<your-account>/my-fastapi-app.git (push)

Secrets¶

デプロイにトークンなどの秘密情報が必要なら、リポジトリの Settings → Secrets and variables → Actions に登録して、ワークフローから ${{ secrets.NAME }} で参照する: cf. Using secrets in GitHub Actions

      - name: Deploy
        run: ./deploy.sh
        env:
          SOME_TOKEN: ${{ secrets.SOME_TOKEN }}