This plugin loads secrets from 1Password Connect as environment variables into the Jenkins pipeline. The loaded secrets can only be accessed witin the scope of the plugin.
Read more on the 1Password Developer Portal.
Prerequisites
- 1Password Connect deployed in your infrastructure.
Install the 1Password CLI
This plugin relies on the 1Password CLI. You need to Install 1Password CLI on your host machine.
Here's an example script to install the 1Password CLI version 2.8.0
on a Linux amd64
host:
curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.8.0/op_linux_amd64_v2.8.0.zip
unzip -o op.zip
rm op.zip
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 you configuration.
Example installation via pipeline script
Declarative Jenkinsfile
pipeline {
agent any
stages {
stage('Install 1Password CLI') {
sh '''
curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.8.0/op_linux_amd64_v2.8.0.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.8.0/op_linux_amd64_v2.8.0.zip
unzip -o op.zip
rm op.zip
'''
}
}
See the most recent 1Password CLI release.
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. 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.
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. |
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:
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:
// (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'
}
}
}
}
}
}
Scripted Jenkinsfile
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'
}
}
}
}
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 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'
}
}
}
}
}
}
Scripted Jenkinsfile
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'
}
}
}
}
}
}
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
- Maven > 3.3.9
- Oracle JDK 11 or higher
Security
1Password requests you practice responsible disclosure if you discover a vulnerability.
Please file requests via BugCrowd.
For information about security practices, please visit our Security homepage.
Getting help
If you find yourself stuck, visit our Support Page for help.