Bitwarden Credentials Provider

The Bitwarden Credentials Provider is a Jenkins plugin that dynamically exposes items from a Bitwarden Password Manager vault (including self-hosted Vaultwarden) as native Jenkins credentials. It allows pipeline authors to access any secret on the fly, without requiring an administrator to manually create or sync credentials in the Jenkins UI.

This plugin integrates with personal vaults and organizations within the Password Manager product. It does not support the separate enterprise product, Bitwarden Secrets Manager.

• How It Works
• Getting Started
• Usage in Pipelines
• Supported Credential Types
• Configuration as Code (JCasC)
• License

This plugin uses the official Bitwarden CLI (bw) as its engine for all interactions with your vault. Its architecture is designed for performance, security, and resilience.

1. Bitwarden CLI Management: The plugin manages its own copy of the bw executable for x86_64 systems. Other architectures require manual installation and providing the path to the executable (see Getting Started).
2. Efficient Caching: On startup or after being configured, the plugin performs an initial bw sync. It then caches only the non-secret metadata (names, IDs, types) in Jenkins.
3. Persistence: The metadata cache is persisted to a file on the Jenkins controller. This allows Jenkins to start up and serve credentials instantly.
4. Background Refresh: The local vault is automatically re-synced with the Bitwarden server via bw sync in the background based on the "Cache Duration" setting, keeping your credentials reasonably fresh without impacting performance from slow CLI operations.
5. Live, On-Demand Secret Fetching: Your actual secrets (passwords, keys, etc.) are never cached by Jenkins. They are fetched "live" from the CLI's secure, local database at the exact moment a build needs to use them.
6. Offline Access: The Bitwarden CLI's local vault ensures that the plugin will continue functioning even if the Bitwarden server is unreachable or the controller is offline.

You must first configure the plugin's global settings in Manage Jenkins > Configure System.

• Bitwarden Server URL: For self-hosted instances like Vaultwarden. Leave blank for the official Bitwarden cloud.
• Bitwarden API Key Credential: Select a Jenkins "Username with password" credential that stores your Bitwarden service account's Client ID and Client Secret.
• Bitwarden Master Password Credential: Select a Jenkins "Secret text" credential that stores your service account's Master Password.
• Cache Duration: Sets how often the plugin will sync with the Bitwarden server in the background.
• Bitwarden CLI Executable Path: (Optional) Provide the absolute path to a manually installed bw executable. This is required for Jenkins controllers running on CPU architectures for which there is no direct bw CLI download (e.g., ARM/aarch64).

This plugin is fully compatible with the Jenkins Configuration as Code plugin and uses the symbol bitwarden.

Example jenkins.yaml:

credentials:
  system:
    domainCredentials:
      - credentials:
          - usernamePassword:
              scope: GLOBAL
              id: "bitwarden-api-key"
              username: "${BITWARDEN_CLIENT_ID}" # Uses value provided by environment variable
              password: "${BITWARDEN_CLIENT_SECRET}" # Uses value provided by environment variable
              description: "Bitwarden CLI API Credentials"
          - string:
              scope: GLOBAL
              id: "bitwarden-master-password"
              secret: '${BITWARDEN_MASTER_PASSWORD}' # Uses value provided by environment variable
              description: "Bitwarden CLI Master Password"
unclassified:
  bitwarden:
    # The URL of your self-hosted Bitwarden/Vaultwarden server.
    # Leave blank for the official Bitwarden cloud.
    serverUrl: "https://vault.example.com"
    # The Jenkins credential ID for your Bitwarden API Key.
    apiCredentialId: "bitwarden-api-key"
    # The Jenkins credential ID for your Bitwarden Master Password.
    masterPasswordCredentialId: "bitwarden-master-password"
    # (Optional) The absolute path to a manually installed `bw` executable.
    # Required for non-x86_64 architectures like ARM/aarch64.
    cliExecutablePath: "/usr/local/bin/bw"
    # How often the plugin automatically syncs with the Bitwarden server (in minutes).
    cacheDuration: 10
    # Comma-separated list of suffixes for Secure Notes names to be treated as File Credentials.
    fileCredentialSuffixes: ".env,.properties,.yaml"

After saving the configuration, the plugin will attempt to log in and perform an initial sync. You can verify success by checking the Jenkins system log or by navigating to the main Credentials page after a few moments to see your Bitwarden items.

The plugin includes several actions in the Manage Jenkins > Configure System > Bitwarden Credentials Provider > Advanced section to help you diagnose and quickly configure the plugin without needing to check the system log.

• Check Version: Verifies that the Bitwarden CLI is installed and executable by Jenkins.
• Download Latest: Forces a fresh download of the latest official Bitwarden CLI. This is useful for updating the CLI to a newer version.
• Verify Session Status: Performs a fast, read-only check to see if the plugin currently has an active, unlocked session with the Bitwarden CLI. This is the quickest way to confirm that the plugin is logged in and ready to serve credentials.
• Refresh Now: Forces the plugin to invalidate its current session and credential list and start a new sync in the background. Use this if you've made changes in your Bitwarden vault and want them to appear immediately.

This plugin intelligently exposes every item in your vault as a native Jenkins credential. To handle items that share the same name, it uses the following rule:

• If an item's name is unique in your vault, its credentialsId in Jenkins is its Name.
• If an item's name is not unique, its credentialsId in Jenkins is its UUID.

The Jenkins UI makes it easy to find the correct ID. The description for every credential shows both its name and its UUID, and will indicate if the name is non-unique.

Example: A Uniquely Named Secret

You can reference this item directly by its name in your Jenkinsfile.

// Jenkinsfile
withCredentials([string(credentialsId: 'My Production API Key', variable: 'API_KEY')]) {
    sh 'echo "The secret API key is available."'
}

Example: Handling a Non-Unique Name

Imagine you have two items named "Docker Hub". In the Jenkins UI, they would appear like this:

• ID: a1b2c3d4-..., Name: Docker Hub (BW ID: a1b2c3d4-..., non-unique name)
• ID: e5f6a1b2-..., Name: Docker Hub (BW ID: e5f6a1b2-..., non-unique name)

To access either one, you would copy its UUID from the UI and use that as the credentialsId.

// Jenkinsfile
withCredentials([usernamePassword(credentialsId: 'e5f6a1b2-c3d4-e5f6-a1b2-c3d4e5f6a1b2', usernameVariable: 'USER', passwordVariable: 'PASS')]) {
    sh 'echo "Logging in with the specific Docker Hub account..."'
}

To avoid fetching secrets by their Bitwarden UUID, the solution is simple: Always set a unique name for each item in your Bitwarden vault.

The plugin automatically converts Bitwarden items into the following Jenkins credential types.

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

This plugin is maintained by a single developer. While every effort is made to test thoroughly and keep the code well-organized and documented so others can understand it, bugs may still occur.

Found a Bug?

If you encounter any issues, please help improve the plugin by opening an issue on the GitHub Issues page.

Want to Add a Feature or Fix?

Pull Requests for realistic, reasonable, and well-tested improvements are welcome. I will do my best to review them in a timely manner.