EE Push

SSH Setup

SSH deployment connects directly to your remote server and runs Git and shell commands. This is ideal when your server doesn't have a CI/CD pipeline but does have SSH access and a Git repository.

Prerequisites

  • The phpseclib library must be installed via Composer:
    Terminal
    composer require phpseclib/phpseclib:~3.0
  • The remote server must have git installed
  • The remote path must be a Git repository with the remote configured
  • SSH access (key-based authentication recommended)

Configuration

FieldDescription
SSH HostHostname or IP address of the remote server. Required.
SSH PortSSH port number. Default: 22.
UsernameSSH username for authentication. Required.
AuthenticationChoose between Private Key (recommended) or Password.
Private KeyPaste your SSH private key. Stored encrypted in the database.
PasswordSSH password. Stored encrypted. Key-based auth is strongly recommended instead.
Remote PathAbsolute path to the site root on the remote server (e.g., /var/www/html).
Pre-deploy CommandsShell commands to run before Git pull, one per line.
Post-deploy CommandsShell commands to run after Git pull, one per line.

What Happens During SSH Deployment

  1. EE Push connects to the server via SSH using your credentials
  2. Runs any pre-deploy commands (e.g., enable maintenance mode, stop workers)
  3. Executes git fetch origin
  4. Checks out the specified branch: git checkout [branch]
  5. Pulls latest code: git pull origin [branch]
  6. Records the current commit SHA
  7. Runs any post-deploy commands (e.g., clear cache, run migrations)
  8. Closes the SSH connection

Example Pre/Post Commands

Pre-deploy commands
php artisan down
php artisan config:clear
Post-deploy commands
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan up

Security

All credentials (private keys and passwords) are encrypted using ExpressionEngine's built-in Encrypt service before being stored in the database. They are decrypted only at the moment of use during deployment.

We strongly recommend using SSH key-based authentication rather than passwords. Consider creating a dedicated deploy user with limited permissions on the remote server.

Troubleshooting

  • Connection refused — Check the host, port, and firewall rules
  • Authentication failed — Verify the username and key/password are correct
  • Permission denied on git pull — Ensure the SSH user has write access to the remote path
  • phpseclib not found — Run composer require phpseclib/phpseclib:~3.0