easingthemes-ssh-deploy/README.md

150 lines
4.1 KiB
Markdown
Raw Normal View History

2019-09-26 05:24:25 +08:00
# ssh deployments
2019-02-09 21:17:45 +08:00
Deploy code with rsync over ssh.
Execute remote scripts before or after rsync
2019-10-03 06:51:32 +08:00
NodeJS version is more than a minute `faster` than simple Docker version.
This GitHub Action deploys specific directory from `GITHUB_WORKSPACE` to a folder on a server via rsync over ssh, using NodeJS.
2019-02-09 21:17:45 +08:00
2019-09-26 05:24:25 +08:00
This action would usually follow a build/test action which leaves deployable code in `GITHUB_WORKSPACE`, eg `dist`;
2019-02-09 21:17:45 +08:00
In addition to rsync, this action provides scripts execution on remote host before and/or after rsync.
2019-09-26 05:52:29 +08:00
# Configuration
2019-02-09 21:17:45 +08:00
2019-09-26 05:52:29 +08:00
Pass configuration with `env` vars
2019-02-09 21:17:45 +08:00
##### 1. `SSH_PRIVATE_KEY` [required]
2019-10-03 06:51:32 +08:00
Private key part of an SSH key pair.
2020-04-12 05:08:36 +08:00
The public key part should be added to the `authorized_keys` file on the server that receives the deployment.
More info for SSH keys: https://www.ssh.com/ssh/public-key-authentication
2020-06-07 04:36:28 +08:00
The keys should be generated using the PEM format. You can use this command
2020-04-11 22:33:22 +08:00
```
ssh-keygen -m PEM -t rsa -b 4096
```
2019-02-09 21:17:45 +08:00
##### 2. `REMOTE_HOST` [required]
2019-10-03 06:51:32 +08:00
eg: mydomain.com
##### 3. `REMOTE_USER` [required]
2019-10-03 06:17:19 +08:00
2019-10-03 06:51:32 +08:00
eg: myusername
##### 4. `REMOTE_PORT` (optional, default '22')
eg: '59184'
##### 5. `ARGS` (optional, default '-rltgoDzvO')
2019-10-03 06:51:32 +08:00
2019-09-26 05:52:29 +08:00
For any initial/required rsync flags, eg: `-avzr --delete`
2019-02-09 21:17:45 +08:00
##### 6. `SOURCE` (optional, default '')
2019-10-03 06:51:32 +08:00
2019-10-03 06:17:19 +08:00
The source directory, path relative to `$GITHUB_WORKSPACE` root, eg: `dist/`
2019-02-09 21:17:45 +08:00
##### 7. `TARGET` (optional, default '/home/REMOTE_USER/')
2019-10-03 06:51:32 +08:00
2019-10-03 06:17:19 +08:00
The target directory
2019-02-09 21:17:45 +08:00
2021-03-12 14:42:12 +08:00
##### 8. `EXCLUDE` (optional, default '')
path to exclude separated by `,`, ie: `/dist/, /node_modules/`
##### 9. `SCRIPT_BEFORE` (optional, default '')
Script to run on host machine before rsync. Single line or multiline commands.
Execution is preformed by storing commands in `.sh` file and executing it via `.bash` over `ssh`
##### 10. `SCRIPT_AFTER` (optional, default '')
Script to run on host machine after rsync.
Rsync output is stored in `$RSYNC_STDOUT` env variable.
2019-10-03 06:51:32 +08:00
# Usage
2019-09-26 05:24:25 +08:00
Use the latest version from Marketplace,eg: ssh-deploy@v2
or use the latest version from a branch, eg: ssh-deploy@main
2020-09-19 05:29:28 +08:00
2019-09-26 05:52:29 +08:00
```
2019-10-03 06:17:19 +08:00
- name: Deploy to Staging server
uses: easingthemes/ssh-deploy@main
2019-10-03 06:17:19 +08:00
env:
2022-10-28 10:16:02 +08:00
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
2019-10-03 06:51:32 +08:00
ARGS: "-rltgoDzvO"
2019-10-03 06:17:19 +08:00
SOURCE: "dist/"
REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
REMOTE_USER: ${{ secrets.REMOTE_USER }}
TARGET: ${{ secrets.REMOTE_TARGET }}
2021-03-12 14:42:12 +08:00
EXCLUDE: "/dist/, /node_modules/"
SCRIPT_BEFORE: |
whoami
ls -al
SCRIPT_AFTER: |
whoami
ls -al
echo $RSYNC_STDOUT
2019-09-26 05:52:29 +08:00
```
2019-02-09 21:17:45 +08:00
2019-10-03 06:17:19 +08:00
# Example usage in workflow
2019-02-09 21:17:45 +08:00
```
2019-09-26 05:52:29 +08:00
name: Node CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
2019-10-03 06:17:19 +08:00
- name: Install Node.js
2019-09-26 05:52:29 +08:00
uses: actions/setup-node@v1
with:
2019-10-03 06:17:19 +08:00
node-version: '10.x'
2019-09-26 05:52:29 +08:00
- name: Install npm dependencies
2019-10-03 06:17:19 +08:00
run: npm install
2019-09-26 05:52:29 +08:00
- name: Run build task
2019-10-03 06:17:19 +08:00
run: npm run build --if-present
- name: Deploy to Server
uses: easingthemes/ssh-deploy@main
2019-10-03 06:17:19 +08:00
env:
2022-10-28 10:16:02 +08:00
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
2019-10-03 06:17:19 +08:00
ARGS: "-rltgoDzvO --delete"
SOURCE: "dist/"
REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
REMOTE_USER: ${{ secrets.REMOTE_USER }}
TARGET: ${{ secrets.REMOTE_TARGET }}
2021-03-12 14:42:12 +08:00
EXCLUDE: "/dist/, /node_modules/"
2019-02-09 21:17:45 +08:00
```
2022-12-31 17:33:16 +08:00
## Issues
This is a GitHub Action wrapping `rsync` via `ssh`. Only issues with action functionality can be fixed here.
2022-12-31 22:20:15 +08:00
Almost 95% of the issues are related to wrong SSH connection or `rsync` params and permissions.
These issues are not related to the action itself.
2022-12-31 22:20:15 +08:00
- Check manually your ssh connection from your client before opening a bug report.
- Check `rsync` params for your use-case. Default params are not going to be enough wor everyone, it highly depends on your setup.
2022-12-31 22:20:15 +08:00
- Check manually your rsync command from your client before opening a bug report.
2022-12-31 17:33:16 +08:00
I've added e2e test for this action.
2022-12-31 22:20:15 +08:00
Real example is executed on every PR merge to `main`.
2022-12-31 17:33:16 +08:00
Check actions tab for example.
2022-12-31 22:13:32 +08:00
More info for SSH keys: https://www.ssh.com/ssh/public-key-authentication
2022-12-31 22:20:15 +08:00
2019-02-09 21:17:45 +08:00
## Disclaimer
2020-04-11 22:30:28 +08:00
Check your keys. Check your deployment paths. And use at your own risk.