# Bitbucket Pipelines

Inject KeyEnv secrets into Bitbucket Pipelines workflows.

Source: https://keyenv.dev/docs/sdks/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

```yaml
# 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:

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

1. Go to your KeyEnv dashboard
2. Navigate to **Settings > Service Tokens**
3. Create a new token with:
   - **Scope**: Select your project (recommended)
   - **Permissions**: `secrets:read`
4. 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:

```yaml
- 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