CircleCI Integration

Load secrets from KeyEnv into your CircleCI workflows using the official KeyEnv orb or CLI.

Overview

There are two ways to integrate KeyEnv with CircleCI:

Method	Best For	Setup
KeyEnv Orb	Most projects	Simplest setup
CLI-based	Custom requirements	More control

Features

Exports secrets as environment variables
Optionally writes secrets to a .env file
Supports project-scoped service tokens
Works with self-hosted KeyEnv instances
Zero dependencies (auto-installs required tools)

Option 1: Using the KeyEnv Orb (Recommended)

The official KeyEnv orb provides the simplest integration.

Basic Usage

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]

jobs:
  build:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - keyenv/load:
          environment: production
      - run: npm test

Orb Parameters

Parameter	Description	Required	Default
`environment`	Environment name (e.g., `production`)	Yes	-
`project-id`	Project ID. Optional if using project-scoped token.	No	-
`token-var`	Name of env var containing the token	No	`KEYENV_TOKEN`
`api-url`	KeyEnv API URL	No	`https://api.keyenv.dev`
`env-file`	Path to write `.env` file	No	-

With Project ID

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

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]

jobs:
  build:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - keyenv/load:
          environment: staging
          project-id: proj_abc123def456
      - run: npm test

Write to .env File

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]

jobs:
  build:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - keyenv/load:
          environment: production
          env-file: .env
      - run: |
          # Secrets are available as env vars AND in .env file
          npm test

Multi-Environment Workflow

Use different environments for different jobs:

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]

jobs:
  test:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - keyenv/load:
          environment: development
      - run: npm ci
      - run: npm test

  deploy:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - keyenv/load:
          environment: production
      - run: npm run deploy

workflows:
  build-and-deploy:
    jobs:
      - test
      - deploy:
          requires:
            - test
          filters:
            branches:
              only: main

Using a Context

Store your KEYENV_TOKEN in a CircleCI context for use across multiple projects:

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]

jobs:
  deploy:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - keyenv/load:
          environment: production
      - run: npm run deploy

workflows:
  deploy:
    jobs:
      - deploy:
          context: keyenv-secrets

Using the load-and-run Job

For simple workflows, use the built-in job:

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]

workflows:
  deploy:
    jobs:
      - keyenv/load-and-run:
          environment: production
          command: npm run deploy
          context: keyenv-secrets

Option 2: CLI-Based Integration

Install the KeyEnv CLI directly in your workflow for more control.

Basic Example

# .circleci/config.yml
version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run:
          name: Install KeyEnv CLI
          command: |
            curl -fsSL https://keyenv.dev/install.sh | bash
            echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV
      - run:
          name: Pull secrets
          command: keyenv pull -e production
      - run:
          name: Deploy
          command: ./deploy.sh

workflows:
  deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Using keyenv run

Inject secrets directly without writing to disk:

# .circleci/config.yml
version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run:
          name: Install KeyEnv CLI
          command: |
            curl -fsSL https://keyenv.dev/install.sh | bash
            echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV
      - run:
          name: Deploy with secrets
          command: keyenv run -e production -- ./deploy.sh

workflows:
  deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Reusable Commands

# .circleci/config.yml
version: 2.1

commands:
  install-keyenv:
    description: Install KeyEnv CLI
    steps:
      - run:
          name: Install KeyEnv CLI
          command: |
            curl -fsSL https://keyenv.dev/install.sh | bash
            echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV

  load-secrets:
    description: Load secrets from KeyEnv
    parameters:
      environment:
        type: string
        default: "production"
    steps:
      - run:
          name: Pull secrets
          command: keyenv pull -e << parameters.environment >>

jobs:
  test:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - install-keyenv
      - load-secrets:
          environment: development
      - run: npm ci
      - run: npm test

  deploy:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - install-keyenv
      - run:
          name: Deploy
          command: keyenv run -e production -- npm run deploy

workflows:
  build-and-deploy:
    jobs:
      - test
      - deploy:
          requires:
            - test
          filters:
            branches:
              only: main

Language-Specific Examples

Node.js Application

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]
  node: circleci/[email protected]

jobs:
  test:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - node/install-packages
      - keyenv/load:
          environment: development
      - run: npm test
      - run: npm run build

workflows:
  ci:
    jobs:
      - test

Python Application

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]
  python: circleci/[email protected]

jobs:
  test:
    docker:
      - image: cimg/python:3.12
    steps:
      - checkout
      - python/install-packages
      - keyenv/load:
          environment: development
      - run: pytest

workflows:
  ci:
    jobs:
      - test

Go Application

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]
  go: circleci/[email protected]

