From 6d9d6acc6aef1f9166118c6ba8bd214d3a582bdb Mon Sep 17 00:00:00 2001
From: Albert Wang <git@albertyw.com>
Date: Wed, 1 Feb 2023 00:26:22 -0800
Subject: [PATCH] Document configuration through dotenv variables (#224)

* Format parameter table

* Format parameter keys as code

* Add documentation of configuration overrides
---
 DOCS.md   | 102 ++++++++++++++++--------------------------------------
 README.md |  13 +++++++
 2 files changed, 42 insertions(+), 73 deletions(-)

diff --git a/DOCS.md b/DOCS.md
index c0dd7f1..c41cd0f 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -179,79 +179,35 @@ Example configuration for passphrase which protecting a private key:
 
 ## Secret Reference
 
-ssh_username
-: account for target host user
-
-ssh_password
-: password for target host user
-
-ssh_passphrase
-: The purpose of the passphrase is usually to encrypt the private key.
-
-ssh_key
-: plain text of user private key
-
-proxy_ssh_username
-: account for user of proxy server
-
-proxy_ssh_password
-: password for user of proxy server
-
-proxy_ssh_passphrase
-: The purpose of the passphrase is usually to encrypt the private key.
-
-proxy_ssh_key
-: plain text of user private key for proxy server
+| Key | Description |
+|-----|-------------|
+| `ssh_username` | account for target host user |
+| `ssh_password` | password for target host user | |
+| `ssh_passphrase` | The purpose of the passphrase is usually to encrypt the private key. |
+| `ssh_key` | plain text of user private key |
+| `proxy_ssh_username` | account for user of proxy server |
+| `proxy_ssh_password` | password for user of proxy server |
+| `proxy_ssh_passphrase` | The purpose of the passphrase is usually to encrypt the private key. |
+| `proxy_ssh_key` | plain text of user private key for proxy server |
 
 ## Parameter Reference
 
-host
-: target hostname or IP
-
-port
-: ssh port of target host
-
-username
-: account for target host user
-
-password
-: password for target host user
-
-key
-: plain text of user private key
-
-key_path
-: key path of user private key
-
-envs
-: custom secrets which are made available in the script section
-
-script
-: execute commands on a remote server
-
-script_stop
-: stop script after first failure
-
-timeout
-: Timeout is the maximum amount of time for the ssh connection to establish, default is 30 seconds.
-
-command_timeout
-: Command timeout is the maximum amount of time for the execute commands, default is 10 minutes.
-
-proxy_host
-: proxy hostname or IP
-
-proxy_port
-: ssh port of proxy host
-
-proxy_username
-: account for proxy host user
-
-proxy_password
-: password for proxy host user
-
-proxy_key
-: plain text of proxy private key
-
-proxy_key_path
-: key path of proxy private key
+| Key | Description |
+|-----|-------------|
+| `host` | target hostname or IP |
+| `port` | ssh port of target host |
+| `username` | account for target host user |
+| `password` | password for target host user |
+| `key` | plain text of user private key |
+| `key_path` | key path of user private key |
+| `envs` | custom secrets which are made available in the script section |
+| `script` | execute commands on a remote server |
+| `script_stop` | stop script after first failure |
+| `timeout` | Timeout is the maximum amount of time for the ssh connection to establish, default is 30 seconds. |
+| `command_timeout` | Command timeout is the maximum amount of time for the execute commands, default is 10 minutes. |
+| `proxy_host` | proxy hostname or IP |
+| `proxy_port` | ssh port of proxy host |
+| `proxy_username` | account for proxy host user |
+| `proxy_password` | password for proxy host user |
+| `proxy_key` | plain text of proxy private key |
+| `proxy_key_path` | key path of proxy private key |
diff --git a/README.md b/README.md
index 05e21ae..f9d03c6 100644
--- a/README.md
+++ b/README.md
@@ -110,3 +110,16 @@ pipeline:
 ```
 
 See the detail of [issue comment](https://github.com/appleboy/drone-ssh/issues/51#issuecomment-336732928).
+
+## Configuration
+
+See [DOCS.md](./DOCS.md) for examples and full configuration options
+
+Configuration options are loaded from multiple sources:
+
+0.  Hardcoded drone-ssh defaults.  See [main.go CLI Flags](https://github.com/albertyw/drone-ssh/blob/master/main.go#L39) for more information.
+1.  From a `.env` [dotenv](https://github.com/joho/godotenv) file at the root of the repository tested by drone.
+2.  From a dotenv file at a path specified by the `PLUGIN_ENV_FILE` environment variable.
+3.  From your `.drone.yml` Drone configuration.
+
+Later sources override previous sources, i.e. if `PORT` is set in an `.env` file committed in the repository or created by previous test steps, it will override the default set `main.go`.