Bitbucket Pipelines

Fetch secrets from KeyEnv and inject them into your Bitbucket Pipelines workflows.

Features

Exports secrets as environment variables
Optionally writes secrets to a .env file
Automatically masks secret values in logs
Supports project-scoped service tokens
Works with all Bitbucket plan tiers

Basic Usage

# bitbucket-pipelines.yml
pipelines:
  default:
    - step:
        name: Build and Test
        script:
          - pipe: keyenv/keyenv-pipe:1.0.0
            variables:
              KEYENV_TOKEN: $KEYENV_TOKEN
              ENVIRONMENT: development
          - npm ci
          - npm test

Variables

Variable	Description	Required	Default
`KEYENV_TOKEN`	KeyEnv service token	Yes	-
`ENVIRONMENT`	Environment name (e.g., `production`)	Yes	-
`PROJECT_ID`	Project ID. Optional if using project-scoped token.	No	-
`API_URL`	KeyEnv API URL	No	`https://api.keyenv.dev`
`ENV_FILE`	Path to write `.env` file	No	-

Examples

With Project ID

If your service token isn't project-scoped, specify the project:

pipelines:
  default:
    - step:
        script:
          - pipe: keyenv/keyenv-pipe:1.0.0
            variables:
              KEYENV_TOKEN: $KEYENV_TOKEN
              PROJECT_ID: proj_abc123def456
              ENVIRONMENT: staging
          - npm test

Write to .env File

pipelines:
  default:
    - step:
        script:
          - pipe: keyenv/keyenv-pipe:1.0.0
            variables:
              KEYENV_TOKEN: $KEYENV_TOKEN
              ENVIRONMENT: production
              ENV_FILE: .env
          - source .env
          - ./run-tests.sh

Deploy to Production

pipelines:
  branches:
    main:
      - step:
          name: Deploy
          deployment: production
          script:
            - pipe: keyenv/keyenv-pipe:1.0.0
              variables:
                KEYENV_TOKEN: $KEYENV_TOKEN
                ENVIRONMENT: production
            - ./deploy.sh

Multi-Environment Deployment

pipelines:
  branches:
    develop:
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - pipe: keyenv/keyenv-pipe:1.0.0
              variables:
                KEYENV_TOKEN: $KEYENV_TOKEN
                ENVIRONMENT: staging
            - ./deploy.sh

    main:
      - step:
          name: Deploy to Production
          deployment: production
          script:
            - pipe: keyenv/keyenv-pipe:1.0.0
              variables:
                KEYENV_TOKEN: $KEYENV_TOKEN
                ENVIRONMENT: production
            - ./deploy.sh

Docker Build

pipelines:
  default:
    - step:
        name: Build Docker Image
        services:
          - docker
        script:
          - pipe: keyenv/keyenv-pipe:1.0.0
            variables:
              KEYENV_TOKEN: $KEYENV_TOKEN
              ENVIRONMENT: production
              ENV_FILE: .env.production
          - docker build --secret id=env,src=.env.production -t myapp:latest .
          - docker push myapp:latest

Node.js Application

pipelines:
  default:
    - step:
        name: Test
        caches:
          - node
        script:
          - pipe: keyenv/keyenv-pipe:1.0.0
            variables:
              KEYENV_TOKEN: $KEYENV_TOKEN
              ENVIRONMENT: development
          - npm ci
          - npm test
          - npm run build

Python Application

pipelines:
  default:
    - step:
        name: Test
        caches:
          - pip
        script:
          - pipe: keyenv/keyenv-pipe:1.0.0
            variables:
              KEYENV_TOKEN: $KEYENV_TOKEN
              ENVIRONMENT: development
          - pip install -r requirements.txt
          - pytest

Setting Up Your Token

Go to your KeyEnv dashboard
Navigate to Settings > Service Tokens
Create a new token with:
- Scope: Select your project (recommended)
- Permissions: secrets:read
Add the token to your Bitbucket repository:
- Go to Repository settings > Pipelines > Repository variables
- Add a variable named KEYENV_TOKEN
- Check Secured to mask the value in logs

Security

All secret values are automatically masked in Bitbucket Pipelines logs
The service token is secured and never exposed
Secrets are fetched over HTTPS
Service tokens can be scoped to specific projects and environments

Self-Hosted KeyEnv

If you're running a self-hosted KeyEnv instance:

- pipe: keyenv/keyenv-pipe:1.0.0
  variables:
    KEYENV_TOKEN: $KEYENV_TOKEN
    ENVIRONMENT: production
    API_URL: https://keyenv.your-company.com

Troubleshooting

"Authentication failed"

Verify your token is correct
Check the token hasn't expired
Ensure the token is stored in Repository Variables correctly

"Access denied"

The token may not have access to the specified project
The token may not have access to the specified environment
Check token permissions in KeyEnv dashboard

"Project or environment not found"

Verify the PROJECT_ID is correct
Verify the ENVIRONMENT name matches exactly (case-sensitive)
Check the project/environment exists in KeyEnv

Bitbucket Pipelines

On this page