Repository files navigation

繁體中文 |简体中文

GitHub Action for copying files and artifacts via SSH.

Note: Only supportsLinuxdocker containers.

• ✅ Copy files and artifacts to one or multiple remote servers via SSH
• ✅ Supports both SSH key and password authentication
• ✅ Full SSH Proxy (jump host) support
• ✅ Handles Linux ↔ Windows path conversion
• ✅ Integrates with GitHub Artifacts workflow
• ✅ Incremental and differential file transfer
• ✅ Rich configuration options for advanced use cases

• 🚀 SCP for GitHub Actions
  • ✨ Features
  • 📦 Table of Contents
  • 🚀 Quick Start
  • ⚙️ Configuration
    • 🔌 Connection Settings
    • 📁 File Transfer Settings
    • 🌐 Proxy Settings
  • 🛡️ Best Practices & Security
  • 🖥️ Cross-Platform Notes
  • 💡 Usage Examples
    • 🧩 Scenario Guide
      • Example 1: Basic SSH Password
      • Example 2: Multi-server
      • Example 3: Changed Files Only
      • Example 4: Artifacts Integration
      • Example 5: Windows Server
  • 🗝️ SSH Key Setup
  • 🧰 Common Error Codes
  • 🔄 Workflow Diagram
  • FAQ & Troubleshooting
  • 📝 License

Copy files and artifacts via SSH in your GitHub Actions workflow:

name:scp fileson:[push]jobs:build:runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v4      -name:Copy files via SSHuses:appleboy/scp-action@v1with:host:${{ secrets.HOST }}username:${{ secrets.USERNAME }}password:${{ secrets.PASSWORD }}port:${{ secrets.PORT }}source:"tests/a.txt,tests/b.txt"target:your_server_target_folder_path

• Prefer SSH key authentication over passwords for better security.
• Store all sensitive values (host, username, password, key) inGitHub Secrets.
• Regularlyrotate deployment keys (suggested every 90 days).
• Restrict write permissions on the target server directory.
• Enable host key fingerprint verification to prevent MITM attacks.
• Avoid using root as the SSH user.

🚩Important:
When copying to Windows servers:

• Install Git for Windows and set OpenSSH default shell to Git Bash
• Use Unix-style target paths (e.g.,/c/Users/...)
• Enabletar_dereference for symlink handling

• Basic file transfer →Example 1
• Multi-server deployment →Example 2
• Incremental/changed files only →Example 3
• Artifacts integration →Example 4
• Windows server setup →Example 5

-name:Copy file via SSH passworduses:appleboy/scp-action@v1with:host:example.comusername:foopassword:barport:22source:"tests/a.txt,tests/b.txt"target:your_server_target_folder_path

-name:Copy to multiple serversuses:appleboy/scp-action@v1with:host:"foo.com,bar.com"username:foopassword:barport:22source:"tests/a.txt,tests/b.txt"target:your_server_target_folder_path

-name:Get changed filesid:changed-filesuses:tj-actions/changed-files@v35with:since_last_remote_commit:trueseparator:","-name:Copy changed files to serveruses:appleboy/scp-action@v1with:host:${{ secrets.HOST }}username:${{ secrets.USERNAME }}key:${{ secrets.KEY }}port:${{ secrets.PORT }}source:${{ steps.changed-files.outputs.all_changed_files }}target:your_server_target_folder_path

-uses:actions/upload-artifact@v4with:name:my-artifactpath:world.txt-uses:actions/download-artifact@v4with:name:my-artifactpath:distfiles-name:Copy artifact to serveruses:appleboy/scp-action@v1with:host:${{ secrets.HOST }}username:${{ secrets.USERNAME }}key:${{ secrets.KEY }}port:${{ secrets.PORT }}source:distfiles/*target:your_server_target_folder_path

-name:Copy to Windowsuses:appleboy/scp-action@v1with:host:${{ secrets.HOST }}username:${{ secrets.USERNAME }}key:${{ secrets.SSH_PRIVATE_KEY }}port:22source:"your_source_path"target:"/c/path/to/target/"tar_dereference:truerm:true

1. Generate SSH Key (on your local machine):

   # RSAssh-keygen -t rsa -b 4096 -C"your_email@example.com"# ED25519ssh-keygen -t ed25519 -a 200 -C"your_email@example.com"

2. Add Public Key to Server:

   cat .ssh/id_rsa.pub| ssh user@host'cat >> .ssh/authorized_keys'# or for ed25519cat .ssh/id_ed25519.pub| ssh user@host'cat >> .ssh/authorized_keys'

3. Copy Private Key Content to GitHub Secrets:

   clip<~/.ssh/id_rsa# orclip<~/.ssh/id_ed25519

SeeSSH login without password for more details.

OpenSSH Note:
If you seessh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], ensure your key algorithm is supported.
On Ubuntu 20.04+, add to/etc/ssh/sshd_config or/etc/ssh/sshd_config.d/:

CASignatureAlgorithms +ssh-rsa

Or use ed25519 keys, which are accepted by default.

sequenceDiagram    participant G as GitHub Runner    participant S as Target Server    G->>S: Establish SSH connection    S-->>G: Authenticate credentials    G->>S: (Optional) Remove target directory    G->>G: Archive source files    G->>S: Transfer archive    S->>S: Extract and process files    S-->>G: Return result

• Q: Why does authentication fail?
  A: Check SSH key format, permissions, and that the key is added to the server.

• Q: How do I copy only changed files?
  A: Usetj-actions/changed-files to get changed files and pass tosource.

• Q: How to deploy to multiple servers?
  A: Use comma-separated host list:host: "foo.com,bar.com"

• Q: How to copy to Windows?
  A: Set up Git Bash, use Unix-style paths, and enabletar_dereference.

MIT License