jobs:
  test:
    docker:
      - image: cimg/go:1.22
    steps:
      - checkout
      - go/load-cache
      - go/mod-download
      - keyenv/load:
          environment: development
      - run: go test ./...
      - go/save-cache

workflows:
  ci:
    jobs:
      - test

Docker Build with Secrets

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]

jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - setup_remote_docker
      - keyenv/load:
          environment: production
          env-file: .env.production
      - run: |
          docker build \
            --secret id=env,src=.env.production \
            -t myapp:latest .

workflows:
  build:
    jobs:
      - build

Setting Up Your Token

Create a Service Token

Go to your KeyEnv dashboard
Navigate to Settings > Service Tokens
Create a new token with:
- Scope: Select your project (recommended)
- Permissions: secrets:read
Copy the token

Add Token to CircleCI

Option A: Project Environment Variable

Go to your CircleCI project
Navigate to Project Settings > Environment Variables
Add a new variable:
- Name: KEYENV_TOKEN
- Value: Your service token

Option B: Context (Recommended for multiple projects)

Go to Organization Settings > Contexts
Create a new context (e.g., keyenv-secrets)
Add a variable:
- Name: KEYENV_TOKEN
- Value: Your service token
Use the context in your workflow:

workflows:
  deploy:
    jobs:
      - deploy:
          context: keyenv-secrets

Self-Hosted KeyEnv

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

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]

jobs:
  deploy:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - keyenv/load:
          environment: production
          api-url: https://keyenv.your-company.com
      - run: npm run deploy

For CLI-based integration:

# .circleci/config.yml
version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    environment:
      KEYENV_API_URL: https://keyenv.your-company.com
    steps:
      - checkout
      - run:
          name: Install KeyEnv CLI
          command: |
            curl -fsSL https://keyenv.dev/install.sh | bash
            echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV
      - run:
          name: Deploy
          command: keyenv run -e production -- ./deploy.sh

Security Best Practices

Use contexts - Centralize token management across projects
Scope tokens narrowly - Create separate tokens for each environment
Don't log secrets - Avoid echo $SECRET in your scripts
Use keyenv run - Prefer runtime injection over writing to disk
Restrict context access - Limit which projects can use each context

Never commit service tokens to your repository. Always use CircleCI's environment variables or contexts.

Troubleshooting

"Authentication failed"

Verify your token is correct in CircleCI project settings
Check the token hasn't expired
Ensure the environment variable name matches token-var parameter

"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

Secrets not available in subsequent steps

Ensure you're using a bash-based executor (most CircleCI images work)
Secrets are exported to $BASH_ENV and loaded automatically in subsequent steps
If using a custom shell, source $BASH_ENV manually

"keyenv: command not found"

Ensure the PATH is updated correctly:

- run:
    name: Install KeyEnv CLI
    command: |
      curl -fsSL https://keyenv.dev/install.sh | bash
      echo 'export PATH="$HOME/.keyenv/bin:$PATH"' >> $BASH_ENV

Complete Example

Here's a complete CircleCI configuration for a Node.js application:

# .circleci/config.yml
version: 2.1

orbs:
  keyenv: keyenv/[email protected]
  node: circleci/[email protected]

jobs:
  test:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - node/install-packages
      - keyenv/load:
          environment: development
      - run:
          name: Run tests
          command: npm test
      - run:
          name: Run linter
          command: npm run lint
      - store_test_results:
          path: test-results

  build:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - node/install-packages
      - keyenv/load:
          environment: staging
      - run:
          name: Build application
          command: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist

  deploy_staging:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - attach_workspace:
          at: .
      - keyenv/load:
          environment: staging
      - run:
          name: Deploy to staging
          command: npm run deploy:staging

  deploy_production:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - attach_workspace:
          at: .
      - keyenv/load:
          environment: production
      - run:
          name: Deploy to production
          command: npm run deploy:production

workflows:
  build-test-deploy:
    jobs:
      - test
      - build:
          requires:
            - test
      - deploy_staging:
          requires:
            - build
          filters:
            branches:
              only: develop
          context: keyenv-secrets
      - deploy_production:
          requires:
            - build
          filters:
            branches:
              only: main
          context: keyenv-secrets

CircleCI Context Setup

Create a context named keyenv-secrets:

Variable	Value
`KEYENV_TOKEN`	`srv_your_token_here`

KeyEnv Environments

Create environments in KeyEnv:

Environment	Purpose
`development`	Testing with test data
`staging`	Pre-production validation
`production`	Live production deployment

Additional Resources

CircleCI Orb Registry
CircleCI Orb Documentation
KeyEnv GitHub Action - Similar integration for GitHub Actions

CircleCI Integration

On this page