> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Load secrets from 1Password into CircleCI

export const YouTubeVideo = ({src, title, alt}) => {
  return <Frame>
      <iframe className="w-full aspect-video rounded-xl" src={src} title={alt ?? title} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>
    </Frame>;
};

With the [1Password Secrets orb for CircleCI <Icon icon="arrow-up-right-from-square" />](https://circleci.com/developer/orbs/orb/onepassword/secrets), you can securely load secrets from 1Password into CircleCI CI/CD pipelines using [secret references](/cli/secret-reference-syntax). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code.

[CircleCI orbs <Icon icon="arrow-up-right-from-square" />](https://circleci.com/docs/orb-intro/) are packages containing YAML configuration files. Using an orb allows you to refer to these configurations with a single line of code.

<Note>
  The [1Password Secrets orb for CircleCI <Icon icon="github" />](https://github.com/1password/secrets-orb) is officially supported and maintained by 1Password, but community contributions are welcome.
</Note>

You can use the orb with a [1Password Connect Server](/connect/) or a [1Password Service Account](/service-accounts/). See the video below for a brief introduction to using 1Password Service Accounts with CircleCI and Docker.

<YouTubeVideo src="https://www.youtube.com/embed/xnv5qBjfisU" title="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.

<Tabs queryString="workflow-type" groupId="requirements">
  <Tab title="Service account">
    Before you use 1Password for CircleCI with a service account, you need to:

    * [Sign up for 1Password.](https://1password.com/pricing/password-manager)
    * [Create a service account.](/service-accounts/)
    * Create a [CircleCI <Icon icon="arrow-up-right-from-square" />](https://circleci.com/) account.
  </Tab>

  <Tab title="Connect">
    Before you use 1Password for CircleCI with a Connect server, you need to:

    * [Sign up for 1Password.](https://1password.com/pricing/password-manager)
    * [Create and deploy a Connect server.](/connect/get-started/#step-1)
    * Create a [CircleCI <Icon icon="arrow-up-right-from-square" />](https://circleci.com/) account.
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

## Get started

<Tabs queryString="workflow-type" groupId="get-started">
  <Tab title="Service account">
    1. Set the service account token environment variable in CircleCI.

       On the [CircleCI settings page <Icon icon="arrow-up-right-from-square" />](https://circleci.com/docs/introduction-to-the-circleci-web-app/#project-settings), 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 <Icon icon="arrow-up-right-from-square" />](https://circleci.com/docs/config-intro/) 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.

       ```yaml config.yml theme={null}
       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.

       ```yaml config.yml theme={null}
       orbs:
         1password: onepassword/secrets@volatile
       ```

    3. Install 1Password CLI version **2.18.0 or later** as the first step of a CircleCI job using the `1password/install-cli` [command](#commands). 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](https://releases.1password.com/developers/cli/).

       ```yaml config.yml theme={null}
       steps:
           - 1password/install-cli:
               version: 2.x.x
       ```

    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](https://releases.1password.com/developers/cli/).

           <Tabs queryString="install-example" groupId="install-example">
             <Tab title="Example 1">
               ```yaml config.yml theme={null}
               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
               ```
             </Tab>

             <Tab title="Example 2">
               ```yaml config.yml theme={null}
               '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
               ```
             </Tab>
           </Tabs>
  </Tab>

  <Tab title="Connect">
    1. Set the Connect server environment variables in CircleCI.

    On the [CircleCI settings page <Icon icon="arrow-up-right-from-square" />](https://circleci.com/docs/introduction-to-the-circleci-web-app/#project-settings), 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.

    2. Edit the CircleCI configuration file.

    Update the [CircleCI `config.yml` file <Icon icon="arrow-up-right-from-square" />](https://circleci.com/docs/config-intro/) 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.

    ```yaml config.yml theme={null}
    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.

    ```yaml config.yml theme={null}
    orbs:
      1password: onepassword/secrets@volatile
    ```

    3. Install 1Password CLI.

    You must install [1Password CLI](/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](#commands).
    * Use 1Password CLI commands in subsequent steps in the pipeline.

    See the following example `config.yml` files.

    <Tabs queryString="install-example" groupId="install-example">
      <Tab title="Example 1">
        ```yaml config.yml theme={null}
        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
        ```
      </Tab>

      <Tab title="Example 2">
        ```yaml config.yml theme={null}
        '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
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Reference

The following sections document the 1Password for CircleCI orb [commands](#commands) and the [secret reference syntax](#secret-reference-syntax).

### Commands

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

<Warning>
  Only some commands mask secrets.

  Both the `1password/exec` orb command and the [`op run`](/cli/reference/commands/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.
</Warning>

| 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.                                                                                 | <span class="badge badge--secondary">N/A</span> |
| `1password/exec`        | Loads secrets on demand and executes the commands requiring secrets. <br /><br /> See [loading secrets with the `exec` command](#load-exec).                                                   | <span class="badge badge--primary">Yes</span>   |
| `1password/export`      | Loads secrets with references exported in the environment and makes them available to subsequent steps of the job. <br /><br /> See [loading secrets with the `export` command](#load-export). | <span class="badge badge--secondary">No</span>  |

### 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](/cli/reference/#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored.

```shell theme={null}
op://vault-name/item-name/[section-name/]field-name
```

Visit the [secret reference syntax](/cli/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-exec)
* [Load secrets with `export`](#load-export)

<h3 id="load-exec">
  Load secrets with the `exec` command
</h3>

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](https://releases.1password.com/developers/cli/) 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.

```yaml config.yml theme={null}
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
```

<h3 id="load-export">
  Load secrets with the `export` command
</h3>

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](https://releases.1password.com/developers/cli/) to `2.18.0` or later.

2. Use the `1password/export` command to load the [secret references](#secret-reference-syntax) 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.

```yaml config.yml theme={null}
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
```