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

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

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