GitHub Actions — dotEnv Cloud

The easiest way to use dotEnv Cloud in GitHub Actions is the official dotEnv Secrets action, dotenvcloud/action-github. It installs the CLI, authenticates with your API key, and pulls your secrets in a single step, no manual install required. If you'd rather drive the CLI yourself, a manual approach is documented at the end.

Create an organization API key

CI/CD should authenticate with an organization API key, not OAuth. API keys are scoped to a single organization and require no browser. Create one in the dotEnv Cloud dashboard, then add it to your repository under Settings → Secrets and variables → Actions as DOTENV_API_KEY.

Never hardcode an API key in a workflow file. Always reference it from secrets so it stays encrypted at rest in GitHub.

Quick start with the dotEnv action

Add the action to your workflow and point it at a project and target. It writes the merged secrets to a .env file (configurable via output-file):

name: Deploy

on: [push]

jobs:

deploy:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Pull dotEnv secrets

uses: dotenvcloud/action-github@v1

with:

api-key: ${{ secrets.DOTENV_API_KEY }}

project: my-app

target: production

- name: Build

run: npm run build # reads .env

Narrow the pull to a single environment within a target by adding environment (for example api or web):

- name: Pull dotEnv secrets

uses: dotenvcloud/action-github@v1

with:

api-key: ${{ secrets.DOTENV_API_KEY }}

project: my-app

target: production

environment: api

Expose secrets to later steps

Set export-variables: true to load the pulled secrets into the GitHub job environment, so subsequent steps can read them as plain environment variables (values are masked in logs). This requires the default format: env:

- name: Pull dotEnv secrets

uses: dotenvcloud/action-github@v1

with:

api-key: ${{ secrets.DOTENV_API_KEY }}

project: my-app

target: production

export-variables: true

- name: Use a secret

run: echo "Deploying to $API_URL"

Inputs

The most common inputs (see the action's README for the full list):

api-key: organization API key. Required.
project: project to pull from. Required.
target: target within the project (e.g. production).
environment: environment within the target (e.g. api).
output-file: path to write (default .env).
format: env, json, yaml, shell, or dockerfile (default env).
export-variables: load secrets into $GITHUB_ENV (default false).
merge: merge secrets across hierarchy levels (default true).
resolve: resolve variable interpolation (default false).
organization: organization to use, if not the token's default.
cli-version: pin a specific CLI version (default latest).

The action exposes one output, env-file, with the path to the generated file.

Client-managed encryption

If the project uses client-managed encryption, the CLI needs the key to decrypt. Store the key as a separate GitHub secret and expose it as DOTENV_CLIENT_KEY at the job (or step) level, and the action's CLI run inherits it:

jobs:

deploy:

runs-on: ubuntu-latest

env:

DOTENV_CLIENT_KEY: ${{ secrets.DOTENV_CLIENT_KEY }}

steps:

- uses: dotenvcloud/action-github@v1

with:

api-key: ${{ secrets.DOTENV_API_KEY }}

project: my-app

target: production

Without the action (manual CLI install)

If you can't use the action (a self-hosted runner with locked-down network egress, or you need full control over the CLI invocation), install the binary and call dotenv pull yourself:

- name: Install dotEnv CLI

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

- name: Pull secrets

env:

DOTENV_API_KEY: ${{ secrets.DOTENV_API_KEY }}

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

For more hardening tips, read Securing CI/CD Pipelines.