From 4af3346b6afc5f54cafec0219605590f922e0040 Mon Sep 17 00:00:00 2001 From: Eddy Filip Date: Mon, 6 Sep 2021 12:39:46 +0300 Subject: [PATCH] Update README with new functionality Give examples for both ways of loading secrets. Update masking. Add security and help sections. --- README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 102 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c3f18a4..d0b718c 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,90 @@ # Load Secrets from 1Password - GitHub Action -The action to load secrets from [1Password Connect](https://1password.com/secrets/) into GitHub Actions. +This action loads secrets from [1Password Connect](https://1password.com/secrets/) into GitHub Actions. 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 + +This approach enables the user to use the loaded secrets as an output from the step: `steps.step-id.outputs.secret-name`. You need to set an id for the step that uses this action to be able to access its outputs. More details about the metadata syntax [here](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#outputsoutput_id). + +```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: + 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: *** +``` + +
+Longer usage example + +```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 +``` +
+ +### Export secrets as environment variables + +In this approach, the user can access the loaded secrets as environment variables. These environment variables are accessible at a job level. + ```yml on: push jobs: @@ -16,6 +95,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: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} @@ -48,6 +130,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 +156,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 +176,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 +195,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 +235,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**](https://bugcrowd.com/agilebits). + +For information about security practices, please visit our [Security homepage](https://bugcrowd.com/agilebits). + +## Getting help + +If you find yourself stuck, visit our [**Support Page**](https://support.1password.com/) for help.