FTP/SFTP file deployer

Fast and customizable deployment with parallel connections and proxy support. Deploy only changed files or do full sync/mirror of repository content.

This is a composite GitHub Action (Linux runner) for deploying repository content to remote server.

Features

Support for FTP and SFTP (SSH) protocols
Use password or SSH private key for authentication of SFTP connection
Delta file synchronization for faster deployment of only changed files since last revision
Mirroring feature to copy entire file and folder structure of repository content
Optimized for faster file transfers via parallel connections
Connect to remote server via SOCKS proxy using SSH tunneling to bypass firewall / NAT / IP whitelist / VPC
Uses composite action without Docker container for faster deployments and shorter run time
Pass additional command arguments to SSH and FTP client for custom configurations and settings
Step runs messages categorized nicely in log groups
Run additional FTP commands after synchronization

Usage

- name: "Checkout"
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
- name: "Deploy"
  uses: milanmk/actions-file-deployer@master
  with:
    remote-protocol: "sftp"
    remote-host: "ftp.example.com"
    remote-user: "username"
    ssh-private-key: ${{ secrets.DEPLOY_PRIVATE_KEY }}
    remote-path: "/var/www/example.com"

Workflow example .github/workflows/main.yml.

name: Deploy Files

on:
  push:
    branches:
      - master
  # Enables manually triggering of Workflow with file synchronization option
  workflow_dispatch:
    inputs:
      sync:
        description: "File synchronization"
        required: true
        default: "delta"

jobs:
  deploy-master:
    name: "master branch"
    if: ${{ github.ref == 'refs/heads/master' }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: "Checkout"
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: "Deploy"
        uses: milanmk/actions-file-deployer@master
        with:
          remote-protocol: "sftp"
          remote-host: "ftp.example.com"
          remote-user: "username"
          ssh-private-key: ${{ secrets.DEPLOY_PRIVATE_KEY }}
          remote-path: "/var/www/example.com"

Inputs

Name	Required	Default	Description
remote-protocol	yes	sftp	Remote file transfer protocol (ftp, sftp)
remote-host	yes		Remote host
remote-port	yes	22	Remote port
remote-user	yes		FTP/SSH username
remote-password	no		FTP/SSH password
ssh-private-key	no		SSH private key of user
proxy	yes	false	Enable proxy for FTP connection (true, false)
proxy-host	yes (if proxy: true)		Proxy host
proxy-port	yes (if proxy: true)	22	Proxy port
proxy-forwarding-port	yes (if proxy: true)	1080	Proxy forwarding port
proxy-user	yes (if proxy: true)		Proxy username
proxy-private-key	yes (if proxy: true)		Proxy SSH private key of user
local-path	yes	.	Local path to repository
remote-path	yes	.	Remote path on host
sync	yes	delta	File synchronization (delta, full)
sync-delta-excludes	no		Files to exclude from delta sync
ssh-options	no		Additional arguments for SSH client
ftp-options	no		Additional arguments for FTP client
ftp-mirror-options	no		Additional arguments for mirroring
ftp-post-sync-commands	no		Additionnal FTP command to run after sync
webhook	no		Send webhook event notifications
artifacts	no	false	Upload logs/files to artifacts (true, false)
debug	no	false	Enable debug information (true, false)

Notes

Character support for remote-user and remote-password is limited due to its usage in .netrc file
- It should not contain shell/URL special characters
File synchronization options
- delta: Transfer only changed files (upload and delete) since last revision
  - Only supported for push, pull_request and workflow_dispatch events
  - Requires fetch-depth: 0 option in checkout action
  - It is recommended to initially do a full synchronization and then switch to delta
- full: Transfer all files (upload)
  - Does not delete files on remote host
  - Default glob exclude pattern is .git*/
sync-delta-excludes accepts pathspec patterns to exclude files from delta sync.
For ftp-options and ftp-mirror-options command arguments please refer to LFTP manual
ftp-post-sync-commands can be used to run additional LFTP commands after the synchronization. For example, to upload a file watched by a process manager on the server in order to restart a deamon:
```
ftp-post-sync-commands: |
  !touch watched_file
  put watched_file
```

Setting webhook to a URL will send start and finish event notifications in JSON format

start event payload:

{
  "timestamp": "1234567890",
  "status": "start",
  "repository": "owner/repository",
  "workflow": "workflow name",
  "job": "deploy",
  "run_id": "1234567890",
  "ref": "refs/heads/master",
  "event_name": "push",
  "actor": "username",
  "message": "commit message",
  "revision": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
}

finish event payload:

{
  "timestamp": "1234567890",
  "status": "finish",
  "repository": "owner/repository",
  "workflow": "workflow name",
  "job": "deploy",
  "run_id": "1234567890",
  "ref": "refs/heads/master",
  "event_name": "push",
  "actor": "username",
  "message": "commit message",
  "revision": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
}

Enabling artifacts will upload transfer log and modified files to artifacts
- Modified files are only added for delta file synchronization
Enabling debug option will output useful context, inputs, configuration file contents and transfer logs to help debug each step
It is strongly recommended to use Encrypted Secrets to store sensitive data like passwords and private keys

Planned features

Add transfer log to artifacts
Add modified files to artifacts
Add steps logging to file
Add steps log to artifacts
Trigger webhook at start and end of step runs