GitLab CI — dotEnv Cloud

GitLab CI/CD jobs can pull secrets from dotEnv Cloud with a single install step and an organization API key stored as a protected CI/CD variable. This guide shows a complete .gitlab-ci.yml and the variations you are most likely to need.

Add the API key as a CI/CD variable

In Settings → CI/CD → Variables, add a variable named DOTENV_API_KEY with your organization API key. Mark it Masked so it is hidden in job logs, and Protected if it should only be available on protected branches and tags.

A complete pipeline

GitLab exposes CI/CD variables to every job's environment automatically, so the CLI picks up DOTENV_API_KEY without any extra mapping:

.gitlab-ci.yml

stages:

- deploy

deploy:

stage: deploy

image: ubuntu:latest

before_script:

- apt-get update && apt-get install -y curl

- curl -sSL https://dotenv.cloud/install.sh | bash

script:

- dotenv pull my-app/production/api --output=.env

- ./deploy.sh

Export into the job environment

To load secrets into the process environment instead of a file, evaluate shell exports at the start of the script:

.gitlab-ci.yml

script:

- eval "$(dotenv export my-app/production/api --format=shell)"

- npm run build

Scope secrets per environment with GitLab environments

Map GitLab's deployment environments onto your dotEnv hierarchy so each stage pulls the right level. The pull path is just a string, so it can reference GitLab variables:

.gitlab-ci.yml

deploy_staging:

environment: staging

script:

- dotenv pull my-app/staging/api --output=.env

deploy_production:

environment: production

script:

- dotenv pull my-app/production/api --output=.env

Client-managed encryption

For client-managed projects, add a second masked variable for the key and let the CLI read it from DOTENV_CLIENT_KEY, or pass --client-key with a path to a key file. Decryption happens on the runner, so the key never leaves your pipeline.

See Securing CI/CD Pipelines for end-to-end hardening guidance.