feat: initial release — Setup SSH Client GitHub Action\n\nInitial implementation of the action to configure an SSH client and an optional remote shell wrapper.\n- Creates ~/.ssh, adds identity and known_hosts\n- Adds ssh config for 'github-action-host'\n- Optional SSH remote shell wrapper using mktemp\n- Fails when strict-host-key-checking is 'yes' and no hosts are provided\n\nThis is the initial creation of the action.,
This commit is contained in:
commit
a5027e414c
5 changed files with 518 additions and 0 deletions
254
README.md
Normal file
254
README.md
Normal file
|
|
@ -0,0 +1,254 @@
|
|||
# Setup SSH Client
|
||||
|
||||
A composite GitHub Action that configures SSH client for running remote commands securely.
|
||||
|
||||
## Features
|
||||
|
||||
- 🔐 Secure SSH key management
|
||||
- 🔧 Automatic SSH configuration
|
||||
- 🔑 Known hosts setup with ssh-keyscan fallback
|
||||
- ✅ Connection validation
|
||||
- 🎯 Simple, reusable configuration
|
||||
- 🚀 Custom shell wrapper for seamless remote command execution
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example with Custom Shell
|
||||
|
||||
```yaml
|
||||
name: Deploy Application
|
||||
on: [push]
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup SSH
|
||||
uses: your-username/setup-ssh-client@v1
|
||||
with:
|
||||
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
|
||||
ssh-host: ${{ secrets.SSH_HOST }}
|
||||
ssh-user: ${{ secrets.SSH_USER }}
|
||||
|
||||
- name: Run remote commands with custom shell
|
||||
shell: ssh-remote
|
||||
run: |
|
||||
cd /var/www
|
||||
git pull origin main
|
||||
npm install
|
||||
systemctl restart myapp
|
||||
|
||||
- name: Or use direct SSH commands
|
||||
run: |
|
||||
ssh github-action-host "uptime"
|
||||
ssh github-action-host "df -h"
|
||||
```
|
||||
|
||||
### Basic Example (Direct SSH)
|
||||
|
||||
```yaml
|
||||
name: Deploy Application
|
||||
on: [push]
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup SSH
|
||||
uses: your-username/setup-ssh-client@v1
|
||||
with:
|
||||
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
|
||||
ssh-host: ${{ secrets.SSH_HOST }}
|
||||
ssh-user: ${{ secrets.SSH_USER }}
|
||||
|
||||
- name: Run remote commands
|
||||
run: |
|
||||
ssh github-action-host "cd /var/www && git pull"
|
||||
ssh github-action-host "systemctl restart myapp"
|
||||
```
|
||||
|
||||
### Advanced Example
|
||||
|
||||
```yaml
|
||||
- name: Setup SSH with custom configuration
|
||||
uses: your-username/setup-ssh-client@v1
|
||||
with:
|
||||
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
|
||||
ssh-host: example.com
|
||||
ssh-user: deploy
|
||||
ssh-port: '2222'
|
||||
strict-host-key-checking: 'yes'
|
||||
ssh-known-hosts: |
|
||||
example.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...
|
||||
|
||||
- name: Deploy application
|
||||
run: |
|
||||
ssh github-action-host "cd /var/www/app && ./deploy.sh"
|
||||
```
|
||||
|
||||
### Using Different Remote Shells
|
||||
|
||||
```yaml
|
||||
- name: Setup SSH with zsh
|
||||
uses: your-username/setup-ssh-client@v1
|
||||
with:
|
||||
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
|
||||
ssh-host: example.com
|
||||
ssh-user: deploy
|
||||
remote-shell: 'zsh'
|
||||
|
||||
- name: Run commands in remote zsh
|
||||
shell: ssh-remote
|
||||
run: |
|
||||
source ~/.zshrc
|
||||
echo "Running in zsh: $SHELL"
|
||||
```
|
||||
|
||||
### Disable Shell Wrapper (SSH Direct Only)
|
||||
|
||||
```yaml
|
||||
- name: Setup SSH without shell wrapper
|
||||
uses: your-username/setup-ssh-client@v1
|
||||
with:
|
||||
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
|
||||
ssh-host: example.com
|
||||
ssh-user: deploy
|
||||
use-shell-wrapper: 'false'
|
||||
|
||||
- name: Use direct SSH commands
|
||||
run: |
|
||||
ssh github-action-host "command1"
|
||||
ssh github-action-host "command2"
|
||||
```
|
||||
|
||||
## Inputs
|
||||
|
||||
| Input | Description | Required | Default |
|
||||
|-------|-------------|----------|---------|
|
||||
| `ssh-private-key` | SSH private key for authentication | Yes | - |
|
||||
| `ssh-host` | SSH host to connect to | Yes | - |
|
||||
| `ssh-user` | SSH username | Yes | - |
|
||||
| `ssh-port` | SSH port | No | `22` |
|
||||
| `ssh-known-hosts` | Known hosts content (uses ssh-keyscan if not provided) | No | `''` |
|
||||
| `strict-host-key-checking` | Enable strict host key checking (`yes`/`no`/`accept-new`) | No | `accept-new` |
|
||||
| `use-shell-wrapper` | Create shell wrapper for remote execution (enables `shell: ssh-remote`) | No | `true` |
|
||||
| `remote-shell` | Shell to use on remote server (`bash`, `sh`, `zsh`, etc.) | No | `bash` |
|
||||
|
||||
## Outputs
|
||||
|
||||
| Output | Description |
|
||||
|--------|-------------|
|
||||
| `ssh-config-path` | Path to the SSH config file |
|
||||
| `ssh-key-path` | Path to the SSH private key |
|
||||
| `shell-wrapper-path` | Path to the SSH remote shell wrapper script |
|
||||
|
||||
## Remote Command Execution
|
||||
|
||||
This action provides two ways to execute commands remotely:
|
||||
|
||||
### 1. Custom Shell Wrapper (Recommended)
|
||||
|
||||
Use `shell: ssh-remote` in any step to execute the entire script on the remote server:
|
||||
|
||||
```yaml
|
||||
- name: Deploy application
|
||||
shell: ssh-remote
|
||||
run: |
|
||||
cd /var/www/myapp
|
||||
git pull origin main
|
||||
npm install --production
|
||||
pm2 restart myapp
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Natural multi-line script syntax
|
||||
- Automatic error handling with `set -e`
|
||||
- Works like a local shell
|
||||
- No need to wrap commands in SSH
|
||||
|
||||
### 2. SSH Host Alias (Direct)
|
||||
|
||||
Use the `github-action-host` alias for direct SSH commands:
|
||||
|
||||
```yaml
|
||||
- name: Run single commands
|
||||
run: |
|
||||
ssh github-action-host "uptime"
|
||||
ssh github-action-host "df -h"
|
||||
```
|
||||
|
||||
This eliminates the need to specify the host, user, port, and key path in every SSH command.
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Generating SSH Keys
|
||||
|
||||
```bash
|
||||
# Generate a dedicated SSH key pair for GitHub Actions
|
||||
ssh-keygen -t ed25519 -C "github-actions" -f github_actions_key
|
||||
|
||||
# Or use RSA if ed25519 is not supported
|
||||
ssh-keygen -t rsa -b 4096 -C "github-actions" -f github_actions_key
|
||||
```
|
||||
|
||||
### Setting up Secrets
|
||||
|
||||
1. Copy your private key content:
|
||||
```bash
|
||||
cat github_actions_key
|
||||
```
|
||||
|
||||
2. Add it to GitHub Secrets:
|
||||
- Go to your repository → Settings → Secrets and variables → Actions
|
||||
- Click "New repository secret"
|
||||
- Name: `SSH_PRIVATE_KEY`
|
||||
- Value: Paste the entire private key content
|
||||
|
||||
3. Add the public key to your server:
|
||||
```bash
|
||||
cat github_actions_key.pub >> ~/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
### Getting Known Hosts
|
||||
|
||||
To pre-populate known hosts (recommended for security):
|
||||
|
||||
```bash
|
||||
ssh-keyscan -H your-server.com
|
||||
```
|
||||
|
||||
Add the output to a GitHub secret named `SSH_KNOWN_HOSTS`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Timeout
|
||||
|
||||
If the connection test fails with a timeout:
|
||||
- Verify the host and port are correct
|
||||
- Check firewall rules allow connections from GitHub Actions IPs
|
||||
- Ensure SSH service is running on the remote server
|
||||
|
||||
### Permission Denied
|
||||
|
||||
If you get "Permission denied":
|
||||
- Verify the public key is in `~/.ssh/authorized_keys` on the remote server
|
||||
- Check the private key format is correct (should include header/footer)
|
||||
- Ensure the SSH user has appropriate permissions
|
||||
|
||||
### Host Key Verification Failed
|
||||
|
||||
If you encounter host key verification issues:
|
||||
- Set `strict-host-key-checking: 'no'` (not recommended for production)
|
||||
- Or provide `ssh-known-hosts` input with the correct host key
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) file for details
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
Loading…
Add table
Add a link
Reference in a new issue