Skip to content

ssh2-to-remote-action

Actions
An action to upload a local directory to a remote server via SSH2 SFTP
v1.0.17
Latest
By 2ue
Star (0)

Tags

 (2)
deploymentpublishing

SSH2 SFTP Upload Action

CI Coverage Status License: MIT

A robust GitHub Action for uploading a local directory to a remote server via SSH2 SFTP protocol. Built with TypeScript and comprehensive error handling.

English | 中文文档

✨ Features

  • 🚀 TypeScript - Type-safe with comprehensive error handling
  • 🔐 Multiple Auth Methods - Password, private key, or SSH agent authentication
  • 📁 Directory Upload - Upload entire directories with progress tracking
  • 💾 Backup Support - Optional remote directory backup before upload
  • 🔄 Retry Logic - Configurable connection retries with exponential backoff
  • 📊 Detailed Outputs - Track uploaded files count and operation status
  • ⚡ Concurrent Operations - Configurable promise limit for optimal performance
  • 🛡️ Security First - No secrets logged, secure connection handling

📦 Usage

Basic Usage

name: Deploy to Server
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Upload to Server
        uses: 2ue/ssh2-to-remote-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USERNAME }}
          password: ${{ secrets.SERVER_PASSWORD }}
          local_dir: './dist'
          remote_base_dir: '/var/www/html'

Advanced Usage with Private Key and Backup

      - name: Upload with Backup
        uses: 2ue/ssh2-to-remote-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          port: 2222
          username: ${{ secrets.SERVER_USERNAME }}
          privateKey: ${{ secrets.SSH_PRIVATE_KEY }}
          passphrase: ${{ secrets.SSH_PASSPHRASE }}
          local_dir: './build'
          remote_base_dir: '/home/user/app'
          remote_bak_path: '/home/user/backups'
          retries: 3
          retry_factor: 2
          readyTimeout: 30000
          debug: true

📋 Inputs

Required Inputs

Input Description Example
host Remote server hostname or IP example.com
username SSH username ubuntu
local_dir Local directory to upload ./dist
remote_base_dir Remote destination directory /var/www/html

Authentication (Choose One)

Input Description Example
password SSH password ${{ secrets.PASSWORD }}
privateKey SSH private key content ${{ secrets.SSH_KEY }}
agent Path to SSH agent socket /tmp/ssh-agent.sock

Optional Inputs

Input Description Default Example
port SSH port 22 2222
passphrase Private key passphrase ${{ secrets.PASSPHRASE }}
remote_bak_path Backup directory path /backups
forceIPv4 Force IPv4 connection false true
forceIPv6 Force IPv6 connection false true
readyTimeout SSH handshake timeout (ms) 20000 30000
strictVendor Strict server vendor check false true
debug Enable debug logging false true
retries Connection retry attempts 1 3
retry_factor Retry delay multiplier 2 1.5
retry_minTimeout Min retry delay (ms) 1000 2000
promiseLimit Concurrent operation limit 10 5

📤 Outputs

Output Description Example
uploaded_files Number of files uploaded 42
success Upload operation status true
error Error message if failed Connection timeout

🔒 Security Considerations

Secrets Management

Store sensitive information as GitHub repository secrets:

  1. Go to your repository → Settings → Secrets and variables → Actions
  2. Add the following secrets:
    • SERVER_HOST - Your server hostname
    • SERVER_USERNAME - SSH username
    • SERVER_PASSWORD - SSH password (if using password auth)
    • SSH_PRIVATE_KEY - SSH private key content (if using key auth)
    • SSH_PASSPHRASE - Private key passphrase (if needed)

SSH Key Authentication (Recommended)

For better security, use SSH key authentication:

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "github-actions@your-repo"

# Copy public key to server
ssh-copy-id -i ~/.ssh/id_rsa.pub user@server

# Add private key content to GitHub secrets as SSH_PRIVATE_KEY
cat ~/.ssh/id_rsa

🚀 Examples

Deploy React App

name: Deploy React App
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install and Build
        run: |
          npm ci
          npm run build
          
      - name: Deploy to Server
        uses: 2ue/ssh2-to-remote-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USERNAME }}
          privateKey: ${{ secrets.SSH_PRIVATE_KEY }}
          local_dir: './build'
          remote_base_dir: '/var/www/html'
          remote_bak_path: '/var/backups/www'
          
      - name: Check Deployment
        if: success()
        run: echo "✅ Deployed ${{ steps.deploy.outputs.uploaded_files }} files successfully!"

Multi-Environment Deployment

name: Multi-Environment Deploy
on:
  push:
    branches: [ main, staging ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        environment: 
          - name: staging
            branch: staging
            host: staging.example.com
            path: /var/www/staging
          - name: production
            branch: main
            host: example.com
            path: /var/www/html
            
    steps:
      - uses: actions/checkout@v4
        if: github.ref == format('refs/heads/{0}', matrix.environment.branch)
        
      - name: Deploy to ${{ matrix.environment.name }}
        if: github.ref == format('refs/heads/{0}', matrix.environment.branch)
        uses: 2ue/ssh2-to-remote-action@v1
        with:
          host: ${{ matrix.environment.host }}
          username: ${{ secrets.SERVER_USERNAME }}
          privateKey: ${{ secrets.SSH_PRIVATE_KEY }}
          local_dir: './dist'
          remote_base_dir: ${{ matrix.environment.path }}
          remote_bak_path: '/backups/${{ matrix.environment.name }}'
          retries: 3
          debug: true

🛠️ Development

Prerequisites

  • Node.js 20+
  • TypeScript
  • Jest for testing

Setup

# Clone repository
git clone https://github.com/2ue/ssh2-to-remote-action.git
cd ssh2-to-remote-action

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run all checks
npm run all

Project Structure

src/
├── config/          # Input validation and processing
├── ssh/             # SSH connection management
├── upload/          # File upload logic
├── types/           # TypeScript type definitions
├── main.ts          # Main action logic
└── index.ts         # Entry point

__tests__/           # Test files
dist/                # Compiled output

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Run the test suite: npm run all
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

📞 Support

Made with ❤️ for the GitHub Actions community

Contributors (3)

@2ue@dependabot@claude

Resources

ssh2-to-remote-action is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.

About

An action to upload a local directory to a remote server via SSH2 SFTP
v1.0.17
Latest
By 2ue

Tags

 (2)
deploymentpublishing

Contributors (3)

@2ue@dependabot@claude

Resources

ssh2-to-remote-action is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.