Load secrets from 1Password into CircleCI

With the 1Password Secrets orb for CircleCI , you can securely load secrets from 1Password into CircleCI CI/CD pipelines using secret references. Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. CircleCI orbs are packages containing YAML configuration files. Using an orb allows you to refer to these configurations with a single line of code.

The 1Password Secrets orb for CircleCI is officially supported and maintained by 1Password, but community contributions are welcome.

You can use the orb with a 1Password Connect Server or a 1Password Service Account. See the video below for a brief introduction to using 1Password Service Accounts with CircleCI and Docker.

Requirements

The requirements for getting started with the 1Password for CircleCI orb vary depending on whether you use a service account or Connect server.

Service account
Connect

Before you use 1Password for CircleCI with a service account, you need to:

Connect credentials take precedence over service account credentials.If you’ve set the OP_CONNECT_HOST or OP_CONNECT_TOKEN environment variables alongside OP_SERVICE_ACCOUNT_TOKEN, the Connect credentials take precedence over the provided service account token. You must unset the Connect environment variables to make sure the action uses the service account token.

Get started

Service account
Connect

Set the service account token environment variable in CircleCI. On the CircleCI settings page , set the OP_SERVICE_ACCOUNT_TOKEN environment variable to token of the service account to use to load secrets.
Edit the CircleCI configuration file and make the following updates:
- Update the CircleCI config.yml file to use the 1Password for CircleCI orb.
- Specify the version number or use volatile to use the latest version number.
Add the onepassword/secrets orb to your config.yml file.
config.yml
orbs: 1password: onepassword/secrets@1.0.0
To use the latest version of 1Password Secrets orb in your project, set volatile as the version number.
config.yml
orbs: 1password: onepassword/secrets@volatile
Install 1Password CLI version 2.18.0 or later as the first step of a CircleCI job using the 1password/install-cli command. You must install the CLI in the pipeline for the 1Password CircleCI orb to function. Earlier versions of 1Password CLI don’t support service accounts. Find the latest version number in the 1Password CLI release notes.
config.yml
steps: - 1password/install-cli: version: 2.x.x

Use 1Password CLI commands in subsequent steps in the pipeline. See the following example config.yml files. Make sure to update 2.x.x to 1Password CLI version 2.18.0 or later.

Example 1
Example 2

config.yml

version: 2.1
orbs:
  1password: onepassword/secrets@1.0.0
jobs:
  deploy:
    machine:
        image: ubuntu-2204:current
    steps:
      - 1password/install-cli:
          version: 2.x.x
      - checkout
      - run:
          shell: op run -- /bin/bash
          environment:
            AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id
            AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key
          command: |
            echo "This value will be masked: $AWS_ACCESS_KEY_ID"
            echo "This value will be masked: $AWS_SECRET_ACCESS_KEY"
            ./deploy-my-app.sh
workflows:
  deploy:
    jobs:
      - deploy

config.yml

