Skip to Content
リファレンスアクションSSH

SSH Action

SSH Actionを使用すると、リモートサーバーにSSH接続してコマンドを実行できます。デプロイメント、リモート監視、サーバー管理などの用途に最適です。

基本的な使用方法

- name: サーバー状況を確認
  uses: ssh
  with:
    host: "example.com"
    user: "deploy"
    password: "your_password"
    cmd: "uptime && df -h"
  test: res.code == 0

パラメータ

必須パラメータ

パラメータ型説明
hoststring接続先ホスト名またはIPアドレス
userstringSSHユーザー名
cmdstring実行するコマンド

認証パラメータ（いずれか必須）

パラメータ型説明
passwordstringパスワード認証
key_filestring秘密鍵ファイルのパス（~展開対応）
key_passphrasestring秘密鍵のパスフレーズ（暗号化された鍵の場合）

オプションパラメータ

パラメータ型デフォルト説明
portint22SSHポート番号
timeoutstring”30s”コマンド実行のタイムアウト
workdirstring-リモートでの作業ディレクトリ
strict_host_checkbooltrueHost Keyの厳密検証
known_hostsstring~/.ssh/known_hostsKnown Hostsファイルのパス

環境変数

env__プレフィックスで環境変数を設定できます：

with:
  env__NODE_ENV: production
  env__APP_VERSION: v1.2.3

戻り値

SSH Actionは以下の値を返します：

フィールド型説明
res.codeint終了コード（0 = 成功）
res.stdoutstring標準出力
res.stderrstring標準エラー出力
res.statusint実行ステータス（0 = 成功、1 = 失敗）

使用例

パスワード認証

- name: パスワード認証でログイン
  uses: ssh
  with:
    host: "server.example.com"
    port: 22
    user: "admin"
    password: "secure_password"
    cmd: "systemctl status nginx"
    timeout: "60s"
  test: res.code == 0

公開鍵認証

- name: SSH鍵でログイン
  uses: ssh
  with:
    host: "prod.example.com"
    user: "deploy"
    key_file: "~/.ssh/deploy_key"
    cmd: "git pull origin main && systemctl restart app"
    workdir: "/opt/myapp"
    timeout: "300s"
  test: res.code == 0

暗号化された秘密鍵

- name: パスフレーズ付き鍵でログイン
  uses: ssh
  with:
    host: "secure.example.com"
    user: "admin"
    key_file: "~/.ssh/id_rsa"
    key_passphrase: "key_passphrase"
    cmd: "docker ps"
  test: res.code == 0

環境変数を使用

- name: 環境変数付きでデプロイ
  uses: ssh
  with:
    host: "app.example.com"
    user: "deploy"
    key_file: "~/.ssh/deploy_key"
    cmd: |
      echo "Deploying version: $APP_VERSION"
      echo "Environment: $DEPLOY_ENV"
      ./deploy.sh
    env__APP_VERSION: "v2.1.0"
    env__DEPLOY_ENV: "production"
    workdir: "/opt/myapp"
    timeout: "600s"
  test: res.code == 0 && contains(res.stdout, "Deploy completed")

複数行コマンド

- name: システム情報収集
  uses: ssh
  with:
    host: "monitor.example.com"
    user: "admin"
    password: "admin_pass"
    cmd: |
      echo "=== System Information ==="
      uname -a
      echo "=== Disk Usage ==="
      df -h
      echo "=== Memory Usage ==="
      free -h
      echo "=== Process List ==="
      ps aux | head -10
    timeout: "120s"
  test: res.code == 0
  echo: "{{res.stdout}}"

エラーハンドリング

- name: サービス再起動（エラー処理付き）
  uses: ssh
  with:
    host: "app.example.com"
    user: "deploy"
    key_file: "~/.ssh/deploy_key"
    cmd: |
      if systemctl is-active --quiet myapp; then
        echo "Stopping service..."
        systemctl stop myapp
      fi
      echo "Starting service..."
      systemctl start myapp
      systemctl is-active myapp
    timeout: "180s"
  test: |
    res.code == 0 && 
    contains(res.stdout, "active") &&
    !contains(res.stderr, "failed")

セキュリティ設定

Host Key検証

- name: 厳密なHost Key検証
  uses: ssh
  with:
    host: "secure.example.com"
    user: "admin"
    key_file: "~/.ssh/id_rsa"
    cmd: "whoami"
    strict_host_check: true
    known_hosts: "~/.ssh/known_hosts"
  test: res.code == 0

Host Key検証を無効化（開発環境のみ推奨）

- name: 開発環境での接続
  uses: ssh
  with:
    host: "dev.example.com"
    user: "developer"
    password: "dev_password"
    cmd: "npm test"
    strict_host_check: false  # 開発環境でのみ使用
  test: res.code == 0

ベストプラクティス

1. 認証方法の選択

公開鍵認証を推奨：

# 推奨
key_file: "~/.ssh/deploy_key"
 
# 可能であれば避ける
password: "plain_password"

2. タイムアウトの設定

適切なタイムアウト値を設定：

# 短時間のコマンド
timeout: "30s"
 
# デプロイメントなど長時間の処理
timeout: "600s"

3. エラーハンドリング

test: |
  res.code == 0 && 
  !contains(res.stderr, "error") &&
  !contains(res.stderr, "failed")

4. ログの安全性

パスワードや秘密鍵の情報は自動的にログから除外されます。

5. 環境変数の活用

機密情報は環境変数を使用：

vars:
  ssh_password: "{{vars.SSH_PASSWORD}}"
  deploy_key: "{{vars.DEPLOY_KEY_PATH}}"
 
steps:
- uses: ssh
  with:
    password: "{{vars.ssh_password}}"
    key_file: "{{vars.deploy_key}}"

制限事項

SSH Configファイル非対応

移植性と再現性を重視するため、SSH Configファイル（~/.ssh/config）はサポートしていません。すべての接続パラメータはワークフロー内で明示的に定義する必要があります。

対話的コマンド

対話的な入力が必要なコマンドはサポートしていません。すべてのコマンドは非対話的に実行される必要があります。

トラブルシューティング

接続エラー

Host Key検証エラー:

# known_hosts を確認
known_hosts: "~/.ssh/known_hosts"
 
# または開発環境では無効化
strict_host_check: false

認証エラー:

# 鍵ファイルのパスとパーミッションを確認
key_file: "/home/user/.ssh/id_rsa"  # 絶対パス
# または
key_file: "~/.ssh/id_rsa"          # チルダ展開
 
# パスフレーズが必要な場合
key_passphrase: "your_passphrase"

タイムアウトエラー:

# より長いタイムアウトを設定
timeout: "300s"

連続実行時の問題

同じホストへの連続接続で問題が発生する場合は、適切な間隔を空ける：

- name: 最初の接続
  uses: ssh
  with:
    cmd: "command1"
  
- name: 少し待機
  uses: hello
  with:
    name: "wait"
  wait: 1s
  
- name: 次の接続
  uses: ssh
  with:
    cmd: "command2"

関連項目

更新日時
IMAPGRPC