Load secrets from 1Password into Jenkins

The 1Password Secrets plugin for Jenkins lets you load secrets from a 1Password Service Account or 1Password Connect Server as environment variables into a Jenkins CI/CD pipeline.

info

The 1Password Jenkins plugin is officially supported and maintained by 1Password. Community contributions are welcome. View the repository on GitHub.

Requirements

You can use the 1Password Secrets plugin for Jenkins with either a Connect server or a service account. If you configure both a Connect server and a service account, the Connect server takes precedence.

Service account

• Sign up for 1Password.
• Create a service account.
• Have a Jenkins instance up and running.

Connect server

• Sign up for 1Password.
• Create and deploy a Connect server.
• Have a Jenkins instance up and running.

Get started

To get started with the 1Password Secrets plugin for Jenkins:

1. Install the 1Password Secrets plugin for Jenkins.
2. Install 1Password CLI.
3. Configure the 1Password Secrets plugin for Jenkins.

Step 1: Install the 1Password Secrets plugin for Jenkins

You have several available options to install the 1Password Secrets plugin for Jenkins. You can use the Jenkins GUI (graphical user interface), the Jenkins CLI tool, or a direct upload.

Jenkins GUI

To install the 1Password Secrets plugin for Jenkins using the GUI:

1. Sign in to your Jenkins instance.
2. From your Jenkins dashboard, go to Manage Jenkins > Plugins.
3. Select the Available plugins tab.
4. Search for onepassword-secrets.
5. Select the 1Password Secrets plugin for Jenkins, then select Install.

Refer to Use the GUI for more detailed instructions.

Jenkins CLI tool

To install the 1Password Secrets plugin for Jenkins using the CLI tool:

1. Follow the Use the CLI tool instructions.

2. Run the following command. Make sure to replace 1.0.0 with the correct version.

Direct upload

To install the 1Password Secrets plugin for Jenkins using a direct upload:

1. Download one of the releases .
2. From your Jenkins dashboard, go to Manage Jenkins > Plugins.
3. Select the Advanced tab.
4. Choose the .hpi file you downloaded from the release.
5. Select Deploy.

Refer to Use direct upload for more detailed instructions.

Step 2: Install 1Password CLI

The 1Password Secrets plugin for Jenkins relies on 1Password CLI. You must install 1Password CLI on the same machine that runs the Jenkins CI/CD pipeline.

You can install 1Password CLI using a Jenkinsfile or using a Freestyle job. Either of these methods can install 1Password CLI in the same pipeline as the 1Password Secrets plugin for Jenkins or in a separate pipeline.

info

If you install 1Password CLI in the same pipeline, you will need to add the 1Password CLI installation script before you make any calls to the plugin.

If you install 1Password CLI in a separate pipeline, you will need to set the 1Password CLI path to the workspace where you performed the installation in your configuration.

Jenkinsfile

To install 1Password CLI using a Jenkinsfile:

1. Sign in to your Jenkins instance.

2. Select New Item.

3. Enter the job details, then select Pipeline.

4. Configure the job details.

5. Scroll to Advanced Project Options > Pipeline.

6. Select Pipeline script.

7. Add the code to install 1Password CLI to the Script field.

   You can install 1Password CLI with a Jenkinsfile using declarative or scripted Jenkins pipeline syntax .

   info

   The following examples show how to install 1Password CLI version 2.24 on a Linux amd64 machine. Make sure to change the example scripts to match your platform and use the latest release of 1Password CLI.

   Declarative Jenkinsfile

   Declarative Jenkinsfile

   See result...

   Scripted Jenkinsfile

   Scripted Jenkinsfile

   See result...

8. Save the build.

Freestyle job

caution

Freestyle jobs don't let you set both the configuration and secrets at the job level. 1Password recommends using a Jenkinsfile rather than a Freestyle job. See Migrating from chained Freestyle jobs to Pipelines .

To install 1Password CLI using a Freestyle job:

1. Sign in to your Jenkins instance.

2. Select New Item.

3. Enter the job name, then select Freestyle project.

4. Configure the job details.

5. Scroll to Build Steps, then select Add build step > Execute shell.

6. Add the following commands to the Execute shell build step.

   See result...

7. Save the build.

