From b85e634d10ad790ec4d8942ce9becf04803e42df Mon Sep 17 00:00:00 2001
From: David Parsley <parsley@linuxjedi.org>
Date: Mon, 11 Nov 2024 15:58:00 +0000
Subject: [PATCH] Document ssh-git-helper

---
 doc/src/pipelines/tasks.md                |  2 ++
 doc/src/pipelines/tasks/ssh-git-helper.md | 14 ++++++++++++++
 2 files changed, 16 insertions(+)
 create mode 100644 doc/src/pipelines/tasks/ssh-git-helper.md

diff --git a/doc/src/pipelines/tasks.md b/doc/src/pipelines/tasks.md
index 5f482d3..ac3d58a 100644
--- a/doc/src/pipelines/tasks.md
+++ b/doc/src/pipelines/tasks.md
@@ -22,4 +22,6 @@
 
 {{#include tasks/ssh-agent.md}}
 
+{{#include tasks/ssh-git-helper.md}}
+
 {{#include tasks/tail-log.md}}
diff --git a/doc/src/pipelines/tasks/ssh-git-helper.md b/doc/src/pipelines/tasks/ssh-git-helper.md
new file mode 100644
index 0000000..ba95799
--- /dev/null
+++ b/doc/src/pipelines/tasks/ssh-git-helper.md
@@ -0,0 +1,14 @@
+___
+
+**ssh-git-helper** - *privileged*
+
+Usage:
+- `AddTask ssh-git-helper addhostkeys <encoded-host-keys>` - create a `known_hosts` file from the encoded keys
+- `AddTask ssh-git-helper scan <host>` - fallback sub-command to scan a remote host for the host keys
+- `AddTask ssh-git-helper loadhostkeys <repo uri>` - for github, bitbucket, retrieve host keys from a known https API endpoint
+- `AddTask ssh-git-helper publishenv` - set `SSH_OPTIONS` and `GIT_SSH_COMMAND` for external binary use
+- `AddTask ssh-git-helper delete` - delete the temporary hostkeys file; automatically added as a FinalTask
+
+The `addhostkeys`, `loadhostkeys` and `scan` sub-commands all create a `known_hosts` file that can be used with `git-command` and `ssh-agent` for working with git repositories authenticated with ssh. Each of these sub-commands also automatically adds a `FinalTask ssh-git-helper delete` to remove the temporary file. By using `publishenv`, the `SSH_OPTIONS` and `GIT_SSH_COMMAND` parameters (environment variables) are exported to the pipeline for use by e.g. bash-based tasks using the system ssh and/or git binaries.
+
+Note that `<encoded-host-keys>` is a single-line string encoded similarly to `GOPHER_DEPLOY_KEY`; all spaces are replaced with '_', and newlines are replaced with ':'; basically, `tr ' \n' '_:'`.