Skip to main content

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.

info

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.

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

caution

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​

  1. 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.

  2. 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

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

    config.yml

  3. 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

  4. 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.

    config.yml

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.

caution

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.

CommandDescriptionMasks secrets
1password/install-cliInstalls 1Password CLI. You must use this command as a step to use 1Password CLI commands in subsequent steps.N/A
1password/execLoads secrets on demand and executes the commands requiring secrets.

See loading secrets with the exec command.		Yes
1password/exportLoads 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.

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 the exec command​

To load secrets with the 1password/exec command:

  1. 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.

  2. 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

Load secrets with the export command​

To load secrets with the 1password/export command:

  1. 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.

  2. Use the 1password/export command to load the secret references exported in the environment.

  3. 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

Was this page helpful?