Add documentation

edif2008 · Aug 31, 2021 · eea4e1c · eea4e1c
1 parent 5f042fb
commit eea4e1c
Show file tree

Hide file tree

Showing 2 changed files with 98 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -4,8 +4,83 @@ The action to load secrets from [1Password Connect](https://1password.com/secret
 
 Specify right from your workflow YAML which secrets from 1Password should be loaded into your job, and the action will make them available as environment variables for the next steps.
 
+## Prerequisites 
+ - [1Password Connect](https://support.1password.com/secrets-automation/#step-2-deploy-a-1password-connect-server) deployed in your infrastructure
+
 ## Usage
 
+There are two ways that secrets can be loaded:
+ - [use the secrets from the action's ouput](#use-secrets-from-the-actions-output)
+ - [export secrets as environment variables](#export-secrets-as-environment-variables)
+
+### Use secrets from the action's output
+
+```yml
+on: push
+jobs:
+  hello-world:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Load secret
+        id: op-load-secret
+        uses: 1password/load-secrets-action@v1
+        env:
+          OP_CONNECT_HOST: <Your Connect instance URL>
+          OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
+          SECRET: op://app-cicd/hello-world/secret
+
+      - name: Print masked secret
+        run: echo "Secret: ${{ steps.op-load-secret.outputs.SECRET }}"
+        # Prints: Secret: ***
+```
+
+<details>
+<summary><b>Longer usage example</b></summary>
+
+```yml
+on: push
+name: Deploy app
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Configure 1Password Connect
+        uses: 1password/load-secrets-action/configure@v1
+        with:
+          # Persist the 1Password Connect URL for next steps. You can also persist 
+          # the Connect token using input `connect-token`, but keep in mind that 
+          # every single step in the job would then be able to access the token.
+          connect-host: https://1password.acme.com
+
+      - name: Load Docker credentials
+        id: load-docker-credentials
+        uses: 1password/load-secrets-action@v1
+        env:
+          OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
+          DOCKERHUB_USERNAME: op://app-cicd/docker/username
+          DOCKERHUB_TOKEN: op://app-cicd/docker/token
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v1
+        with:
+          username: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_USERNAME }}
+          password: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v2
+        with:
+          push: true
+          tags: acme/app:latest
+```
+</details>
+
+### Export secrets as environment variables
+
 ```yml
 on: push
 jobs:
@@ -16,6 +91,9 @@ jobs:
 
       - name: Load secret
         uses: 1password/load-secrets-action@v1
+        with:
+          # Export loaded secrets as environment variables
+          export-env: true
         env:
           OP_CONNECT_HOST: <Your Connect instance URL>
           OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
@@ -48,6 +126,9 @@ jobs:
 
       - name: Load Docker credentials
         uses: 1password/load-secrets-action@v1
+        with:
+          # Export loaded secrets as environment variables
+          export-env: true
         env:
           OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
           DOCKERHUB_USERNAME: op://app-cicd/docker/username
@@ -71,6 +152,8 @@ jobs:
       - name: Load AWS credentials
         uses: 1password/load-secrets-action@v1
         with:
+          # Export loaded secrets as environment variables
+          export-env: true
           # Remove local copies of the Docker credentials, which are not needed anymore
           unset-previous: true
         env:
@@ -89,6 +172,7 @@ jobs:
 
 | Name | Default | Description |
 |---|---|---|
+| `export-env`     | `false` | Export the loaded secrets as environment variables |
 | `unset-previous` | `false` | Whether to unset environment variables populated by 1Password in earlier job steps |
 
 ## Secrets Reference Syntax
@@ -107,12 +191,9 @@ So for example, the reference URI `op://app-cicd/aws/secret-access-key` would be
 
 ## Masking
 
-Similar to regular GitHub repository secrets, secret fields from 1Password will automatically be masked from the GitHub Actions logs too.
-A 1Password field is considered 'secret' when it's marked as concealed (which shows as `•••••••` in the 1Password GUI) or when it's a secure note.
+Similar to regular GitHub repository secrets, fields from 1Password will automatically be masked from the GitHub Actions logs too.
 So if one of these values accidentally gets printed, it'll get replaced with `***`.
 
-This means that a username or port field for example will not get masked.
-
 ## 1Password Connect Configuration
 
 To use the action, you need to have a [1Password Connect](https://support.1password.com/secrets-automation/#step-1-set-up-a-secrets-automation-workflow) instance deployed somewhere.
@@ -150,3 +231,15 @@ jobs:
 ## Supported Runners
 
 You can run the action on Linux and macOS runners. Windows is currently not supported.
+
+## Security
+
+1Password requests you practice responsible disclosure if you discover a vulnerability.
+
+Please file requests via BugCrowd.
+
+For information about security practices, please visit our Security homepage.
+
+## Getting help
+
+If you find yourself stuck, visit our Support Page for help.
diff --git a/action.yml b/action.yml
@@ -9,7 +9,7 @@ inputs:
     description: Whether to unset environment variables populated by 1Password in earlier job steps
     default: false
   export-env:
-    description: Export the secrets as environment variables
+    description: Export the loaded secrets as environment variables
     default: false
 runs:
   using: 'docker'