Claude CodeをEC2 + GitHub ActionsでRunnerとして動かす手順まとめ

Last updated at 2026-03-10Posted at 2026-03-10

こちらの記事の内容を具体的な手順にまとめてみます。

この記事で作る構成

今回やることは次の 4 つです。

EC2 を 1 台作る
EC2 上で runner ユーザーを作り、そのユーザーで Claude Code に OAuth ログインする
同じ runner ユーザーで GitHub Actions の self-hosted runner を登録する
GitHub Actions から claude コマンドが見えることを確認する

重要なのは、次の 3 つを same user に揃えることです。

Claude Code にログインするユーザー
普段 Session Manager で作業するユーザー
self-hosted runner を動かすユーザー

ここがずれると、Claude OAuth の認証状態を GitHub Actions 側で再利用できません。

前提条件

必要なものは次の通りです。

AWS アカウント
Claude Max または Pro の契約
GitHub アカウント
GitHub の private repository
ローカル Mac
ローカルに aws CLI と Session Manager Plugin が入っていること

今回は SSH ではなく Session Manager 前提です。22/tcp を開けたり、My IP を Security Group に入れたりする運用はしません。

1. AWS 側の準備

1-1. IAM ロールを作る

まず EC2 から Session Manager で入れるように、IAM ロールを作ります。

IAM -> Roles -> Create role

設定は次の通りです。

Trusted entity type: AWS service
Use case: EC2
Permissions: AmazonSSMManagedInstanceCore

ロール名は何でもよいですが、例えば claude-oauth-ssm-role にしておくと分かりやすいです。

1-2. EC2 を作る

次に EC2 を作ります。

EC2 -> Instances -> Launch instances

設定値は次の通りです。

Name: claude-oauth-runner
AMI: Ubuntu Server 24.04 LTS
Instance type: t3.micro or t3.small
Key pair: Proceed without a key pair
VPC: default VPC
Subnet: public subnet
Auto-assign public IP: Enable
Security group: 新規作成
Inbound rules: 追加しない
Storage: 30 GiB gp3
IAM instance profile: claude-oauth-ssm-role

今回は Session Manager 前提なので、22/tcp は開けません。

1-3. Session Manager で入れることを確認する

EC2 の起動後、少し待ってから次を確認します。

EC2 -> Instances -> 対象インスタンス -> Connect -> Session Manager

Connect ボタンが押せるようになっていて、シェルが開けば OK です。

もしここで接続できない場合は、だいたい次のどれかです。

IAM ロールが付いていない
まだ起動直後で SSM Agent が上がり切っていない
ネットワーク側で outbound が塞がっている

2. EC2 上の初期セットアップ

2-1. `runner` ユーザーを作る

Session Manager で入れたら、まず runner ユーザーを作ります。

sudo adduser runner
sudo usermod -aG sudo runner
sudo su - runner
whoami

最後に runner と表示されれば OK です。以後の作業はすべてこのユーザーで進めます。

2-2. 必要なライブラリのインストール

git や claude CLI など必要なライブラリをインストールします。ここは、使いたいランタイムなど使用したいものを使ってください。

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg git tmux

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" \
  | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install -y nodejs

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  | sudo dd of=/etc/apt/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
  | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt-get update
sudo apt-get install -y gh

sudo npm install -g @anthropic-ai/claude-code

わたしは以下を入れました。

Node.js 20
Git
tmux
GitHub CLI
Claude Code CLI

2-3. インストール結果を確認する

node --version
git --version
tmux -V
gh --version
claude --version

全部バージョンが返れば OK です。

2-4. GitHub CLI で認証して、対象リポジトリを clone する

private repository を使う前提なので、先に GitHub CLI で認証します。

gh auth login -w
gh auth status

認証できたら、Actions を実行したい対象リポジトリを clone します。

git clone https://github.com/<owner>/<Actionsで実行したいリポジトリ>.git
cd <Actionsで実行したいリポジトリ>

ここは自分の repository 名に置き換えてください。

3. Claude OAuth を通す

ここが今回の本題です。

3-1. EC2 側で `claude` を起動する

runner ユーザーで次を実行します。

claude

すると認証用の URL が表示されます。ローカルのブラウザで開き、Claude アカウントでログインします。

3-2. 疎通確認

ログインが終わったら、EC2 側で次を実行します。

claude -p "1+1 を数値だけで答えてください。"

2 が返れば、Claude Code を API Key ではなく契約プラン認証で使える状態になっています。

