Conjur Bitbucket Pipe

Introducing the Conjur Bitbucket Pipe

Published July 4th, 2025 by Shlomo Heigh

Introduction

At CyberArk, we’re always trying to find ways to make it easier for developers to securely manage secrets wherever their code runs. That’s why we’re excited to introduce the Conjur Bitbucket Pipe! This integration allows CI pipelines that run in Bitbucket Cloud to easily retrieve secrets from Conjur for use in their builds and deployments.

What is the Conjur Bitbucket Pipe?

The Conjur Bitbucket Pipe is a new integration that allows you to connect your Bitbucket Cloud pipelines to Conjur. It works by authenticating with Conjur using the Bitbucket secure OIDC token, which means there’s no need to store any Conjur credentials in your Bitbucket repository. This reduces the risk of credential exposure and simplifies secret management, allowing teams to focus on delivering code without worrying about managing or rotating sensitive credentials. The integration provides a simple way to retrieve secret values stored in Conjur OSS, Conjur Enterprise, or Conjur Cloud so they can be used by your CI/CD pipelines.

How can I use it?

Pre-requisites

To use the Conjur Bitbucket Pipe, you need to have:

Configure Authentication

Before you can use the pipe, you need to configure authentication between Bitbucket and Conjur. This is done by creating a Conjur policy that allows the Bitbucket pipeline to authenticate using the OIDC token. Here’s an example:

# Create the authenticator 

- !policy 

  id: conjur/authn-jwt/bitbucket 

  body: 

    - !webservice 

    - !variable provider-uri 

    - !variable token-app-property 

    - !variable identity-path 
   
    - !group authenticatable 

    - !permit 

      role: !group authenticatable 

      privilege: [ read, authenticate ] 

      resource: !webservice 

# Create hosts for your Bitbucket pipelines 

- !policy 

  id: bitbucket-pipelines 

  body: 

    - !group 

    - &hosts 

      - !host 

# Replace this with your repositoryUuid. You must include the curly braces and double quotes! 

        id: "{<bitbucket-repository-uuid>}"

        annotations: 

          authn-jwt/bitbucket/repositoryUuid: "{<bitbucket-repository-uuid>}" # Replace this as well 

# Add more hosts here for other Bitbucket repositories if needed 
  
     - !grant 

      role: !group 

      members: *hosts 

# Create some secrets for the pipelines to use 

    - &variables 

      - !variable username 

      - !variable password 
  
# Allow the pipelines to read the variables 

    - !permit 

      role: !group 

      privilege: [ read, execute ] 

      resource: *variables 

# Add the pipelines to the group that can authenticate using authn-jwt/bitbucket 

- !grant 

  role: !group authn-jwt/bitbucket/authenticatable 

  members: !group bitbucket-pipelines

After loading this policy into Conjur, add values for the authenticator variables:

# Replace `<workspace-name>` with your Bitbucket workspace name
 conjur variable set -i conjur/authn-jwt/bitbucket/provider-uri -v "https://api.bitbucket.org/2.0/workspaces/<workspace-name>/pipelines-config/identity/oidc"
conjur variable set -i conjur/authn-jwt/bitbucket/token-app-property -v "repositoryUuid" 

# This is the path in the Conjur policy where the Bitbucket pipeline hosts are defined 

conjur variable set -i conjur/authn-jwt/bitbucket/identity-path -v "bitbucket-pipelines"

Now Conjur is ready to authenticate your Bitbucket pipelines!

Using the Pipe in Your Pipeline

To use the Conjur Bitbucket Pipe in your pipeline, you can add it to your bitbucket-pipelines.yml file like this: 
- step: 
  name: 'Retrieve secrets from Conjur' 
  oidc: true # This instructs Bitbucket to use provide OIDC credentials to the Pipe 

  script: 

    - pipe: cyberark-conjur/conjur-bitbucket-pipe:0.0.8 

      variables: 

        CONJUR_URL: 'https://<your-conjur-url>' 

        CONJUR_ACCOUNT: '<your-conjur-account>' # Defaults to 'conjur' 

        CONJUR_SERVICE_ID: 'bitbucket' # Service ID of the JWT Authenticator in Conjur. Defaults to 'bitbucket' 

        SECRETS: 'bitbucket-pipelines/username,bitbucket-pipelines/password' # Comma-separated list of Conjur variable IDs 

    - . ./.secrets/load_secrets.sh # This command loads the secrets into environment variables 

 # Now you can access the secrets as environment variables 
 # For example, 

    - curl -u $username:$password https://some-api.example.com/resource

You can see the full documentation, including advanced usage options, on our GitHub repository.

Conclusion

The Conjur Bitbucket Pipe makes it easy to securely manage secrets in your Bitbucket Cloud pipelines. By using OIDC authentication, you can avoid storing Conjur credentials in your repository, and you can easily retrieve secrets from Conjur for use in your builds and deployments. We hope this integration helps you streamline your CI/CD workflows while keeping your secrets secure. If you have any questions or feedback, please feel free to reach out to us on our GitHub repository or CyberArk Community. Happy coding!