'og:description': Install 1Password CLI within a job and make it useable for all the commands following the installation.
usage:
  version: 2.1
  orbs:
    1password: onepassword/secrets@1.0.0
  jobs:
    deploy:
      machine:
        image: ubuntu-2204:current
      steps:
        - 1password/install-cli:
            version: 2.x.x
        - checkout
        - run: |
            docker login -u $(op read op://company/docker/username) -p $(op read op://company/docker/password)
            docker build -t company/app:${CIRCLE_SHA1:0:7} .
            docker push company/app:${CIRCLE_SHA1:0:7}
  workflows:
    deploy:
      jobs:
        - deploy

Set the Connect server environment variables in CircleCI.

On the CircleCI settings page , set the OP_CONNECT_HOST and OP_CONNECT_TOKEN environment variables for the Connect server to use to load secrets:

Set OP_CONNECT_TOKEN to the Connect server token.
Set OP_CONNECT_HOST to the Connect server hostname or IP address.

Edit the CircleCI configuration file.

Update the CircleCI config.yml file to use the 1Password for CircleCI orb. Make sure to specify the version number or use volatile to use the latest version number.Add the onepassword/secrets orb to your config.yml file.

config.yml

orbs:
  1password: onepassword/secrets@1.0.0

To use the latest version of 1Password Secrets orb in your project, set volatile as the version number.

config.yml

orbs:
  1password: onepassword/secrets@volatile

Install 1Password CLI.

You must install 1Password CLI in the pipeline for the 1Password CircleCI orb to function:

Install the CLI as the first step of a CircleCI job using the 1password/install-cli command.
Use 1Password CLI commands in subsequent steps in the pipeline.

See the following example config.yml files.

Example 1
Example 2

config.yml

version: 2.1
orbs:
  1password: onepassword/secrets@1.0.0
jobs:
  deploy:
    machine:
        image: ubuntu-2204:current
    steps:
      - 1password/install-cli
      - checkout
      - run:
          shell: op run -- /bin/bash
          environment:
            AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id
            AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key
          command: |
            echo "This value will be masked: $AWS_ACCESS_KEY_ID"
            echo "This value will be masked: $AWS_SECRET_ACCESS_KEY"
            ./deploy-my-app.sh
workflows:
  deploy:
    jobs:
      - deploy

config.yml

'og:description': Install 1Password CLI within a job and make it useable for all the commands following the installation.
usage:
version: 2.1
orbs:
  1password: onepassword/secrets@1.0.0
jobs:
  deploy:
    machine:
      image: ubuntu-2204:current
    steps:
      - 1password/install-cli
      - checkout
      - run: |
          docker login -u $(op read op://company/docker/username) -p $(op read op://company/docker/password)
          docker build -t company/app:${CIRCLE_SHA1:0:7} .
          docker push company/app:${CIRCLE_SHA1:0:7}
workflows:
  deploy:
    jobs:
      - deploy

Reference

The following sections document the 1Password for CircleCI orb commands and the secret reference syntax.

Commands

There are three commands to use when you configure your orb: 1password/install-cli, 1password/exec, and 1password/export.

Only some commands mask secrets.Both the 1password/exec orb command and the op run shell wrapper automatically mask secrets from the CircleCI log output. If secrets accidentally get logged, 1Password replaces them with <concealed by 1Password>. The 1password/export command doesn’t mask secrets.

Command	Description	Masks secrets
`1password/install-cli`	Installs 1Password CLI. You must use this command as a step to use 1Password CLI commands in subsequent steps.	N/A
`1password/exec`	Loads secrets on demand and executes the commands requiring secrets. See loading secrets with the `exec` command.	Yes
`1password/export`	Loads secrets with references exported in the environment and makes them available to subsequent steps of the job. See loading secrets with the `export` command.	No

Secret reference syntax

You can make secrets available to CircleCI jobs and steps by including references to them in the environment using secret references. Secret reference URIs point to where a secret is saved in your 1Password account using the names (or unique identifiers) of the vault, item, section, and field where the information is stored.

op://vault-name/item-name/[section-name/]field-name

Visit the secret reference syntax documentation to access examples and learn more about referencing secrets.

Usage examples

Explore the following sections to learn about specific use case examples for the 1Password CircleCI orb.

Load secrets with exec
Load secrets with export

Load secrets with the `exec` command

To load secrets with the 1password/exec command:

Install 1Password CLI with 1password/install-cli. If you’re using a service account, make sure to set the 1Password CLI version to 2.18.0 or later.
Use the 1password/exec command to load secrets on demand and execute commands that require secrets.

After you add the 1password/exec command as a step in your job, subsequent steps of the job can access secrets. The following example shows how to use the 1password/exec command to resolve variables at the job level. The exec command automatically masks any secrets or sensitive values that might be accidentally logged.

config.yml

version: 2.1
orbs:
  1password: onepassword/secrets@1.0.0

jobs:
  deploy:
    machine:
        image: ubuntu-2204:current
    environment:
      AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id
      AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key
    steps:
      - checkout
      - 1password/install-cli:
          version: 2.x.x
      - 1password/exec:
          command: |
            echo "This value will be masked: $AWS_ACCESS_KEY_ID"
            echo "This value will be masked: $AWS_SECRET_ACCESS_KEY"
            ./deploy-my-app.sh
workflows:
  deploy:
    jobs:
      - deploy

Load secrets with the `export` command

To load secrets with the 1password/export command:

Install 1Password CLI with 1password/install-cli. If you’re using a service account, make sure to set the 1Password CLI version to 2.18.0 or later.
Use the 1password/export command to load the secret references exported in the environment.
Access secrets in subsequent steps of the job.

The following example shows how to use the 1password/export command to resolve variables at the job level.

config.yml

version: 2.1
orbs:
  1password: onepassword/secrets@1.0.0

jobs:
  deploy:
    machine:
        image: ubuntu-2204:current
    steps:
      - checkout
      - 1password/install-cli
          version: 2.x.x
      - 1password/export:
            var-name: AWS_ACCESS_KEY_ID
            secret-reference: op://company/app/aws/access_key_id
      - 1password/export:
            var-name: AWS_SECRET_ACCESS_KEY
            secret-reference: op://company/app/aws/secret_access_key
      - run:
          command: |
            echo "This value will not be masked: $AWS_ACCESS_KEY_ID"
            echo "This value will not be masked: $AWS_SECRET_ACCESS_KEY"
            ./deploy-my-app.sh
workflows:
  deploy:
    jobs:
      - deploy

​Requirements

​Get started

​Reference

​Commands

​Secret reference syntax

​Usage examples

​Load secrets with the exec command

​Load secrets with the export command

Requirements

Get started

Reference

Commands

Secret reference syntax

Usage examples

Load secrets with the `exec` command

Load secrets with the `export` command