4. same user で self-hosted runner を登録する

次に GitHub Actions からこの EC2 を使えるようにします。

4-1. GitHub で runner を追加する

GitHub の対象リポジトリで次を開きます。

Settings -> Actions -> Runners -> New self-hosted runner

ここで必ず Linux を選んでください。Ubuntu 上なので macOS ではありません。

4-2. EC2 上で runner を登録する

GitHub の画面に表示されたコマンドを、EC2 上の runner ユーザーで実行します。だいたいこんな流れです。

mkdir -p ~/actions-runner
cd ~/actions-runner
curl -o actions-runner-linux-x64-<version>.tar.gz -L <GitHubが表示するURL>
echo "<GitHubが表示するchecksum>  actions-runner-linux-x64-<version>.tar.gz" | shasum -a 256 -c
tar xzf ./actions-runner-linux-x64-<version>.tar.gz
./config.sh \
  --url https://github.com/<owner>/<Actionsで実行したいリポジトリ> \
  --token <GitHubが表示するtoken> \
  --labels self-hosted,linux,ec2,claude

注意点は次の 1 つです。

token は短命なので、古いものは使わない

5. `run.sh` ではなく `svc.sh` で常駐化する

runner の起動は、最初から service 化してしまう方が安定します。

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

成功すると、Active: active (running) のような表示になります。

./run.sh でも初回疎通の確認はできますが、日常運用にはあまり向きません。実際には svc.sh で systemd 管理にした方が安定していました。

6. GitHub Actions から動作確認する

ここでは、Ralph のような大きな workflow ではなく、まず「作った self-hosted runner が runner として生きているか」を確認します。

対象リポジトリに、次の workflow を作ります。

.github/workflows/runner-healthcheck.yml

name: Runner Healthcheck

on:
  workflow_dispatch:
  schedule:
    - cron: '0 * * * *'

jobs:
  healthcheck:
    runs-on:
      - self-hosted
      - linux
      - ec2
      - claude
    steps:
      - name: Basic checks
        run: |
          whoami
          pwd
          command -v node
          node --version
          command -v gh
          gh --version
          command -v claude
          claude --version

      - name: Verify Claude OAuth
        run: |
          claude -p "1+1 を数値だけで答えてください。"

この workflow の意図はかなり単純です。

schedule で定期的に runner が生きているかを見る
workflow_dispatch で手動実行もできるようにする
claude -p まで入れて、runner だけでなく Claude OAuth も見えているか確認する

GitHub 側で workflow を実行して、次を確認します。

whoami が runner になっている
node, gh, claude のバージョン確認が通る
claude -p "1+1..." が GitHub Actions 上でも通る

スクリーンショット候補:
GitHub Actions の job log。whoami と claude -p の成功が見える箇所を切り出すと分かりやすいです。

7. ハマりやすいポイント

1. `runner` ユーザーを揃えないと認証が見えない

一番重要です。

Claude Code にログインするユーザー
self-hosted runner を動かすユーザー

この 2 つは必ず同じにします。

2. `./run.sh` は一時確認用で、常駐運用には向かない

GitHub Actions のセットアップ手順では ./run.sh を実行する流れが出てきますが、これはその場で受け付けるための起動に近いです。

実運用では次の理由で svc.sh の方が扱いやすかったです。

Session が切れても runner を残せる
systemd で状態確認しやすい
再起動時の復旧がしやすい

初回だけ ./run.sh で試すのはありですが、常駐させるなら svc.sh を既定手順にした方がよいです。

3. `ANTHROPIC_API_KEY` が残っていると挙動がぶれる

OAuth 前提で試すなら、Repository Secret や Organization Secret に ANTHROPIC_API_KEY を混在させない方が安全です。

せっかく OAuth を確認したつもりでも、実際には API Key 側で通っていた、という切り分けしづらい状態になりやすいです。

8. 応用例: Ralph のような長時間ジョブにつなぐ

ここまでできれば、self-hosted runner を土台にして、より長い workflow も動かせます。

例えば次のような用途です。

Issue を起点に AI エージェントを動かす
PRD の更新を検知して長時間ジョブを回す
コードレビューや実装支援を GitHub 側で回す

まとめ

いかがでしたでしょうか。
Claude Max / Pro をすでに契約していて、GitHub を入口にクラウド側で AI エージェントを回したいなら、かなり現実的な方法だと思います。
ぜひ、活用してみてください！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up