docs: improve docs for onboarding and usage (#13)

* docs: improve docs for onboarding and usage
* chore: enable trunk
* ci: add integration test

.github/workflows/integration.yml

@@ -1,12 +1,12 @@
 ---
 name: integration
 on:
-  # pull_request:
-  # push:
-  #   branches:
-  #     - main
-  #   tags:
-  #     - v*
+  pull_request:
+  push:
+    branches:
+      - main
+    tags:
+      - v*
   workflow_dispatch:
     inputs:
       setenv:

.github/workflows/lint.yml

@@ -9,6 +9,7 @@ concurrency:
 permissions:
   pull-requests: read
   contents: read
+  checks: write
 jobs:
   lint:
     name: lint

.goreleaser.yaml

@@ -94,4 +94,4 @@ announce:
 sboms:
   - artifacts: binary
     documents:
-      - "${artifact}.spdx.sbom"
+      - '${artifact}.spdx.sbom'

.markdownlint.yaml

@@ -1,10 +1,13 @@
 ---
 comment: my-markdown-linting-rules
+indentation: false
+
 default: true
 # MD003:
 #   style:
-MD007:
-  indent: 4
+MD002: true
+MD007: true
+
 no-hard-tabs: true
 whitespace: true
 no-bare-urls: true

.trunk/trunk.yaml

@@ -1,4 +1,8 @@
 ---
+actions:
+  enabled:
+    - trunk-check-pre-push
+    - trunk-fmt-pre-commit
 version: 0.1
 runtimes:
   enabled:

.vscode/launch.json

@@ -10,10 +10,7 @@
       "request": "launch",
       "mode": "test",
       "program": "${workspaceFolder}",
-      "args": [
-        "-test.run",
-        "TestOpenEnvFile"
-      ]
+      "args": ["-test.run", "TestOpenEnvFile"]
     },
     {
       "name": "Launch file",
@@ -28,6 +25,6 @@
       "request": "launch",
       "mode": "auto",
       "program": "${fileDirname}"
-    },
+    }
   ]
 }

DEVELOPER.md

