/FTP-Deploy-Action

Deploys a GitHub project to a FTP server using GitHub actions

Primary LanguageShellMIT LicenseMIT

FTP Deploy GitHub Action

Automate deploying websites and more with this GitHub action.

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
  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 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

  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/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
Instructions for debugging on linux
  • Please submit a PR for linux instructions :)

ToDo

  • More examples

Pull Requests Welcome!