1Password Secrets plugin for Jenkins

This plugin loads secrets from a 1Password Connect server or 1Password Service Account as environment variables into the Jenkins CI/CD pipeline. The loaded secrets can only be accessed witin the scope of the plugin.

Read more on the 1Password Developer Portal.

Prerequisites

If you're using 1Password Connect, then you'll need to:

• Set up a Secrets Automation workflow.
• Deploy 1Password Connect in your infrastructure.

If you're using 1Password Service Accounts, then you'll need to create a service account.

Install the 1Password CLI

This plugin relies on the 1Password CLI. You need to Install 1Password CLI on your host machine.

If you plan to install 1Password CLI in the same pipeline where you'll use the plugin, you need to add the installation script before you make any calls to the plugin.

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

Here's an example script to install the 1Password CLI version 2.41.1 on a Linux amd64 host:

curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.41.1/op_linux_amd64_v2.41.1.zip
unzip -o op.zip
rm op.zip

Declarative Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Install 1Password CLI') {
            sh '''
            curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.41.1/op_linux_amd64_v2.41.1.zip
            unzip -o op.zip
            rm op.zip
            '''
        }
    }
}

Scripted Jenkinsfile

node {
    stage('Install 1Password CLI') {
        sh '''
        curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.41.1/op_linux_amd64_v2.41.1.zip
        unzip -o op.zip
        rm op.zip
        '''
    }
}

See the most recent 1Password CLI release.

NOTE: If you want to use Service Accounts, then you'll need to install the latest version of the 1Password CLI (2.18.0 or later).

Configuration

You can configure the plugin at three different levels:

• Global: Add to your global configuration. Impacts all folders and jobs.
• Folder: Configuration applies to the folder where your job is running.
• Job level: Configure the plugin either on your freestyle project job or directly in the Jenkinsfile. Applies only to that job.

The lower the level, the higher its priority. For example, if you configure a Connect server host in your global settings, but override it in a particular job, the Connect host configured at the job level will be used.

NOTE: If both a Connect server and service account are configured, the Connect server will take precedence.

Configuration options

On your Jenkins configuration page, you'll see the following options:

Setting	Description
Connect Host	The host where the Connect server is deployed.
Connect Credential	A Secret text credential type that contains the 1Password Connect Token to get secrets from 1Password.
Service Account Credential	A Secret text credential type that contains the 1Password Service Account Token to get secrets from 1Password.
1Password CLI path	The path to the 1Password CLI binary.

Jenkins 1Password Secrets configuration interface:

Create a Connect Credential by clicking Add next to Connect Token:

or Create a Service Account Credential by clicking Add next to Service Account Token:

Usage

With a Jenkinsfile

To access secrets within the Jenkins pipeline, use the withSecrets function. This function receives the configuration and list of 1Password secrets to be loaded as parameters.

Here's an example of a declarative Jenkinsfile in which we configure to use Connect:

// (Optional) Define the configuration values for your Connect Instance.
// If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global).
// Note the most granularly scoped configuration will have priority over all other configurations.
def config = [
        connectHost: 'http://localhost:8080',
        connectCredentialId: 'my-connect-credential-id',
        opCLIPath: '/path/to/op'
]

// Define the environment variables that will have the values of the secrets
// read using the secret reference `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 {
                // Environment variables will be set with the secrets specified by
                // the secret references within this block only.
                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'
                    }
                }
            }
        }
    }
}

node {
    // (Optional) Define the configuration values for your Connect Instance.
    // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global).
    // Note the most granularly scoped configuration will have priority over all other configurations.
    def config = [
        connectHost: 'http://localhost:8080',
        connectCredentialId: 'my-connect-credential-id',
        opCLIPath: '/path/to/op'
    ]

    // Define the environment variables that will have the values of the secrets
    // read using the secret reference `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') {
        // Environment variables will be set with the secrets specified by
        // the secret references within this block only.
        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'
            }
        }
    }
}

Here's an example of a declarative Jenkinsfile in which we configure to use Service Accounts:

// (Optional) Define the service account token that will be used.
// If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global).
// Note the most granularly scoped configuration will have priority over all other configurations.
def config = [
        serviceAccountCredentialId: 'my-service-account-credential-id',
        opCLIPath: '/path/to/op'
]

// Define the environment variables that will have the values of the secrets
// read using the secret reference `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 {
                // Environment variables will be set with the secrets specified by
                // the secret references within this block only.
                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'
                    }
                }
            }
        }
    }
}