Step 3: Configure the 1Password Secrets plugin for Jenkins

You can configure the 1Password Secrets plugin for Jenkins from the Jenkins dashboard:

1. Login to your Jenkins instance.
2. Select Manage Jenkins > System.
3. Scroll to 1Password Secrets.
4. Set the 1Password CLI path to the location of the 1Password CLI executable.
   The example script uses /usr/local/bin/op.

The remaining configuration steps depend on whether you use a service account or a Connect server.

Service account

You must add at least one Service Account Credential to use a service account with the 1Password Secrets plugin for Jenkins.

1. Select Add > Jenkins under the Service Account Credential.
2. Set the Domain.
3. Set the Kind to Secret text.
   The plugin only supports secret text .
4. Set the Scope.
5. Set the Secret to the service account token.
6. You can leave the ID and Description empty.
7. Select Add.

Connect server

You must specify the Connect Host value and add at least one Connect Credential to use a service account with the 1Password Secrets plugin for Jenkins.

1. Set Connect Host to the IP address, hostname, or URL of the Connect server.
2. Select Add > Jenkins under the Connect Credential.
3. Set the Domain.
4. Set the Kind to Secret text.
   The plugin only supports secret text .
5. Set the Scope.
6. Set the Secret to the Connect server token.
7. You can leave the ID and Description empty.
8. Select Add.

For example configurations and pipeline scripts, go to Usage examples.

info

If you configure both a Connect server and a service account, the Connect server takes precedence.

Configuration

The following sections document the available configuration options and configuration scopes.

info

If you install 1Password CLI in the same pipeline, you will need to add the 1Password CLI installation script before you make any calls to the plugin.

If you install 1Password CLI in a separate pipeline, you will need to set the 1Password CLI path to the workspace where you performed the installation in your configuration.

Configuration options

The 1Password Secrets plugin for Jenkins has configuration options for 1Password CLI, Connect servers, and service accounts.

Setting	Description
Connect Host	The hostname, IP address, or URL of the Connect server.
Connect Credential	The Connect server token to authenticate with the Connect server. This setting is a Jenkins secret text credential .
Service Account Credential	The service account token to authenticate with the service account. This setting is a Jenkins secret text credential .
1Password CLI path	The path to the 1Password CLI executable. The default location is /usr/local/bin/op

Configuration scope

You can configure the 1Password Secrets plugin for Jenkins globally, per folder, or per job.

Level	Description
Global	Global-level configurations impact all jobs in all folders. To configure the 1Password Secrets plugin for Jenkins globally, add it to your global configuration.
Folder	Folder-level configurations impact all jobs within the folder. To configure the 1Password Secrets plugin for Jenkins for a specific folder, add it to the folder configuration.
Job	Job-level configurations only impact the jobs you configure. To configure the 1Password Secrets plugin for Jenkins for a single job, configure the plugin in the Jenkinsfile or Freestyle job.

The configuration priority is highest for job-level configurations and lowest for global configurations. The more specific the level, the higher the priority. This means you can have a default configuration at a broader level and override it at more specific levels.

For example, if you configure a service account (service account A) globally, but override it with a different service account (service account B) in a job-level configuration, the job will use the second service account (service account B).

info

If you configure both a Connect server and a service account, the Connect server takes precedence.

Usage examples

The following sections cover several use case examples for the 1Password Secrets plugin for Jenkins:

• Use with a Jenkinsfile
• Use with environment variables
• Use in a Freestyle job

Use with a Jenkinsfile

You can access secrets within the Jenkins pipeline using secret reference syntax with the withSecrets function. This function receives the configuration and list of 1Password secrets and loads them as parameters. Explore the following examples to learn how to use the withSecrets function in various contexts.

About the configuration step...

Service account

The configuration at the beginning of the Jenkinsfile to configure the service account and 1Password CLI is optional. If you don't provide a configuration, the 1Password Secrets plugin uses a more broadly scoped configuration.

Make sure to replace service-account-token with the service account token and op-cli-path with the path you installed the 1Password CLI to (if you used a custom location). See Configuration.

Connect

The configuration at the beginning of the Jenkinsfile to configure the Connect server and 1Password CLI is optional. If you don't provide a configuration, the 1Password Secrets plugin uses a more broadly scoped configuration.

