Skip to content

SamKirkland/FTP-Deploy-Action

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

FTP Deploy Action - Continuous integration for everyone

Automate deploying websites and more with this GitHub action. It's free!

FTP test FTPS test


Usage Example

Place the following in /.github/workflows/main.yml

on: push
name: πŸš€ Deploy website on push
jobs:
  web-deploy:
    name: πŸŽ‰ Deploy
    runs-on: ubuntu-latest
    steps:
    - name: 🚚 Get latest code
      uses: actions/checkout@v4
    
    - name: πŸ“‚ Sync files
      uses: SamKirkland/FTP-Deploy-Action@v4.3.5
      with:
        server: ftp.samkirkland.com
        username: myFtpUserName
        password: ${{ secrets.ftp_password }}

Requirements

  • You must have ftp access to your server. If your host allows or requires ssh please use my web-deploy action
  • Some web hosts change the default port (21), check with your host for your port number

Setup Steps

  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 example above into your yaml 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 password
  6. Update your yaml file settings
  7. If you appreciate this github action give it a ⭐ or show off with one of the badges below.

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 strongly recommend you store your password as a secret.

Key Name Required Example Default Value Description
server Yes ftp.samkirkland.com Deployment destination server
username Yes username@samkirkland.com FTP user name
password Yes CrazyUniquePassword&%123 FTP password, be sure to escape quotes and spaces
port No 990 21 Server port to connect to (read your web hosts docs)
protocol No ftps ftp ftp: provides no encryption, ftps: full encryption newest standard (aka "explicit" ftps), ftps-legacy: full encryption legacy standard (aka "implicit" ftps)
local-dir No ./myFolderToPublish/ ./ Folder to upload from, must end with trailing slash /
server-dir No public_html/www/ ./ Folder to upload to (on the server), must end with trailing slash /
state-name No folder/.sync-state.json .ftp-deploy-sync-state.json Path and name of the state file - this file is used to track which files have been deployed
dry-run No true false Prints which modifications will be made with current config options, but doesn't actually make any changes
dangerous-clean-slate No true false Deletes ALL contents of server-dir, even items in excluded with 'exclude' argument
exclude No See Example See Example An array of glob patterns, these files will not be included in the publish/delete process. List MUST be in this format. You can use a glob tester to test your pattern(s).
log-level No minimal standard minimal: only important info, standard: important info and basic file changes, verbose: print everything the script is doing
security No strict loose strict: Reject any connection which is not authorized with the list of supplied CAs. loose: Allow connection even when the domain is not certificate
timeout No 60000 30000 Timeout in milliseconds for FTP operations

Common Examples

Build and Publish React/Angular/Vue Website

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

on: push
name: πŸš€ Deploy website on push
jobs:
  web-deploy:
    name: πŸŽ‰ Deploy
    runs-on: ubuntu-latest
    steps:
    - name: 🚚 Get latest code
      uses: actions/checkout@v4

    - name: Use Node.js 16
      uses: actions/setup-node@v2
      with:
        node-version: '16'
      
    - name: πŸ”¨ Build Project
      run: |
        npm install
        npm run build
    
    - name: πŸ“‚ Sync files
      uses: SamKirkland/FTP-Deploy-Action@v4.3.5
      with:
        server: ftp.samkirkland.com
        username: myFtpUserName
        password: ${{ secrets.password }}

FTPS

on: push
name: πŸš€ Deploy website on push
jobs:
  web-deploy:
    name: πŸŽ‰ Deploy
    runs-on: ubuntu-latest
    steps:
    - name: 🚚 Get latest code
      uses: actions/checkout@v4

    - name: πŸ“‚ Sync files
      uses: SamKirkland/FTP-Deploy-Action@v4.3.5
      with:
        server: ftp.samkirkland.com
        username: myFtpUserName
        password: ${{ secrets.password }}
        protocol: ftps
        port: 1234 # todo replace with your web hosts ftps port

Log only dry run: Use this option for testing

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

on: push
name: πŸš€ Deploy website on push
jobs:
  web-deploy:
    name: πŸŽ‰ Deploy
    runs-on: ubuntu-latest
    steps:
    - name: 🚚 Get latest code
      uses: actions/checkout@v4

    - name: πŸ“‚ Sync files
      uses: SamKirkland/FTP-Deploy-Action@v4.3.5
      with:
        server: ftp.samkirkland.com
        username: myFtpUserName
        password: ${{ secrets.password }}
        dry-run: true

