From 85386695a587fa53f22b7c7d639a6de7efda3951 Mon Sep 17 00:00:00 2001 From: Lucy Butcher Date: Mon, 3 Oct 2022 09:26:54 -0400 Subject: [PATCH] Update readme to link to developer portal This MR updates the readme to: - Match the final edited text used in the developer portal - Link out to the developer portal for usage examples beyond basic setup --- README.md | 266 ++++++------------------------------------------------ 1 file changed, 30 insertions(+), 236 deletions(-) diff --git a/README.md b/README.md index 26ed5d9..19564f0 100644 --- a/README.md +++ b/README.md @@ -1,254 +1,48 @@ # Load Secrets from 1Password - GitHub Action -This action loads secrets from 1Password into GitHub Actions using [1Password Connect](https://1password.com/secrets/). +`load-secrets-action` loads secrets from 1Password into GitHub Actions using [1Password Connect](https://developer.1password.com/docs/connect). -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. +Specify in your workflow YAML file which secrets from 1Password should be loaded into your job, and the action will make them available as environment variables for the next steps. + +## Requirements + +Before you get started, you'll need to: + +- [Deploy 1Password Connect](https://developer.1password.com/docs/connect/get-started#step-2-deploy-1password-connect-server) in your infrastructure. +- Set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables to your Connect instance's credentials, so it'll be used to load secrets. + +### Supported runners + +You can run the action on Mac and Linux runners. Windows is currently not supported. + +## 1Password configuration + +By default, you'll need to set the environment variables for your Connect instance in the step that uses `load-secrets-action`. + +If you're using the action more than once in a single job, [you can use the `configure` action](https://developer.1password.com/docs/connect/github-actions/#1password-configuration) to set the environment variables instead, so you don't have to set them separately in each `load-secrets-action` step. ## Usage -You can configure the action to use either 1Password Connect instance. +You can load secrets using the action in two ways: -If you provide `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` variables, the Connect instance will be used to load secrets. Make sure [1Password Connect](https://support.1password.com/secrets-automation/#step-2-deploy-a-1password-connect-server) is deployed in your infrastructure. - -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 method allows for you to use the loaded secrets as an output from the step: `steps.step-id.outputs.secret-name`. You will need to set an id for the step that uses this action to be able to access its outputs. For more details, , see [`outputs.`](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 - -This method, allows the action to access the loaded secrets as environment variables. These environment variables are accessible at a job level. - -```yml -on: push -jobs: - hello-world: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - - 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 }} - SECRET: op://app-cicd/hello-world/secret - - - name: Print masked secret - run: echo "Secret: $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 - 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 - DOCKERHUB_TOKEN: op://app-cicd/docker/token - - - name: Login to Docker Hub - uses: docker/login-action@v1 - with: - username: ${{ env.DOCKERHUB_USERNAME }} - password: ${{ env.DOCKERHUB_TOKEN }} - - - name: Print environment variables with masked secrets - run: printenv - - - name: Build and push Docker image - uses: docker/build-push-action@v2 - with: - push: true - tags: acme/app:latest - - - 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: - OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} - AWS_ACCESS_KEY_ID: op://app-cicd/aws/access-key-id - AWS_SECRET_ACCESS_KEY: op://app-cicd/aws/secret-access-key - - - name: Deploy app - # This script expects AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to be set, which was - # done automatically by the step above - run: ./deploy.sh -``` - -
- -## Action Inputs - -| 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 - -To specify which secret should be loaded into which environment variable, the action will look for `op://` reference URIs in environment variables, and replace those with the actual secret values. - -These reference URIs have the following syntax: - -> `op:///[/
]/` - -So for example, the reference URI `op://app-cicd/aws/secret-access-key` would be interpreted as: - -- **Vault:** `app-cicd` -- **Item:** `aws` -- **Section:** default section -- **Field:** `secret-access-key` +1. [Use secrets from the action's output](https://developer.1password.com/docs/connect/github-actions/#use-secrets-from-the-actions-output) +2. [Export secrets as environment variables](https://developer.1password.com/docs/connect/github-actions/#export-secrets-as-environment-variables) ## Masking -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 `***`. - -## 1Password Configuration - -To use the action with Connect, you need to have a [1Password Connect](https://support.1password.com/secrets-automation/#step-1-set-up-a-secrets-automation-workflow) instance deployed somewhere. -To configure the action with your Connect host and token, set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables. - -If you're using the `load-secrets` action more than once in a single job, you can use the `configure` action to avoid duplicate configuration: - -```yml -on: push -jobs: - hello-world: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - - name: Configure 1Password Connect - uses: 1password/load-secrets-action/configure@v1 - with: - connect-host: - connect-token: ${{ secrets.OP_CONNECT_TOKEN }} - - name: Load secret - uses: 1password/load-secrets-action@v1 - env: - SECRET: op://app-cicd/hello-world/secret -``` - -### `configure` Action Inputs - -| Name | Default | Environment variable | Description | -| ----------------------- | ------- | -------------------------- | -------------------------------------------------------- | -| `connect-host` | | `OP_CONNECT_HOST` | Your 1Password Connect instance URL | -| `connect-token` | | `OP_CONNECT_TOKEN` | Token to authenticate to your 1Password Connect instance | - -## Supported Runners - -You can run the action on Linux and macOS runners. Windows is currently not supported. +Similar to regular GitHub repository secrets, fields from 1Password will automatically be masked in GitHub Actions logs. If one of these values accidentally gets printed, it'll be replaced with `***`. ## Security 1Password requests you practice responsible disclosure if you discover a vulnerability. -Please file requests via [**BugCrowd**](https://bugcrowd.com/agilebits). +Please file requests through [BugCrowd](https://bugcrowd.com/agilebits). -For information about security practices, please visit our [Security homepage](https://bugcrowd.com/agilebits). +[Learn more about our security practices.](https://bugcrowd.com/agilebits) -## Getting help +## Get help + +If you find yourself stuck, [contact 1Password support](https://support.1password.com/) for help. + +[Read the full documentation](https://developer.1password.com/docs/connect/github-actions/). -If you find yourself stuck, visit our [**Support Page**](https://support.1password.com/) for help.