From 70d518e3c90fbc170c1b51a09dcc2e61bbf4cce4 Mon Sep 17 00:00:00 2001 From: Fantarzero Date: Tue, 16 Sep 2025 12:58:08 +0700 Subject: [PATCH] Delete README.md --- README.md | 490 ------------------------------------------------------ 1 file changed, 490 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index f3f79a3..0000000 --- a/README.md +++ /dev/null @@ -1,490 +0,0 @@ -# 🚀 SSH for GitHub Actions - -English | [įšéĢ”中文](./README.zh-tw.md) | [įŽ€äŊ“中文](./README.zh-cn.md) - -## Table of Contents - -- [🚀 SSH for GitHub Actions](#-ssh-for-github-actions) - - [Table of Contents](#table-of-contents) - - [📖 Introduction](#-introduction) - - [🧩 Core Concepts \& Input Parameters](#-core-concepts--input-parameters) - - [🔌 Connection Settings](#-connection-settings) - - [🛠ī¸ SSH Command Settings](#ī¸-ssh-command-settings) - - [🌐 Proxy Settings](#-proxy-settings) - - [⚡ Quick Start](#-quick-start) - - [🔑 SSH Key Setup \& OpenSSH Compatibility](#-ssh-key-setup--openssh-compatibility) - - [Setting Up SSH Keys](#setting-up-ssh-keys) - - [Generate RSA key](#generate-rsa-key) - - [Generate ED25519 key](#generate-ed25519-key) - - [OpenSSH Compatibility](#openssh-compatibility) - - [🛠ī¸ Usage Scenarios \& Advanced Examples](#ī¸-usage-scenarios--advanced-examples) - - [Using password authentication](#using-password-authentication) - - [Using private key authentication](#using-private-key-authentication) - - [Multiple commands](#multiple-commands) - - [Run commands from a file](#run-commands-from-a-file) - - [Multiple hosts](#multiple-hosts) - - [Multiple hosts with different ports](#multiple-hosts-with-different-ports) - - [Synchronous execution on multiple hosts](#synchronous-execution-on-multiple-hosts) - - [Pass environment variables to shell script](#pass-environment-variables-to-shell-script) - - [🌐 Proxy \& Jump Host Usage](#-proxy--jump-host-usage) - - [🛡ī¸ Security Best Practices](#ī¸-security-best-practices) - - [Protecting Your Private Key](#protecting-your-private-key) - - [Host Fingerprint Verification](#host-fingerprint-verification) - - [🚨 Error Handling \& Troubleshooting](#-error-handling--troubleshooting) - - [Q\&A](#qa) - - [Command not found (npm or other command)](#command-not-found-npm-or-other-command) - - [🤝 Contributing](#-contributing) - - [📝 License](#-license) - ---- - -## 📖 Introduction - -**SSH for GitHub Actions** is a powerful [GitHub Action](https://github.com/features/actions) for executing remote SSH commands easily and securely in your CI/CD workflows. -Built with [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh), it supports a wide range of SSH scenarios, including multi-host, proxy, and advanced authentication. - -![ssh workflow](./images/ssh-workflow.png) - -[![testing main branch](https://github.com/appleboy/ssh-action/actions/workflows/main.yml/badge.svg)](https://github.com/appleboy/ssh-action/actions/workflows/main.yml) - ---- - -## 🧩 Core Concepts & Input Parameters - -This action provides flexible SSH command execution with a rich set of configuration options. - -For full details, see [action.yml](./action.yml). - -### 🔌 Connection Settings - -These parameters control how the action connects to your remote host. - -| Parameter | Description | Default | -| ------------------- | ----------------------------------------------------------------- | ------- | -| host | SSH host address | | -| port | SSH port number | 22 | -| username | SSH username | | -| password | SSH password | | -| protocol | SSH protocol version (`tcp`, `tcp4`, `tcp6`) | tcp | -| sync | Run synchronously if multiple hosts are specified | false | -| timeout | Timeout for SSH connection to host | 30s | -| key | Content of SSH private key (e.g., raw content of `~/.ssh/id_rsa`) | | -| key_path | Path to SSH private key | | -| passphrase | Passphrase for the SSH private key | | -| fingerprint | SHA256 fingerprint of the host public key | | -| use_insecure_cipher | Allow additional (less secure) ciphers | false | -| cipher | Allowed cipher algorithms. Uses sensible defaults if unspecified | | - ---- - -### 🛠ī¸ SSH Command Settings - -These parameters control the commands executed on the remote host and related behaviors. - -| Parameter | Description | Default | -| --------------- | --------------------------------------------------------------------------------- | ------- | -| script | Commands to execute remotely | | -| script_path | Path to a file in the repository containing commands to execute remotely | | -| envs | Environment variables to pass to the shell script | | -| envs_format | Flexible configuration for environment variable transfer | | -| allenvs | Pass all environment variables with `GITHUB_` and `INPUT_` prefixes to the script | false | -| command_timeout | Timeout for SSH command execution | 10m | -| debug | Enable debug mode | false | -| request_pty | Request a pseudo-terminal from the server | false | -| curl_insecure | Allow curl to connect to SSL sites without certificates | false | -| version | drone-ssh binary version. If not specified, the latest version will be used. | | - ---- - -### 🌐 Proxy Settings - -These parameters control the use of a proxy (jump host) for connecting to your target host. - -| Parameter | Description | Default | -| ------------------------- | ----------------------------------------------- | ------- | -| proxy_host | SSH proxy host | | -| proxy_port | SSH proxy port | 22 | -| proxy_username | SSH proxy username | | -| proxy_password | SSH proxy password | | -| proxy_passphrase | SSH proxy key passphrase | | -| proxy_protocol | SSH proxy protocol version | tcp | -| proxy_timeout | Timeout for SSH connection to proxy host | 30s | -| proxy_key | Content of SSH proxy private key | | -| proxy_key_path | Path to SSH proxy private key | | -| proxy_fingerprint | SHA256 fingerprint of the proxy host public key | | -| proxy_cipher | Allowed cipher algorithms for the proxy | | -| proxy_use_insecure_cipher | Allow insecure ciphers for the proxy | false | - -> **Note:** To mimic the removed `script_stop` option, add `set -e` at the top of your shell script. - ---- - -## ⚡ Quick Start - -Run remote SSH commands in your workflow with minimal configuration: - -```yaml -name: Remote SSH Command -on: [push] -jobs: - build: - name: Build - runs-on: ubuntu-latest - steps: - - name: Execute remote SSH commands using password - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: linuxserver.io - password: ${{ secrets.PASSWORD }} - port: ${{ secrets.PORT }} - script: whoami -``` - -**Output:** - -```sh -======CMD====== -whoami -======END====== -linuxserver.io -=============================================== -✅ Successfully executed commands to all hosts. -=============================================== -``` - ---- - -## 🔑 SSH Key Setup & OpenSSH Compatibility - -### Setting Up SSH Keys - -It is best practice to create SSH keys on your local machine (not on a remote server). Log in with the username specified in GitHub Secrets and generate a key pair: - -#### Generate RSA key - -```bash -ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -``` - -#### Generate ED25519 key - -```bash -ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" -``` - -Add the new public key to the authorized keys on your server. [Learn more about authorized keys.](https://www.ssh.com/ssh/authorized_keys/) - -```bash -# Add RSA key -cat .ssh/id_rsa.pub | ssh user@host 'cat >> .ssh/authorized_keys' - -# Add ED25519 key -cat .ssh/id_ed25519.pub | ssh user@host 'cat >> .ssh/authorized_keys' -``` - -Copy the private key content and paste it into GitHub Secrets. - -```bash -# macOS -pbcopy < ~/.ssh/id_rsa -# Ubuntu -xclip < ~/.ssh/id_rsa -``` - -> **Tip:** Copy from `-----BEGIN OPENSSH PRIVATE KEY-----` to `-----END OPENSSH PRIVATE KEY-----` (inclusive). - -For ED25519: - -```bash -# macOS -pbcopy < ~/.ssh/id_ed25519 -# Ubuntu -xclip < ~/.ssh/id_ed25519 -``` - -See more: [SSH login without a password](http://www.linuxproblem.org/art_9.html). - -> **Note:** Depending on your SSH version, you may also need to: -> -> - Place the public key in `.ssh/authorized_keys2` -> - Set `.ssh` permissions to 700 -> - Set `.ssh/authorized_keys2` permissions to 640 - -### OpenSSH Compatibility - -If you see this error: - -```bash -ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey] -``` - -On Ubuntu 20.04+ you may need to explicitly allow the `ssh-rsa` algorithm. Add this to your OpenSSH daemon config (`/etc/ssh/sshd_config` or a drop-in under `/etc/ssh/sshd_config.d/`): - -```bash -CASignatureAlgorithms +ssh-rsa -``` - -Alternatively, use ED25519 keys (supported by default): - -```bash -ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" -``` - ---- - -## 🛠ī¸ Usage Scenarios & Advanced Examples - -This section covers common and advanced usage patterns, including multi-host, proxy, and environment variable passing. - -### Using password authentication - -```yaml -- name: Execute remote SSH commands using password - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - password: ${{ secrets.PASSWORD }} - port: ${{ secrets.PORT }} - script: whoami -``` - -### Using private key authentication - -```yaml -- name: Execute remote SSH commands using SSH key - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script: whoami -``` - -### Multiple commands - -```yaml -- name: Multiple commands - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script: | - whoami - ls -al -``` - -![result](./images/output-result.png) - -### Run commands from a file - -```yaml -- name: File commands - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script_path: scripts/script.sh -``` - -### Multiple hosts - -```diff - - name: Multiple hosts - uses: appleboy/ssh-action@v1 - with: -- host: "foo.com" -+ host: "foo.com,bar.com" - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script: | - whoami - ls -al -``` - -Default `port` is `22`. - -### Multiple hosts with different ports - -```diff - - name: Multiple hosts - uses: appleboy/ssh-action@v1 - with: -- host: "foo.com" -+ host: "foo.com:1234,bar.com:5678" - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - script: | - whoami - ls -al -``` - -### Synchronous execution on multiple hosts - -```diff - - name: Multiple hosts - uses: appleboy/ssh-action@v1 - with: - host: "foo.com,bar.com" -+ sync: true - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script: | - whoami - ls -al -``` - -### Pass environment variables to shell script - -```diff - - name: Pass environment - uses: appleboy/ssh-action@v1 -+ env: -+ FOO: "BAR" -+ BAR: "FOO" -+ SHA: ${{ github.sha }} - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} -+ envs: FOO,BAR,SHA - script: | - echo "I am $FOO" - echo "I am $BAR" - echo "sha: $SHA" -``` - -> _All environment variables in the `env` object must be strings. Using integers or other types may cause unexpected results._ - ---- - -## 🌐 Proxy & Jump Host Usage - -You can connect to remote hosts via a proxy (jump host) for advanced network topologies. - -```bash -+--------+ +----------+ +-----------+ -| Laptop | <--> | Jumphost | <--> | FooServer | -+--------+ +----------+ +-----------+ -``` - -Example `~/.ssh/config`: - -```bash -Host Jumphost - HostName Jumphost - User ubuntu - Port 22 - IdentityFile ~/.ssh/keys/jump_host.pem - -Host FooServer - HostName FooServer - User ubuntu - Port 22 - ProxyCommand ssh -q -W %h:%p Jumphost -``` - -**GitHub Actions YAML:** - -```diff - - name: SSH proxy command - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} -+ proxy_host: ${{ secrets.PROXY_HOST }} -+ proxy_username: ${{ secrets.PROXY_USERNAME }} -+ proxy_key: ${{ secrets.PROXY_KEY }} -+ proxy_port: ${{ secrets.PROXY_PORT }} - script: | - mkdir abc/def - ls -al -``` - ---- - -## 🛡ī¸ Security Best Practices - -### Protecting Your Private Key - -A passphrase encrypts your private key, making it useless to attackers if leaked. Always store your private key securely. - -```diff - - name: SSH key passphrase - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} -+ passphrase: ${{ secrets.PASSPHRASE }} - script: | - whoami - ls -al -``` - -### Host Fingerprint Verification - -Verifying the SSH host fingerprint helps prevent man-in-the-middle attacks. To get your host's fingerprint (replace `ed25519` with your key type and `example.com` with your host): - -```sh -ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2 -``` - -Update your config: - -```diff - - name: SSH key passphrase - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} -+ fingerprint: ${{ secrets.FINGERPRINT }} - script: | - whoami - ls -al -``` - ---- - -## 🚨 Error Handling & Troubleshooting - -### Q&A - -#### Command not found (npm or other command) - -If you encounter "command not found" errors, see [this issue comment](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) about interactive vs non-interactive shells. - -On many Linux distros, `/etc/bash.bashrc` contains: - -```sh -# If not running interactively, don't do anything -[ -z "$PS1" ] && return -``` - -Comment out this line or use absolute paths for your commands. - ---- - -## 🤝 Contributing - -Contributions are welcome! Please submit a pull request to help improve `appleboy/ssh-action`. - ---- - -## 📝 License - -This project is licensed under the [MIT License](LICENSE).