Exclude files

Excludes files

on: push
name: πŸš€ Deploy website on push
jobs:
  web-deploy:
    name: πŸŽ‰ Deploy
    runs-on: ubuntu-latest
    steps:
    - name: 🚚 Get latest code
      uses: actions/checkout@v4

    - name: πŸ“‚ Sync files
      uses: SamKirkland/FTP-Deploy-Action@v4.3.5
      with:
        server: ftp.samkirkland.com
        username: myFtpUserName
        password: ${{ secrets.password }}
        exclude: |
          **/.git*
          **/.git*/**
          **/node_modules/**
          fileToExclude.txt

exclude has the following default value

exclude: |
  **/.git*
  **/.git*/**
  **/node_modules/**

if you overwrite the default value you will probably want to respecify them


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


Badge

If you appreciate this github action give it a ⭐ or show off with one of the badges below. Feel free to edit the text or color.

Deployed with FTP Deploy Action

[<img alt="Deployed with FTP Deploy Action" src="https://img.shields.io/badge/Deployed With-FTP DEPLOY ACTION-%3CCOLOR%3E?style=for-the-badge&color=0077b6">](https://github.com/SamKirkland/FTP-Deploy-Action)

Deployed with FTP Deploy Action

[<img alt="Deployed with FTP Deploy Action" src="https://img.shields.io/badge/Deployed With-FTP DEPLOY ACTION-%3CCOLOR%3E?style=for-the-badge&color=2b9348">](https://github.com/SamKirkland/FTP-Deploy-Action)

Deployed with FTP Deploy Action

[<img alt="Deployed with FTP Deploy Action" src="https://img.shields.io/badge/Deployed With-FTP DEPLOY ACTION-%3CCOLOR%3E?style=for-the-badge&color=d00000">](https://github.com/SamKirkland/FTP-Deploy-Action)

Website Deployed for Free with FTP Deploy Action

[<img alt="Website Deployed for Free with FTP Deploy Action" src="https://img.shields.io/badge/Website deployed for free with-FTP DEPLOY ACTION-%3CCOLOR%3E?style=for-the-badge&color=297FA9">](https://github.com/SamKirkland/FTP-Deploy-Action)

Website Deployed for Free with FTP Deploy Action

[<img alt="Website Deployed for Free with FTP Deploy Action" src="https://img.shields.io/badge/Website deployed for free with-FTP DEPLOY ACTION-%3CCOLOR%3E?style=for-the-badge&color=2b9348">](https://github.com/SamKirkland/FTP-Deploy-Action)

Website Deployed for Free with FTP Deploy Action

[<img alt="Website Deployed for Free with FTP Deploy Action" src="https://img.shields.io/badge/Website deployed for free with-FTP DEPLOY ACTION-%3CCOLOR%3E?style=for-the-badge&color=d00000">](https://github.com/SamKirkland/FTP-Deploy-Action)

FAQ

How to exclude .git files from the publish

Git files are excluded by default! If you customize the exclude option make sure you re-add the default options.

How to exclude a specific file or folder

You can use the exclude option to ignore specific files/folders from the publish. Keep in mind you will need to re-add the default exclude options if you want to keep them. For example the below option excludes all .txt files.

exclude:
 - *.txt
How do I set a upload timeout?

github has a built-in timeout-minutes option, see customized example below

on: push
name: Publish Website
jobs:
  web-deploy:
    name: web-deploy
    runs-on: ubuntu-latest
    timeout-minutes: 15 # time out after 15 minutes (default is 360 minutes)
    steps:
      ....

Debugging your config locally

This action is a basic wrapper around my @samkirkland/ftp-deploy npm package. To test your config you can install @samkirkland/ftp-deploy and then convert your config to a yml action. Settings are one-to-one, this action is only a wrapper.

Contributing to this project

To test this action locally you will need to setup docker and act to run a environment similar to the one github uses for actions.

  • Download/install docker for windows, make sure it is running
  • choco install act-cli install act
  • Install the npm package using npm install --dev-only @samkirkland/ftp-deploy
  • Update the deploy script in package.json with a actual server/username/password
  • You can run the script using the following command npm run deploy (run this in the folder that has the package.json file)