FTP Deploy GitHub Action

Automate deploying websites and more with this GitHub action.

Usage Example (Your_Project/.github/workflows/main.yml)

on: push
name: Publish Website
jobs:
  FTP-Deploy-Action:
    name: FTP-Deploy-Action
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - name: FTP-Deploy-Action
      uses: SamKirkland/FTP-Deploy-Action@2.0.0
      env:
        FTP_SERVER: ftp.samkirkland.com
        FTP_USERNAME: myFtpUserName
        FTP_PASSWORD: ${{ secrets.FTP_PASSWORD }}
        ARGS: --delete
        # --delete arg will delete files on the server if you've deleted them in git

Select the repository you want to add the action to
Select the actions tab
Select Blank workflow file or Set up a workflow yourself, if you don't see these options manually create a yaml file Your_Project/.github/workflows/main.yml
Paste the above code into your file and save
Now you need to add a key to the secrets section in your project. To add a secret go to the Settings tab in your project then select Secrets. Add a new Secret for FTP_PASSWORD

Settings

Keys can be added directly to your .yml config file or referenced from your project Secrets storage.

To add a secret go to the Settings tab in your project then select Secrets. I recommend you store your FTP_PASSWORD as a secret.

Key Name	Required?	Example	Default	Description
`FTP_SERVER`	Yes	ftp.samkirkland.com	N/A	FTP server name (you may need to specify a port)
`FTP_USERNAME`	Yes	git-action@samkirkland.com	N/A	FTP account username
`FTP_PASSWORD`	Yes	CrazyUniquePassword&%123	N/A	FTP account password
`METHOD`	No	ftp	ftp	Protocol used to deploy (ftp or sftp)
`PORT`	No	21	ftp=21, sftp=22	The port used to connect to server
`LOCAL_DIR`	No	build	. (root project folder)	The local folder to copy, defaults to root project folder. Do NOT include slashes for folders.
`REMOTE_DIR`	No	serverFolder	. (root FTP folder)	The remote folder to copy to, deafults to root FTP folder (I recommend you configure this on your server side instead of here). Do NOT include slashes for folders.
`ARGS`	No	See `ARGS` section below	N/A	Custom lftp arguments, this field is passed through directly into the lftp script.

ARGS

Custom lftp arguments, this field is passed through directly into the lftp script. See lftp's website for all options. You can use as many arguments as you want, seperate them with a space

Below is an incomplete list of commonly used ARGS:

Argument	Description
`--verbose`	Outputs which files are being modified, useful for debugging
`--delete`	Delete files not present at the source
`--transfer-all`	Transfer all files, even seemingly the same as the target site
`--dry-run`	Ouputs files that will be modified without making any actual changes
`--include=File.txt`	Include matching files, you can add multiple `--include`
`--exclude=File.txt`	Exclude matching files, you can add multiple `--exclude`
`--include-glob=*.zip`	Include matching files, you can add multiple `--include-glob`
`--exclude-glob=*.zip`	Exclude matching files, you can add multiple `--exclude-glob`
`--delete-excluded`	Deletes any items you've marked as excluded if they exist on the server
`--no-empty-dirs`	Don't create empty directories
`--parallel=X`	Uploads X files at a time in parallel
`-L`	Upload symbolic links as files (FTP doesn't have a way of creating actual symbolic links)
`--ignore-time`	⚠ Temporary workaround to prevent all files being uploaded. See this issue.

Common Examples

Build and Publish React/Angular/Vue/Node Website

Make sure you have an npm script named 'build'. This config should work for most node built websites

on: push
name: Build and Publish Front End Framework Website
jobs:
  FTP-Deploy-Action:
    name: FTP-Deploy-Action
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    
    - name: Use Node.js 12.x
      uses: actions/setup-node@v1
      with:
        node-version: '12.x'
        
    - name: Build Project
      run: |
        npm install
        npm run build --if-present
        
    - name: List output files
      run: ls
      
    - name: FTP-Deploy-Action
      uses: SamKirkland/FTP-Deploy-Action@2.0.0
      env:
        FTP_SERVER: ftp.samkirkland.com
        FTP_USERNAME: myFTPUsername
        FTP_PASSWORD: ${{ secrets.FTP_PASSWORD }}
        LOCAL_DIR: build
        ARGS: --delete

SFTP Example

on: push
name: Publish Website over SFTP
jobs:
  FTP-Deploy-Action:
    name: FTP-Deploy-Action
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    
    - name: FTP-Deploy-Action
      uses: SamKirkland/FTP-Deploy-Action@2.0.0
      env:
        FTP_SERVER: ftp.samkirkland.com
        FTP_USERNAME: mySFTPUsername
        FTP_PASSWORD: ${{ secrets.FTP_PASSWORD }}
        METHOD: sftp
        PORT: 7280
        ARGS: --delete

Log only dry run: Use this mode for testing

Ouputs a list of files that will be created/modified to sync your source without making any actual changes

on: push
name: Publish Website Dry Run
jobs:
  FTP-Deploy-Action:
    name: FTP-Deploy-Action
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - name: FTP-Deploy-Action
      uses: SamKirkland/FTP-Deploy-Action@2.0.0
      env:
        FTP_SERVER: ftp.samkirkland.com
        FTP_USERNAME: myFTPUsername
        FTP_PASSWORD: ${{ secrets.FTP_PASSWORD }}
        ARGS: --delete --dry-run

Want another example? Let me know by creating a github issue

FAQ

rm: Access failed: 553 Prohibited file name: ./.ftpquota
- The .ftpquota file is created by some FTP Servers and cannot be modified by the user
- Fix: Add --exclude=.ftpquota to your ARGS
How to exclude .git files from the publish
- Fix: Add --exclude-glob=.git*/** --exclude-glob=.git** to your ARGS
- Note: If you've already published these files you will need to manually delete them on the server or add the --delete-excluded option to ARGS
- Note: This will exclude all folders and files that start with .git no matter the folder they're in

Deprecated main.workflow config (used for beta/legacy apps that haven't been migrated to .yaml workflows yet)

action "FTP-Deploy-Action" {
   uses = "SamKirkland/FTP-Deploy-Action@1.0.0"
   secrets = ["FTP_USERNAME", "FTP_PASSWORD", "FTP_SERVER"]
}

Debugging locally

Instructions for debugging on windows

Install docker for windows
Open powershell
Navigate to the repo folder
Run docker build --tag action .
(Optional) This step is only required when editing entrypoint.sh due to windows editors saving the file with windows line breaks instead of linux line breaks
- Download http://dos2unix.sourceforge.net/
- In another powershell window nagivate to the dos2unix folder /bin
- Run this command every time you modify entrypoint.sh .\dos2unix.exe "{FULL_PATH_TO_REPO\entrypoint.sh}"
Run docker run action

bondartrq/FTP-Deploy-Action