Make sure to replace connect-server-token with the Connect server token, connect-host with the Connect server IP address, and op-cli-path with the path you installed the 1Password CLI to (if you used a custom location). See Configuration.

Service account

The following examples show how to use the withSecrets function in a Jenkinsfile with a 1Password Service Account.

Declarative Jenkinsfile

The following declarative Jenkinsfile shows how to use the withSecrets function with a service account. It first defines environment variables to hold the secret values, then uses the withSecrets function to access and assign the values.

Declarative Jenkinsfile

Scripted Jenkinsfile

The following scripted Jenkinsfile shows how to use the withSecrets function with a service account. It first defines environment variables to hold the secret values, then uses the withSecrets function to access and assign the values.

Scripted Jenkinsfile

Connect server

The following examples show how to use the withSecrets function in a Jenkinsfile with a 1Password Connect Server.

Declarative Jenkinsfile

The following declarative Jenkinsfile shows how to use the withSecrets function with a Connect server. It first defines environment variables to hold the secret values, then uses the withSecrets function to access and assign the values.

Declarative Jenkinsfile

Scripted Jenkinsfile

The following scripted Jenkinsfile shows how to use the withSecrets function with a Connect server. It first defines environment variables to hold the secret values, then uses the withSecrets function to access and assign the values.

Scripted Jenkinsfile

Jenkins Pipeline Syntax helper

You can also use the Jenkins Pipeline Syntax helper to create a pipeline script.

Use with environment variables

The 1Password Secrets plugin for Jenkins lets you use environment variables to get configuration and secrets. The following examples show how to use environment variables with the 1Password Secrets plugin for Jenkins.

You must set the environment variables in the environment block. The following table describes each environment variable.

Variable	Required	Description
OP_CLI_PATH	Always required.	The path where you installed the 1Password CLI. If you followed the 1Password CLI installation instruction, set this value to /usr/local/bin/op. The example scripts on this page set this value to op-cli-path.
OP_SERVICE_ACCOUNT_TOKEN	Required if using a service account.	The service account token of the service account to use. The example scripts on this page set this value to service-account-token variable.
OP_CONNECT_HOST	Required if using a Connect server.	The IP address, hostname, or URL of the Connect server to use. The example scripts on this page set this value to connect-server-host.
OP_CONNECT_TOKEN	Required if using a Connect server.	The Connect server token of the Connect server to use. The example scripts on this page set this value to connect-server-token.

If you don't configure these environment variables, the 1Password Secrets plugin uses a more broadly scoped configuration.

Service account

The following examples show how to use a service account with environment variables in a Jenkinsfile.

Declarative Jenkinsfile

Declarative Jenkinsfile

Scripted Jenkinsfile

Scripted Jenkinsfile

Connect server

The following examples show how to use a Connect server with environment variables in a Jenkinsfile.

Declarative Jenkinsfile

Declarative Jenkinsfile

Scripted Jenkinsfile

Scripted Jenkinsfile

Use in a Freestyle Job

You can use the Jenkins Pipeline Syntax helper to set environment variables and access secrets in a Freestyle job.

Service account

Use the Jenkins Pipeline Syntax helper to use a service account in a Freestyle job:

1. From the Freestyle job in Jenkins, go to the Steps section.
2. Set 1Password CLI path to the location where you installed 1Password CLI.
   The example script uses /usr/local/bin/op.
3. Set Service Account Credential to the service account token.
4. Select Add a 1Password secret.
5. Set the Environment variable for the secret.
6. Set Secret reference.
   Use secret reference syntax to point to the 1Password secret.
7. Select Generate Pipeline Script.

Connect server

Use the Jenkins Pipeline Syntax helper to use a Connect server in a Freestyle job:

1. From the Freestyle job in Jenkins, go to the Steps section.
2. Set 1Password CLI path to the location where you installed 1Password CLI.
   The example script uses /usr/local/bin/op.
3. Set Connect Host to the Connect server IP address or hostname.
4. Set Connect Credential to the Connect server token.
5. Select Add a 1Password secret.
6. Set the Environment variable for the secret.
7. Set Secret reference.
   Use secret reference syntax to point to the 1Password secret.
8. Select Generate Pipeline Script.