Home

Awesome

<p align="center"> <img alt="FTP Deploy Action - Continuous integration for everyone" src="images/ftp-deploy-logo-small.png"> </p>

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


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 :star: 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 NameRequiredExampleDefault ValueDescription
serverYesftp.samkirkland.comDeployment destination server
usernameYesusername@samkirkland.comFTP user name
passwordYesCrazyUniquePassword&%123FTP password, be sure to escape quotes and spaces
portNo99021Server port to connect to (read your web hosts docs)
protocolNoftpsftpftp: provides no encryption, ftps: full encryption newest standard (aka "explicit" ftps), ftps-legacy: full encryption legacy standard (aka "implicit" ftps)
local-dirNo./myFolderToPublish/./Folder to upload from, must end with trailing slash /
server-dirNopublic_html/www/./Folder to upload to (on the server), must end with trailing slash /
state-nameNofolder/.sync-state.json.ftp-deploy-sync-state.jsonPath and name of the state file - this file is used to track which files have been deployed
dry-runNotruefalsePrints which modifications will be made with current config options, but doesn't actually make any changes
dangerous-clean-slateNotruefalseDeletes ALL contents of server-dir, even items in excluded with 'exclude' argument
excludeNoSee ExampleSee ExampleAn 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-levelNominimalstandardminimal: only important info, standard: important info and basic file changes, verbose: print everything the script is doing
securityNostrictloosestrict: Reject any connection which is not authorized with the list of supplied CAs. loose: Allow connection even when the domain is not certificate
timeoutNo6000030000Timeout 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 :star: or show off with one of the badges below. Feel free to edit the text or color.

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

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

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

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

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

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

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

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

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

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

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

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

<details> <summary>How to exclude .git files from the publish</summary>

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

</details> <details> <summary>How to exclude a specific file or folder</summary>

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
</details> <details> <summary>How do I set a upload timeout?</summary>

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:
      ....
</details>

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.