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/[email protected]
      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

1. Select the repository you want to add the action to
2. Select the actions tab
3. 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
4. Paste the above code into your file and save
5. 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	[email protected]	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/[email protected]
      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/[email protected]
      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/[email protected]
      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

1. 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
2. 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/[email protected]"
   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

Instructions for debugging on linux

• Please submit a PR for linux instructions :)

ToDo

• More examples

Pull Requests Welcome!