Managing Credentials
1. Adding Username/Password Credentials
| Field | Description | Example Value |
|---|---|---|
| Username | Username for the credential | admin |
| Password | Password for the credential | secret123 |
| ID | Unique identifier for the credential | my-credentials |
Example: Adding Username/Password Credentials via UI
1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Credentials"
3. Select the appropriate domain (e.g., "System")
4. Click "Add Credentials"
5. Choose "Username with password" type
6. Fill in the username and password fields
7. Provide an ID for the credential (e.g., "my-credentials")
8. Save the credentials
Note: Ensure that the credential ID is unique within the domain to avoid conflicts.
2. Adding SSH Keys
| Field | Description | Example |
|---|---|---|
| SSH Key | Private SSH key content (PEM format) | -----BEGIN RSA PRIVATE KEY-----<br>MIIEowIBAAKCAQEA...<br>-----END RSA PRIVATE KEY----- |
| Passphrase (optional) | Passphrase for encrypted private key | mySecurePassphrase |
| Description | Human-readable description for the credential | Deployment key for prod server |
Example: Adding SSH Key via Jenkins UI
1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Credentials"
3. Select "System" > "Global credentials (unrestricted)"
4. Click "Add Credentials"
5. Choose "SSH Username with private key"
6. Paste the private key content
7. Enter passphrase if required
8. Add a description
9. Save credentials
Note: Ensure the private key is in PEM format and has proper permissions (e.g.,
chmod 600) before adding to Jenkins.
Warning: Never store or expose private keys in plain text outside of Jenkins' secure credential storage.
3. Adding Secret Text Credentials
| Field | Description | Example Value |
|---|---|---|
| Credentials ID | Unique identifier for the credential | my-secret-text-id |
| Secret Text | The actual secret text to store | my-super-secret-password |
| Description (Optional) | Human-readable description of the credential | Database password for production |
Example: Adding Secret Text via UI
1. Navigate to Jenkins Dashboard
2. Click "Manage Jenkins"
3. Select "Manage Credentials"
4. Choose the appropriate store (e.g., "System")
5. Click "Add Credentials"
6. Select "Secret Text" from the Kind dropdown
7. Fill in the ID, Secret Text, and optional Description
8. Click "OK"
Note: The secret text is encrypted at rest using Jenkins' built-in encryption.
Warning: Never expose secret text in logs or console output.
4. Adding Secret Files
| Field | Description | Example |
|---|---|---|
| File Content | Content of the secret file to be stored | <?xml version="1.0" encoding="UTF-8"?> |
| File Name | Name of the secret file in Jenkins | my-config.xml |
Example: Adding a Secret File via UI
1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Credentials"
3. Select the appropriate store (e.g., "System")
4. Click "Add Credentials"
5. Choose "Secret File" from the Kind dropdown
6. Paste file content into the "File" field
7. Enter a description in the "Description" field
8. Click "OK"
Note: Secret files are stored securely in Jenkins and can be accessed by jobs using the
withCredentials step.
5. Adding Certificate Credentials
| Field | Description | Example Value |
|---|---|---|
| Name | Unique identifier for the credential within Jenkins | my-certificate |
| Type | Must be set to Certificate |
Certificate |
| Certificate | PEM-encoded certificate content or file path | |
| Private Key | PEM-encoded private key content or file path | |
| Password (if encrypted) | Password to decrypt the private key | mySecretPassword |
Example: Adding Certificate Credential via UI
1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Credentials"
3. Select the appropriate domain (e.g., System)
4. Click "Add Credentials"
5. Choose "Certificate" from the Kind dropdown
6. Fill in the Name, Certificate, and Private Key fields
7. Save the credential
Note: Ensure that the certificate and private key are in PEM format. Jenkins does not support PKCS#12 (.p12) files directly.
6. Using Credentials Binding
| Property | Description | Usage |
|---|---|---|
| credentialsId | Identifier for the credential in Jenkins | withCredentials([usernamePassword(credentialsId: 'my-cred', variable: 'USER_PASS')]) { ... } |
| variable | Environment variable name to bind the credential to | withCredentials([usernamePassword(credentialsId: 'my-cred', variable: 'USER_PASS')]) { echo env.USER_PASS } |
Example: Binding Username and Password
withCredentials([usernamePassword(credentialsId: 'my-cred', variable: 'USER_PASS')]) {
sh "echo $USER_PASS"
}
Example: Binding SSH Key
withCredentials([sshUserPrivateKey(credentialsId: 'ssh-key', keyFileVariable: 'SSH_KEY')]) {
sh "ssh -i $SSH_KEY user@host"
}
Note: Credentials binding is available in Jenkins Pipeline DSL and supports various credential types including username/password, SSH private keys, and secret text.
7. Scoping Credentials
| Scope | Description | Usage |
|---|---|---|
| Global | Available to all jobs and nodes in the Jenkins instance | Used for credentials that are shared across the entire Jenkins environment |
| Job-specific | Restricted to a specific job or pipeline | Used for credentials that should only be accessible within a particular job context |
| Node-specific | Restricted to a specific node or set of nodes | Used for credentials that are required only on certain agents or nodes |
Example: Using Job-specific Credentials
pipeline {
agent any
stages {
stage('Build') {
steps {
withCredentials([string(credentialsId: 'job-secret', variable: 'SECRET')]) {
sh 'echo $SECRET'
}
}
}
}
}
Note: Scoping credentials helps enforce least privilege and improves security by limiting access to sensitive data.
8. Managing Credential Domains
| Domain | Description | Usage | Notes |
|---|---|---|---|
| Global | Applies to all jobs and build agents | All credentials available globally | Default domain for system-wide credentials |
| Job-specific | Restricted to a specific job or project | Credentials used only in that job context | Isolated from other jobs and agents |
| Agent-specific | Bound to a specific build agent or node | Credentials used for connecting to agents | Useful for agent-specific access control |
Example: Setting up a Job-specific Domain
pipeline {
agent any
environment {
CREDENTIALS = credentials('job-specific-credentials')
}
stages {
stage('Use Credentials') {
steps {
sh 'echo "Using credentials: $CREDENTIALS"'
}
}
}
}
Note: Credential domains help in managing access control and scope of credentials across Jenkins jobs and agents.
9. Using Credentials in Pipelines
| Property | Description | Usage |
|---|---|---|
| credentials() | Declares a credential to be used in the pipeline | |
Example: Using a Username/Password Credential
pipeline {
agent any
stages {
stage('Example') {
steps {
withCredentials([usernamePassword(credentialsId: 'my-credential',
usernameVariable: 'USERNAME',
passwordVariable: 'PASSWORD')]) {
sh 'echo "Username: $USERNAME"'
}
}
}
}
}
Example: Using a Secret Text Credential
pipeline {
agent any
stages {
stage('Example') {
steps {
withCredentials([secretText(credentialsId: 'my-secret',
variable: 'SECRET')]) {
sh 'echo "Secret: $SECRET"'
}
}
}
}
}
Note: Ensure the credential ID matches exactly what is configured in Jenkins.
Warning: Never hardcode credentials in pipeline scripts. Always use Jenkins' credential store.
10. Rotating and Updating Credentials
| Operation | Description | Command/Method | Notes |
|---|---|---|---|
| Rotating Credentials | Replacing existing credentials with new ones to maintain security | credentials.update() |
Use Jenkins UI or API to update credential values |
| Updating Credential ID | Changing the identifier of a credential for better organization | credentials.rename() |
Requires reconfiguration of jobs using the credential |
| Reverting to Previous Version | Restoring a credential from a previous version or backup | credentials.rollback() |
Only available if version control is enabled |
Example: Updating a Username/Password Credential
const Jenkins = require('jenkins');
const jenkins = new Jenkins({ baseUrl: 'http://localhost:8080', crumbIssuer: true });
jenkins.credentials.update({
id: 'my-credential-id',
username: 'new-user',
password: 'new-password'
});
Note: Ensure that all jobs and build configurations referencing the updated credential are validated to prevent runtime errors.
11. Integrating with Secret Management Tools
| Tool | Integration Method | Notes |
|---|---|---|
| HashiCorp Vault | jenkins-plugin:Vault Credential Provider |
Provides credential binding and secret retrieval from Vault |
| AWS Secrets Manager | jenkins-plugin:AWS Credentials Plugin |
Allows Jenkins to fetch secrets from AWS Secrets Manager |
| Azure Key Vault | jenkins-plugin:Azure Credentials Plugin |
Enables fetching of secrets from Azure Key Vault |
| Google Secret Manager | jenkins-plugin:Google Secret Manager Plugin |
Supports integration with GCP Secret Manager for credential storage |
Example: Using Vault Credentials in a Pipeline
pipeline {
agent any
stages {
stage('Example') {
steps {
withCredentials([vaultString(credentialsId: 'my-vault-secret', variable: 'SECRET')]) {
sh 'echo "Secret value is: $SECRET"'
}
}
}
}
}
Note: Ensure the Vault plugin is installed and configured with proper permissions to access secrets.