node {
    // (Optional) Define the service account token that will be used.
    // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global).
    // Note the most granularly scoped configuration will have priority over all other configurations.
    def config = [
        serviceAccountCredentialId: 'my-service-account-credential-id',
        opCLIPath: '/path/to/op'
    ]

    // Define the environment variables that will have the values of the secrets
    // read using the secret reference `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') {
        // Environment variables will be set with the secrets specified by
        // the secret references within this block only.
        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'
            }
        }
    }
}

You can use the Jenkins Pipeline Syntax helper to generate a pipeline script, if you prefer.

With environment variables

The plugin also allows you to use environment variables to get configuration and secrets.

For the configuration, you need to set up the following environment variables:

• OP_CONNECT_HOST
• OP_CONNECT_TOKEN
• OP_CLI_PATH

Here's an example configuration for Connect in a declarative Jenkinsfile:

pipeline {
    agent any
    environment {
        // (Optional) Define the configuration values for your Connect Instance as environment variables.
        // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global).
        // Note the most granularly scoped configuration will have priority over all other configurations.
        OP_CONNECT_HOST = 'http://localhost:8080'
        OP_CONNECT_TOKEN = credentials('my-connect-credential-id')
        OP_CLI_PATH = '/path/to/op'

        // Define the environment variables that will have the values of the secrets
        // read 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 {
                // Environment variables will be set with the secrets specified by
                // the secret references within this block only.
                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'
                    }
                }
            }
        }
    }
}

node {
    def environment = [
        // (Optional) Define the configuration values for your Connect Instance as environment variables.
        // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global).
        // Note the most granularly scoped configuration will have priority over all other configurations.
        'OP_CONNECT_HOST=http://localhost:8080',
        'OP_CLI_PATH = /path/to/op',

        // Define the environment variables that will have the values of the secrets
        // read using the secret reference `op://<vault>/<item>[/section]/<field>`
        'DOCKER_USERNAME=op://vault/item/username',
        'DOCKER_PASSWORD=op://vault/item/password'
    ]

    def credentials = [
        string(credentialsId: 'my-connect-credential-id', variable: 'OP_CONNECT_TOKEN')
    ]

    withEnv(environment) {
        withCredentials(credentials) {
            stage('Push latest docker image') {
                // Environment variables will be set with the secrets specified by
                // the secret reference within this block only.
                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'
                    }
                }
            }
        }
    }
}

Here's an example configuration for Service Accounts in a declarative Jenkinsfile:

pipeline {
    agent any
    environment {
        // (Optional) Define the service account token that will be used.
        // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global).
        // Note the most granularly scoped configuration will have priority over all other configurations.
        OP_SERVICE_ACCOUNT_TOKEN = credentials('my-service-account-credential-id')
        OP_CLI_PATH = '/path/to/op'

        // Define the environment variables that will have the values of the secrets
        // read 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 {
                // Environment variables will be set with the secrets specified by
                // the secret references within this block only.
                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'
                    }
                }
            }
        }
    }
}

node {
    def environment = [
        'OP_CLI_PATH = /path/to/op',

        // Define the environment variables that will have the values of the secrets
        // read using the secret reference `op://<vault>/<item>[/section]/<field>`
        'DOCKER_USERNAME=op://vault/item/username',
        'DOCKER_PASSWORD=op://vault/item/password'
    ]

    // (Optional) Define the service account token that will be used.
    // If no configuration provided, a more broadly scoped configuration will be used (e.g. folder or global).
    // Note the most granularly scoped configuration will have priority over all other configurations.
    def credentials = [
        string(credentialsId: 'my-service-account-credential-id', variable: 'OP_SERVICE_ACCOUNT_TOKEN')
    ]

    withEnv(environment) {
        withCredentials(credentials) {
            stage('Push latest docker image') {
                // Environment variables will be set with the secrets specified by
                // the secret reference within this block only.
                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'
                    }
                }
            }
        }
    }
}

In Freestyle Jobs

If you use Freestyle Jobs, consider migrating to Jenkinsfile), With Jenkinsfile, you can set up both the configuration and the secrets you need at the job level.

To add a secret to your Freestyle Job, click the "Add a 1Password secret" button in the 1Password Secrets section, then fill out the following fields:

Field	Description
Environment variable	The name of the environment variable that will contain the loaded secret.
Secret reference	The 1Password secret reference using secret reference syntax: op://<vault>/<item>[/section]/<field>

The secrets are available as environment variables.

Requirements

• Jenkins 2.555.3 or newer
• To build the plugin: Maven 3.9.6 or newer and JDK 21 or 25

Security

1Password requests you practice responsible disclosure if you discover a vulnerability.

Please file requests by sending an email to [email protected].

Getting help

If you find yourself stuck, visit our Support Page for help.