Automate deploying websites and more with this GitHub action. It's free!
Place the following in Your_Project/.github/workflows/main.yml
on: push
name: Publish Website
jobs:
web-deploy:
name: π Deploy Website Every Commit
runs-on: ubuntu-latest
steps:
- name: π Get Latest Code
uses: actions/checkout@v3
- name: π Sync Files
uses: SamKirkland/web-deploy@v1
with:
target-server: example.com
remote-user: username
private-ssh-key: ${{ secrets.SSH_KEY }}
destination-path: ~/destinationFolder/
- You must have shell access to your server, please read you webite hosts documentation
- You CANNOT use a FTP account - they are not the same!
- If you don't have SSH access but have ftp access use FTP-Deploy-Action instead
- You will need to create a SSH user to deploy. Normally this is your cpanel or hosting providers username and password
- Most web hosts change the default port (22), check with your host for your port number
- Select the repository you want to add the action to
- Select the
Actions
tab - Select
Blank workflow file
orSet up a workflow yourself
, if you don't see these options manually create a yaml fileYour_Project/.github/workflows/main.yml
- Paste the example above into your yaml file and save
- Now you need to add a key to the
secrets
section in your project. To add asecret
go to theSettings
tab in your project then selectSecrets
. Add a newSecret
forprivate-ssh-key
- Update your yaml file 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 private-ssh-key
as a secret.
Key Name | Required? | Example | Default | Description |
---|---|---|---|---|
target-server |
Yes | example.com |
Destination server to deploy to | |
destination-path |
Yes | ~/folderOnServerThatAlreadyExists/ |
Path on the server to deploy to. Must already exist. | |
remote-user |
Yes | username |
SSH user to login as | |
private-ssh-key |
Yes | -----BEGIN RSA PRIVATE KEY----- ...... |
SSH Private key. Must be specified as a secret. | |
source-path |
No | ./myFolderToPublish/ |
./ |
Path to upload to on the server, must end with trailing slash / |
ssh-port |
No | 12345 |
22 |
SSH port to use. Most hosts change this from the default. This is NOT your websites port. |
rsync-options |
No | See rsync-options section below |
--archive --verbose --compress --human-readable --progress --delete-after --exclude=.git* --exclude=.git/ --exclude=README.md --exclude=readme.md --exclude=.gitignore |
Note: If customizing you should re-specify defaults (assuming you want them). Custom rsync arguments, this field is passed through directly into the rsync script. |
Custom arguments, this field is passed through directly into the rsync script. See rsync's manual 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:
Option | Description |
---|---|
--archive |
A quick way of saying you want recursion and want to preserve almost everything |
--dry-run |
Does not upload or delete anything, but tells you what it would upload/delete if this was a real deploy |
--stats |
Print verbose statistics on the file transfer, allowing you to tell how effective rsyncβs delta-transfer algorithm is for your data |
--links |
When symlinks are encountered, recreate the symlink on the destination |
--compress |
Compresses the file data as it is sent to the destination machine, which reduces the amount of data being transmitted |
--human-readable |
Output bytes in a more human-readable format (K, M, G) |
--itemize-changes |
itemized list of the changes that are being made to each file, including attribute changes |
--delete-after |
When you delete a file on github it will also be deleted on the server. Files are deleted at the end of a deployment to minimize downtime. |
--max-size '200K' |
Ignore syncing files over this limit. Value is a number followed by "K", "M", or "G" |
--exclude 'file.txt' |
Excludes file(s) from the deployment. Supports glob pattterns (ex: *.jpg ). You can have multiple excludes! |
--include 'file.txt' |
Includes file(s) even if it was excluded. Supports glob pattterns (ex: *.jpg ). You can have multiple includes! |
See rsync's manual for all options
Make sure you have an npm script named 'build'. This config should work for most node built websites.
on: push
name: Publish Website
jobs:
web-deploy:
name: π Deploy Website Every Commit
runs-on: ubuntu-latest
steps:
- name: π Get Latest Code
uses: actions/checkout@v3
- name: π¦ Install Packages
- uses: actions/setup-node@v3
with:
node-version: 18
cache: "npm"
- run: npm ci
- name: π¨ Build
run: npm run build
- name: π Sync Files
uses: SamKirkland/web-deploy@v1
with:
target-server: example.com
remote-user: username
private-ssh-key: ${{ secrets.SSH_KEY }}
destination-path: ~/destinationFolder/
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:
web-deploy:
name: π Deploy Website Every Commit
runs-on: ubuntu-latest
steps:
- name: π Get Latest Code
uses: actions/checkout@v3
- name: π Sync Files
uses: SamKirkland/web-deploy@v1
with:
target-server: example.com
remote-user: username
private-ssh-key: ${{ secrets.SSH_KEY }}
ssh-port: 22
destination-path: ~/destinationFolder/
rsync-options: --dry-run --archive --verbose --compress --delete-after --human-readable --exclude=.git* --exclude=.git/ --exclude=README.md --exclude=readme.md --exclude=.gitignore
Want another example? Let me know by creating a github issue
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.
[<img alt="Deployed with web deploy" src="https://img.shields.io/badge/Deployed With-web deploy-%3CCOLOR%3E?style=for-the-badge&color=0077b6">](https://github.com/SamKirkland/web-deploy)
[<img alt="Deployed with web deploy" src="https://img.shields.io/badge/Deployed With-web deploy-%3CCOLOR%3E?style=for-the-badge&color=2b9348">](https://github.com/SamKirkland/web-deploy)
[<img alt="Deployed with web deploy" src="https://img.shields.io/badge/Deployed With-web deploy-%3CCOLOR%3E?style=for-the-badge&color=d00000">](https://github.com/SamKirkland/web-deploy)
[<img alt="Website Deployed for Free with web deploy" src="https://img.shields.io/badge/Website deployed for free with-web deploy-%3CCOLOR%3E?style=for-the-badge&color=297FA9">](https://github.com/SamKirkland/web-deploy)
[<img alt="Website Deployed for Free with web deploy" src="https://img.shields.io/badge/Website deployed for free with-web deploy-%3CCOLOR%3E?style=for-the-badge&color=2b9348">](https://github.com/SamKirkland/web-deploy)
[<img alt="Website Deployed for Free with web deploy" src="https://img.shields.io/badge/Website deployed for free with-web deploy-%3CCOLOR%3E?style=for-the-badge&color=d00000">](https://github.com/SamKirkland/web-deploy)
How to exclude .git files from the publish
Git files are excluded by default
If have customized rsync-options
you will need to re-add the default exclude options using --exclude=.git* --exclude=.git/ --exclude=README.md --exclude=readme.md --exclude=.gitignore
How to exclude a specific file or folder
You can use rsync-options
and pass in as many --exclude
options as you want. By default this action excludes github files. If you choose to customize rsync-options
make sure you copy over the defaults.
Example excluding all .jpg
files:
rsync-options: --exclude "*.jpg"
Example excluding a specific folder:
rsync-options: --exclude "wp-content/themes/"
rsync not found. Please see https://github.com/SamKirkland/web-deploy#rsync-not-installed
This library uses rsync
to sync files. The script was not able to detect rsync
on the machine running the action.
If you are using runs-on: ubuntu-latest
you will always have rsync
.
If you are using windows-latest
, windows-XXXX
, macos-latest
, macos-12
or a self-hosted runner you will need to install rsync before the web-deploy
step.
This is pretty easy to do!
On windows
runners run your windows specific steps, then use a ubuntu-latest
step to deploy.
On self-hosted runners install rsync before the web-deploy
step.
runs-on: [self-hosted, linux, my-self-hosted-runner-label]
steps:
- name: Install rsync
run: |
sudo apt-get update
sudo apt-get install rsync
On macos
runners install rsync before the web-deploy
step.
runs-on: macos-latest
steps:
- name: Install rsync
run: |
brew update
brew install rsync
Read more about customizing runners
https://docs.github.com/en/actions/using-github-hosted-runners/customizing-github-hosted-runners