actions-file-deployer/README.md

# FTP/SFTP file deployer

This is a fork of https://github.com/milanmk/actions-file-deployer with gitea customisation. 

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 Gitea Action (Linux runner) for deploying repository content to a 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](https://en.wikipedia.org/wiki/SOCKS) using [SSH tunneling](https://www.ssh.com/academy/ssh/tunneling) to bypass firewall / NAT / IP whitelist / VPC
- Uses [composite action](https://docs.github.com/en/actions/creating-actions/about-actions#types-of-actions) 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

```yml
- name: "Checkout"
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
- name: "Deploy"
  uses: https://code.klank.school/riviera/actions-file-deployer@v4
  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 `.gitea/workflows/main.yml`.

```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: https://code.klank.school/riviera/actions-file-deployer@v4
        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(!)| Publish secrets on the internet (true, false) |

### Notes

- Character support for `remote-user` and `remote-password` is limited due to its usage in [.netrc file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html)
  - 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](https://docs.github.com/en/actions/reference/events-that-trigger-workflows)
    - Requires `fetch-depth: 0` option in [checkout action](https://gitea.com/actions/checkout)
    - 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](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec) patterns to exclude files from delta sync.
- For `ftp-options` and `ftp-mirror-options` command arguments please refer to [LFTP manual](https://lftp.yar.ru/lftp-man.html)
- `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/main",
    "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/main",
    "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
- It is strongly recommended to use [Encrypted Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets) to store sensitive data like passwords and private keys
- It is strongly recommended not to use the `debug` option because it will output your encrypted secrets in the Action logs.

## Planned features
- [ ] Stop the debug option from publishing encrypted secrets
- [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