@@ -62,3 +62,44 @@ gh secret create DSV_SECRET_KEY_2
 gh secret create DSV_EXPECTED_VALUE_1
 gh secret create DSV_EXPECTED_VALUE_2
 ```
+
+For general config you'll also need:
+
+```shell
+gh secret set DSV_SERVER
+gh secret set DSV_CLIENT_SECRET                                                                                          gh secret set DSV_CLIENT_ID
+```
+
+## Local Integration Testing
+
+Ensure you've setup with `mage init` to have all the tooling.
+
+Run `mage buildall test:integration`.
+
+Setup a test env file to load into the dockerized test run.
+
+```shell
+# To read from local credfile (not optimal)
+# DSV_CLIENT_ID=$(cat "${clientcredfile}" | jq '.clientId' --raw-output)
+# DSV_CLIENT_SECRET=$(cat "${clientcredfile}" | jq '.clientSecret' --raw-output)
+# INSTEAD: read using dsv cli! 💯
+rm .cache/.secrets
+rm .cache/.envfile
+touch .cache/.envfile
+cat <<EOT >> .cache/.secrets
+DSV_SECRET_PATH=secrets:ci:tests:dsv-github-action:secret-01
+DSV_SECRET_KEY_1=<testvaluehere>
+DSV_SECRET_KEY_2=<testvaluehere>
+DSV_EXPECTED_VALUE_1=<testvaluehere>
+DSV_EXPECTED_VALUE_2=<testvaluehere>
+DSV_DOMAIN=<tenanthere>.secretsvaultcloud.com
+DSV_CLIENT_ID=$(dsv secret read "${secretpathclient}" --filter '.data.clientId')
+DSV_CLIENT_SECRET=$(dsv secret read "${secretpathclient}" --filter '.data.clientSecret')
+GITHUB_TOKEN=${GITHUB_TOKEN}
+GITHUB_ENV=/app/.cache/.envfile
+GITHUB_ACTIONS=true
+DSV_SET_ENV=true
+DSV_RETRIEVE=[{"secretPath": "ci:tests:dsv-github-action:secret-01", "secret_key": "", "output_variable": "RETURN_VALUE_1"}]
+RUNNER_DEBUG=true
+EOT
+```

README.md

@@ -1,79 +1,173 @@
-# Repo
+# dsv-github-action
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 
 [![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
 
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-Brief description
+Use Delinea DevOps Secret Vault for retrieval of your secrets.
+
+Now, instead of storing all your secrets directly in your GitHub repo configuration, store client credentials to connect and retrieve the desired secret or multiple secrets from your secure vault.
 
 ## Getting Started
 
 - [Developer](DEVELOPER.md): instructions on running tests, local tooling, and other resources.
 - [DSV Documentation](https://docs.delinea.com/dsv/current?ref=githubrepo)
+- [Download DSV CLI](https://dsv.secretsvaultcloud.com/downloads)
+  Quick install example (adjust to platform/version): `curl -fSsl https://dsv.secretsvaultcloud.com/downloads/cli/1.37.5/dsv-darwin-x64 -o dsv && chmod +x ./dsv && sudo mv ./dsv /usr/local/bin`
+- Remaining readme for the usage directions.
+- Install [github-cli](https://cli.github.com/) for easier setup.
+  - quick: `brew install gh` or see [installation instructions](https://github.com/cli/cli#installation)
 
 ## How This Works
 
 ## Inputs
 
-| Name           | Description                                                              |
-| -------------- | ------------------------------------------------------------------------ |
-| `domain`       | Tenant domain name (e.g. example.secretsvaultcloud.com).                 |
-| `clientId`     | Client ID for authentication.                                            |
-| `clientSecret` | Client Secret for authentication.                                        |
-| `setEnv`       | Set environment variables. Applicable only for GitHub Actions.           |
-| `retrieve`     | Data to retrieve from DSV in format `<path> <data key> as <output key>`. |
+| Name           | Description                                                    |
+| -------------- | -------------------------------------------------------------- |
+| `domain`       | Tenant domain name (e.g. example.secretsvaultcloud.com).       |
+| `clientId`     | Client ID for authentication.                                  |
+| `clientSecret` | Client Secret for authentication.                              |
+| `setEnv`       | Set environment variables. Applicable only for GitHub Actions. |
+| `retrieve`     | Data to retrieve from DSV in json format.                      |
 
 ## Prerequisites
 
 This plugin uses authentication based on Client Credentials, i.e. via Client ID and Client Secret.
 
-You can generate Client Credentials using a command-line interface (CLI) tool. Latest version of
-the CLI tool can be found here: <https://dsv.secretsvaultcloud.com/downloads>. Quick start with
-the CLI: <https://docs.delinea.com/dsv/current/quickstart>.
+```shell
+rolename="github-dsv-github-action-tests"
+secretpath="ci:tests:dsv-github-action"
+secretpathclient="clients:${secretpath}"
 
-To create a role run:
+desc="a secret for testing operation of secrets against dsv-github-action"
+clientcredfile=".cache/${rolename}.json"
+clientcredname="${rolename}"
 
-```shell
-dsv role create --name <role name>
-```
+dsv role create --name "${rolename}"
 
-To generate a pair of Client ID and Client Secret run:
+# Option 1: Less Optimal - Save Credential to local json for testing
+# dsv client create --role "${rolename}" --out "file:${clientcredfile}"
 
-```shell
-dsv client create --role <role name>
-```
+# Option 2: 🔒 MOST SECURE
+# Create credential info for dsv, and set as variable. Then use the github cli to set as a secret for your action.
+# Create an org secret instead if you want to share this credential in many repos.
 
-Use returned values of Client ID and Client Secret to configure this plugin. After this you can
-create secrets for the pipeline and configure access to those secrets.
+# compress to a single line
+clientcred=$(dsv client create --role "${rolename}" --plain | jq -c)
 
-Example of configuration:
+# configure the dsv server, such as mytenant.secretsvaultcloud.com
+gh secret set DSV_CLIENT_ID
 
-```shell
-# Create a role named "ci-reader":
-dsv role create --name ci-reader
+# use the generated client credentials in your repo
+gh secret set DSV_CLIENT_ID --body "$( echo "${clientcred}" | jq '.clientId' )"
+gh secret set DSV_CLIENT_SECRET --body "$( echo "${clientcred}" | jq '.clientSecret')"
+```
 
-# Generate client credentials for the role:
-dsv client create --role ci-reader
+For further setup, here's how you could create extend that script block above with also creating a secret and the policy to read just this secret.
 
-# Create a secret:
+```shell
+# Create a secret
+secretkey="secret-01"
+secretvalue='{"value1":"taco","value2":"burrito"}'
 dsv secret create \
-  --path 'ci-secrets:secret1' \
-  --data '{"password":"foo","token":"bar"}'
+  --path "secrets:${secretpath}:${secretkey}" \
+  --data "${secretvalue}" \
+  --desc "${desc}"
 
-# Create a policy to allow role "ci-reader" to read secrets under "ci-secrets":
+# Create a policy to allow role "$rolename" to read secrets under "ci:tests:integration-configs/dsv-github-action":
 dsv policy create \
-  --path 'secrets:ci-secrets' \
+  --path "secrets:${secretpath}" \
   --actions 'read' \
   --effect 'allow' \
-  --subjects 'roles:ci-reader'
+  --subjects "roles:$rolename" \
+  --desc "${desc}" \
+  --resources "${secretpath}:<.*>"
 ```
 
 ## GitHub usage example
 
 See [integration.yaml](.github/workflows/integration.yaml) for an example of how to use this to retrieve secrets and use outputs on other tasks.
 
+## Other Usage Examples
+
+### Retrieve A Single Secret Without Setting Env File
+
+```yaml
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v3
+      - id: dsv
+        uses: delineaxpm/dsv-github-action@v1 # renovate: tag=v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          domain: ${{ secrets.DSV_SERVER }}
+          clientId: ${{ secrets.DSV_CLIENT_ID }}
+          clientSecret: ${{ secrets.DSV_CLIENT_SECRET }}
+          setEnv: false
+          retrieve: |
+            [
+             {"secretPath": "ci:tests:dsv-github-action:secret-01", "secretKey": "value1" }
+            ]
+```
+
+### Set Output to Job Scope Using SetEnv
+
+```yaml
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v3
+      - id: dsv
+        uses: delineaxpm/dsv-github-action@v1 # renovate: tag=v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          domain: ${{ secrets.DSV_SERVER }}
+          clientId: ${{ secrets.DSV_CLIENT_ID }}
+          clientSecret: ${{ secrets.DSV_CLIENT_SECRET }}
+          setEnv: true
+          retrieve: |
+            [
+             {"secretPath": "ci:tests:dsv-github-action:secret-01", "secretKey": "value1", "outputVariable": "MY_ENV_VAR" }
+            ]
+      - name: validate-first-value
+        if: always()
+        run: |
+          "This is a secret value you shouldn't echo 👉 ${{ steps.dsv.outputs.MY_ENV_VAR }}"
+```
+
+### Retrieve 2 Values from Same Secret
+
+The json expects an array, so just add a new line.
+
+```yaml
+retrieve: |
+  [
+   {"secretPath": "ci:tests:dsv-github-action:secret-01", "secretKey": "value1", "outputVariable": "MY_ENV_VAR_1" },
+   {"secretPath": "ci:tests:dsv-github-action:secret-01", "secretKey": "value2", "outputVariable": "MY_ENV_VAR_2" }
+  ]
+```
+
+### Retrieve 2 Values from Different Secrets
+
+> Note: Make sure your generated client credentials are associated a policy that has rights to read the different secrets.
+
+```yaml
+retrieve: |
+  [
+   {"secretPath": "ci:tests:dsv-github-action:secret-01", "secretKey": "value1", "outputVariable": "MY_ENV_VAR_1" },
+   {"secretPath": "ci:tests:dsv-github-action:secret-02", "secretKey": "value1", "outputVariable": "MY_ENV_VAR_2" }
+  ]
+```
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

action.yml

@@ -1,6 +1,7 @@
 ---
 name: secret-vault-github-action-plugin
-description: Delinea DevOps Secrets Vault (DSV) GitHub Actions Plugin allows you to access and reference your Secrets data available for use in GitHub Actions
+description: |
+  Delinea DevOps Secrets Vault (DSV) GitHub Actions Plugin allows you to access and reference your Secrets data available for use in GitHub Actions
 
 inputs:
   domain: