appleboy/scp-action

🚀 SCP for GitHub Actions

繁體中文 | 简体中文

GitHub Action for copying files and artifacts via SSH.

Note: Only supports Linux docker containers.

✨ Features

• ✅ 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

📦 Table of Contents

• 🚀 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

🚀 Quick Start

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

name: scp files
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Copy files via SSH
        uses: appleboy/scp-action@v1
        with:
          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

⚙️ Configuration

🔌 Connection Settings

📁 File Transfer Settings

🌐 Proxy Settings

🛡️ Best Practices & Security

• Prefer SSH key authentication over passwords for better security.
• Store all sensitive values (host, username, password, key) in GitHub Secrets.
• Regularly rotate 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.

🖥️ Cross-Platform Notes

🚩 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/...)
• Enable tar_dereference for symlink handling

💡 Usage Examples

🧩 Scenario Guide

• 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

Example 1: Basic SSH Password

- name: Copy file via SSH password
  uses: appleboy/scp-action@v1
  with:
    host: example.com
    username: foo
    password: bar
    port: 22
    source: "tests/a.txt,tests/b.txt"
    target: your_server_target_folder_path

Example 2: Multi-server

- name: Copy to multiple servers
  uses: appleboy/scp-action@v1
  with:
    host: "foo.com,bar.com"
    username: foo
    password: bar
    port: 22
    source: "tests/a.txt,tests/b.txt"
    target: your_server_target_folder_path

Example 3: Changed Files Only

- name: Get changed files
  id: changed-files
  uses: tj-actions/changed-files@v35
  with:
    since_last_remote_commit: true
    separator: ","

- name: Copy changed files to server
  uses: appleboy/scp-action@v1
  with:
    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

Example 4: Artifacts Integration

- uses: actions/upload-artifact@v4
  with:
    name: my-artifact
    path: world.txt

- uses: actions/download-artifact@v4
  with:
    name: my-artifact
    path: distfiles

- name: Copy artifact to server
  uses: appleboy/scp-action@v1
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    key: ${{ secrets.KEY }}
    port: ${{ secrets.PORT }}
    source: distfiles/*
    target: your_server_target_folder_path

Example 5: Windows Server

- name: Copy to Windows
  uses: appleboy/scp-action@v1
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    key: ${{ secrets.SSH_PRIVATE_KEY }}
    port: 22
    source: "your_source_path"
    target: "/c/path/to/target/"
    tar_dereference: true
    rm: true

🗝️ SSH Key Setup

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

   # RSA
   ssh-keygen -t rsa -b 4096 -C "[email protected]"
   # ED25519
   ssh-keygen -t ed25519 -a 200 -C "[email protected]"
   

2. Add Public Key to Server:

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

3. Copy Private Key Content to GitHub Secrets:

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

See SSH login without password for more details.

OpenSSH Note:
If you see ssh: 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.

🧰 Common Error Codes

🔄 Workflow Diagram

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

FAQ & Troubleshooting

• 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: Use tj-actions/changed-files to get changed files and pass to source.

• 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 enable tar_dereference.

📝 License

MIT License