overwatcher

Overwatcher プロジェクトの管理

Overwatcher は、GitHub リポジトリにプッシュがあったとき、またはその CI ワークフローが成功したときに、VM 上に Docker Compose サービスをデプロイします。すべての API 操作には owctl を使用してください。API 呼び出しを独自に作成したり、エージェントトークンを扱ったりしないでください。

ルール

1. owctl がインストールされていない場合はインストールしてください。 インストーラーが失敗した場合は中止して、その旨を報告してください。依頼されない限り、ソースからビルドしないでください。

   curl -fsSL "${OVERWATCHER_URL:-https://overwatcher-web-production.up.railway.app}/cli.sh" | sh
   export PATH="$HOME/.local/bin:$PATH"
   

2. 既存の認証情報を使用してください。 owctl は OVERWATCHER_API_KEY または保存済みの owctl login を読み込みます。API キーがないと表示された場合は、ユーザーにターミナルで owctl login を実行するか、OVERWATCHER_API_KEY を設定するよう依頼してください（ユーザーメニュー → API キーで作成してください）。キーを表示したり、引数として渡したりしないでください。

3. コーディネーターを調べてください。 --json を使用し、エラーが発生したら中止してください。同じ名前のプロジェクトがすでにある場合は、新規作成せずにそれを再利用してください。

   owctl project list --json
   owctl agent list --json
   owctl project get <project> --json
   

4. ほかのことを尋ねる前に VM を調べてください。 SSH ターゲットだけを尋ね、ssh -G <target> でエイリアスを解決してから、プローブを実行してください（読み取り専用です。VM 上での zsh のグロブエラーを避けるため sh -s を使用します）。

   ssh -T -o BatchMode=yes <target> sh -s <<'EOF'
   echo "user: $(id -un)"
   sudo -n true 2>/dev/null && echo "sudo: passwordless" || echo "sudo: needs password"
   command -v systemctl >/dev/null && echo "systemd: ok" || echo "systemd: missing"
   command -v curl >/dev/null && echo "curl: ok" || echo "curl: missing"
   systemctl show -p LoadState -p ActiveState overwatcher-agent 2>/dev/null
   docker compose version 2>/dev/null || echo "compose v2: missing"
   docker compose ls --all 2>/dev/null || echo "docker: no access for $(id -un)"
   EOF
   

   /etc/overwatcher-agent.env はエージェントトークンが含まれているため、読み取らないでください。その後、まだ不明なことだけを、調査結果を伝えたうえで尋ねてください。

   • LoadState=loaded の場合、エージェントは存在します。agent list にある場合（name または remote_ip が一致するもの）、再インストールではなくバインドすることを提案してください。それ以外の場合はユーザーに確認してください。
   • Compose のパスとして docker compose ls の設定ファイルを提案してください。Docker にアクセスできない場合はパスを尋ねてください。インストーラーはユーザーを docker グループに追加します。
   • sudo、systemd、curl、または Compose v2 が不足している場合は、解消されるまで中止してください。

5. 確認済みの Compose パスを指定してプロジェクトを作成してください。 ファイルは VM 上にすでに存在している必要があります（ssh <target> test -r <path>）。

   owctl project create <project> --compose-file <path> --environment production --json
   

6. アプリのリポジトリからサービスを割り出してください。 各フィールドはデフォルト値ではなく、ソースから取得してください。image は Compose の image: 行から、workflow はイメージをプッシュする CI ファイルから、tag はプッシュされるタグから、root_directory はビルドの context から取得します（モノレポで / を指定しないでください）。既存のプロジェクトを参考にしてください。name は Compose のサービスキーと一致する必要があります。service set はリスト全体を置き換えるため、既存のサービスも残してください。

   owctl service set <project> -f - --json <<'EOF'
   services:
     - name: web
       repo: acme/my-app
       image: ghcr.io/acme/my-app-web
       tag: main
       branch: main
       root_directory: services/web
       workflow: build.yml
   EOF
   

   workflow がない場合、プッシュのたびにデプロイが実行され、古いイメージが取得される可能性があります。1 つのワークフローで複数のイメージをビルドする場合、実行のたびにすべてのイメージが再デプロイされます。ユーザーに伝えてください。

7. エージェントをバインドするか、インストールしてください。 バインドすると、エージェントは以前のプロジェクトから移され、プロジェクトの現在のエージェントと置き換わります。どちらの場合も、実行前に確認してください。

   owctl agent bind <agent-id> <project> --json
   owctl agent install --ssh <target> --project <project> --json
   

   インストールすると、root 管理の systemd サービスが設定されます。--yes を追加する前に、明示的な承認を得てください。失敗した場合、owctl はエージェントを失効させますが、VM 上にファイルが残る可能性があります。その旨を報告し、むやみに再試行しないでください。エージェントは SSH ユーザーとして実行されるため、プライベートイメージの場合はそのユーザーによるレジストリへのログインが必要です。

8. GitHub App のアクセスを確認してください。 アクセスがないと、CI は成功しても何もデプロイされません。owctl では確認できないため、gh を使用してください（read:user スコープが必要です。ない場合はユーザーに gh auth refresh -h github.com -s read:user を実行するよう依頼してください）。

   gh api user/installations --jq '.installations[] | select(.app_slug=="overwatcher-app") | {id, account: .account.login, repository_selection, events}'
   gh api user/installations/<id>/repositories --paginate --jq '.repositories[].full_name'
   

   リポジトリ所有者は、events に push（および使用する場合は workflow_run）を含むインストールを必要とします。repository_selection が selected の場合、そのリポジトリが一覧に含まれている必要があります。そうでない場合は、インストールの Configure → Repository access で設定するようユーザーに案内し、セットアップ完了と報告しないでください。GitHub は過去のイベントを再送信しません。アクセスが許可されたら、最新の CI 実行を再実行してください。

検証

1. owctl project get <project> --json：compose_file、enabled、各サービスのフィールドを確認してください。
2. owctl agent list --json：エージェントの project_id が一致し、status が connected であることを確認してください。
3. すべてのリポジトリで、ルール 8 の GitHub App チェックに合格していることを確認してください。
4. プロジェクト ID、エージェント名、サービスごとのトリガーを報告してください。これだけではデプロイの成功を証明できません。