Load secrets from 1Password into Jenkins - 1Password Developer Docs

With the 1Password Secrets plugin for Jenkins , you can securely load secrets from 1Password as environment variables in a Jenkins CI/CD pipeline using secret references. Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. You can authenticate the plugin with a 1Password Service Account or a 1Password Connect Server.

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 service account or a Connect server. If you configure both a service account and a Connect server, the Connect server takes precedence.

Service account
Connect server

Get started

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

Install the 1Password Secrets plugin for Jenkins.
Install 1Password CLI.
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
Jenkins CLI tool
Direct upload

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

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

Refer to Use the GUI for more detailed instructions.

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

Follow the Use the CLI tool instructions.
Run the following command. Make sure to replace 1.0.0 with the correct version.
```
jenkins-plugin-cli --plugins onepassword-secrets:1.0.0
```

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

Download one of the releases .
From your Jenkins dashboard, go to Manage Jenkins > Plugins.
Select the Advanced tab.
Select the .hpi file you downloaded from the release.
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.

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
Freestyle job

To install 1Password CLI using a Jenkinsfile:

Sign in to your Jenkins instance.
Select New Item.
Enter the job details, then select Pipeline.
Configure the job details.
Scroll to Advanced Project Options > Pipeline.
Select Pipeline script.
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 .

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
Scripted Jenkinsfile

Declarative Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Install 1Password CLI') {
            steps {
                sh 'curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip"'
                sh 'unzip -o op.zip -d op-dir'
                sh 'mv -f op-dir/op /usr/local/bin'
                sh 'rm -r op.zip op-dir'
            }
        }
    }
}
# code-result
[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins in /config/workspace/Example
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Install 1Password CLI)
[Pipeline] sh
+ curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip
[Pipeline] sh
+ unzip -o op.zip -d op-dir
Archive:  op.zip
extracting: op-dir/op.sig
inflating: op-dir/op
[Pipeline] sh
+ mv -f op-dir/op /usr/local/bin
[Pipeline] sh
+ rm -r op.zip op-dir
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS

Scripted Jenkinsfile

node {
    stage('Install 1Password CLI') {
        sh '''
        ARCH="amd64"
        curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_${ARCH}_v2.24.0.zip"
        unzip -o op.zip -d op-dir
        mv -f op-dir/op /usr/local/bin
        rm -r op.zip op-dir
        '''
    }
}
# code-result
[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins in /config/workspace/Test 1Password Secrets
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Install 1Password CLI)
[Pipeline] sh
+ ARCH=amd64
+ curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip
+ unzip -o op.zip -d op-dir
Archive:  op.zip
extracting: op-dir/op.sig
inflating: op-dir/op
+ mv -f op-dir/op /usr/local/bin
+ rm -r op.zip op-dir
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS

Save the build.

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:

Sign in to your Jenkins instance.
Select New Item.
Enter the job name, then select Freestyle project.
Configure the job details.
Scroll to Build Steps, then select Add build step > Execute shell.

Add the following commands to the Execute shell build step.

ARCH="amd64"
curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_${ARCH}_v2.24.0.zip"
unzip -o op.zip -d op-dir
mv -f op-dir/op /usr/local/bin
rm -r op.zip op-dir
# code-result
Running as SYSTEM
Building in workspace /config/workspace/Example
[Test 1Password Secrets Freestyle] $ /bin/sh -xe /tmp/jenkins14763651031574634007.sh
+ ARCH=amd64
+ curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip
+ unzip -o op.zip -d op-dir
Archive:  op.zip
extracting: op-dir/op.sig
inflating: op-dir/op
+ mv -f op-dir/op /usr/local/bin
+ rm -r op.zip op-dir
Finished: SUCCESS

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:

Login to your Jenkins instance.
Select Manage Jenkins > System.
Scroll to 1Password Secrets.
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
Connect server

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

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

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

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.

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

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 references 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
Connect

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.

def config = [
        serviceAccountCredentialId: 'service-account-token',
        opCLIPath: 'op-cli-path'
]

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.

def config = [
        connectHost: 'connect-host',
        connectCredentialId: 'connect-server-token',
        opCLIPath: 'op-cli-path'
]

Service account
Connect server

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

Declarative Jenkinsfile
Scripted 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

// Configure 1Password CLI and the service account.
def config = [
        serviceAccountCredentialId: 'service-account-token',
        opCLIPath: 'op-cli-path'
]
// Define the environment variables for the values of the secrets.
// Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`.
def secrets = [
    [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'],
    [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password']
]
pipeline {
    agent any
    stages{
        stage('Push latest docker image') {
            steps {
                // Use the `withSecrets` function to access secrets.
                withSecrets(config: config, secrets: secrets) {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    }
}

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

node {
    // Configure 1Password CLI and the service account
    def config = [
            serviceAccountCredentialId: 'service-account-token',
            opCLIPath: 'op-cli-path'
    ]
    // Define the environment variables for the values of the secrets.
    // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`.
    def secrets = [
        [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'],
        [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password']
    ]
    stage('Push latest docker image') {
        // Use the `withSecrets` function to access secrets.
        withSecrets(config: config, secrets: secrets) {
            docker.withRegistry('http://somehost:5100') {
                sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                def image = docker.build('somebuild')
                image.push 'latest'
            }
        }
    }
}

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

Declarative Jenkinsfile
Scripted 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

// Configure 1Password CLI and the Connect server.
def config = [
        connectHost: 'connect-host',
        connectCredentialId: 'connect-server-token',
        opCLIPath: 'op-cli-path'
]
// Define the environment variables for the values of the secrets.
// Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`.
def secrets = [
    [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'],
    [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password']
]
pipeline {
    agent any
    stages{
        stage('Push latest docker image') {
            steps {
                // Use the `withSecrets` function to access secrets.
                withSecrets(config: config, secrets: secrets) {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    }
}

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

node {
    // Configure 1Password CLI and the Connect server.
    def config = [
            connectHost: 'connect-host',
            connectCredentialId: 'connect-server-token',
            opCLIPath: 'op-cli-path'
    ]
    // Define the environment variables for the values of the secrets.
    // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`.
    def secrets = [
        [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'],
        [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password']
    ]
    stage('Push latest docker image') {
        // Use the `withSecrets` function to access secrets.
        withSecrets(config: config, secrets: secrets) {
            docker.withRegistry('http://somehost:5100') {
                sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                def image = docker.build('somebuild')
                image.push 'latest'
            }
        }
    }
}

Jenkins Pipeline Syntax helperYou 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`. 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
Connect server

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

Declarative Jenkinsfile
Scripted Jenkinsfile

Declarative Jenkinsfile

pipeline {
    agent any
    environment {
        // Configure 1Password CLI and the service account.
        OP_SERVICE_ACCOUNT_TOKEN = credentials('service-account-token')
        OP_CLI_PATH = 'op-cli-path'
        // Define the environment variables using the secret reference `op://<vault>/<item>[/section]/<field>`.
        DOCKER_USERNAME = 'op://vault/item/username'
        DOCKER_PASSWORD = 'op://vault/item/password'
    }
    stages{
        stage('Push latest docker image') {
            steps {
                // Access 1Password secrets.
                withSecrets() {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    }
}

Scripted Jenkinsfile

node {
    def environment = [
        // Configure 1Password CLI.
        'OP_CLI_PATH = op-cli-path',
        // Define the environment variables for the values of the secrets.
        // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`.
        'DOCKER_USERNAME=op://vault/item/username',
        'DOCKER_PASSWORD=op://vault/item/password'
    ]
    // Define the service account token.
    def credentials = [
        string(credentialsId: 'service-account-token', variable: 'OP_SERVICE_ACCOUNT_TOKEN')
    ]
    withEnv(environment) {
        withCredentials(credentials) {
            stage('Push latest docker image') {
                // Use the `withSecrets` function to access secrets.
                withSecrets() {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    }
}

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

Declarative Jenkinsfile
Scripted Jenkinsfile

Declarative Jenkinsfile

pipeline {
    agent any
    environment {
        // Configure 1Password CLI and the Connect server.
        OP_CONNECT_HOST = 'connect-host'
        OP_CONNECT_TOKEN = credentials('connect-server-token')
        OP_CLI_PATH = 'op-cli-path'
        // Define the environment variables for the values of the secrets.
        // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`.
        DOCKER_USERNAME = 'op://vault/item/username'
        DOCKER_PASSWORD = 'op://vault/item/password'
    }
    stages{
        stage('Push latest docker image') {
            steps {
                // Use the `withSecrets` function to access secrets.
                withSecrets() {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    }
}

Scripted Jenkinsfile

node {
    def environment = [
        // Configure 1Password CLI and the Connect server.
        'OP_CONNECT_HOST=connect-host',
        'OP_CLI_PATH = op-cli-path',
        // Define the environment variables for the values of the secrets.
        // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`.
        'DOCKER_USERNAME=op://vault/item/username',
        'DOCKER_PASSWORD=op://vault/item/password'
    ]
    def credentials = [
        string(credentialsId: 'connect-server-token', variable: 'OP_CONNECT_TOKEN')
    ]
    withEnv(environment) {
        withCredentials(credentials) {
            stage('Push latest docker image') {
                // Use the `withSecrets` function to access secrets.
                withSecrets() {
                    docker.withRegistry('http://somehost:5100') {
                        sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100'
                        def image = docker.build('somebuild')
                        image.push 'latest'
                    }
                }
            }
        }
    }
}

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
Connect server

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

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

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

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

Integrations

​Requirements

​Get started

​Step 1: Install the 1Password Secrets plugin for Jenkins

​Step 2: Install 1Password CLI

​Step 3: Configure the 1Password Secrets plugin for Jenkins

​Configuration

​Configuration options

​Configuration scope

​Usage examples

​Use with a Jenkinsfile

​Use with environment variables

​Use in a Freestyle Job

Requirements

Get started

Step 1: Install the 1Password Secrets plugin for Jenkins

Step 2: Install 1Password CLI

Step 3: Configure the 1Password Secrets plugin for Jenkins

Configuration

Configuration options

Configuration scope

Usage examples

Use with a Jenkinsfile

Use with environment variables

Use in a Freestyle Job