dotenvx

dotenvx スキル

dotenvx は、.env ファイルを読み込み、暗号化する環境変数管理ツールです。言語やフレームワークを問いません。

インストール

# curl (recommended)
curl -sfS https://dotenvx.sh | sh

# brew
brew install dotenvx/brew/dotenvx

# npm
npm install @dotenvx/dotenvx --save

基本コマンド

# Load environment variables and run a command
dotenvx run -- node index.js

# Specify a particular .env file
dotenvx run -f .env.production -- npm start

# Load multiple files (later ones take precedence)
dotenvx run -f .env -f .env.local -- npm start

# Get an environment variable
dotenvx get DATABASE_URL

# Display all environment variables
dotenvx get

暗号化

# Encrypt .env (generates DOTENV_PUBLIC_KEY, DOTENV_PRIVATE_KEY)
dotenvx encrypt

# Encrypt a specific file
dotenvx encrypt -f .env.production

# Decrypt
dotenvx decrypt

# Run an encrypted file (requires DOTENV_PRIVATE_KEY)
dotenvx run -- node index.js

暗号化の仕組み

• dotenvx encrypt を実行すると、公開鍵と秘密鍵のペアが生成されます
• DOTENV_PUBLIC_KEY：暗号化のために .env ファイル内に保存されます
• DOTENV_PRIVATE_KEY：復号のためにローカル環境または CI に設定します
• 環境ごとの設定：DOTENV_PRIVATE_KEY_PRODUCTION によって自動検出されます

オプション

オプション	説明
-f, --env-file	.env ファイルを指定します
--overload	後続のファイルで上書きします
--quiet	出力を抑制します
--verbose	詳細な出力を表示します
--debug	デバッグ情報を表示します

複数の環境の管理

.env                 # Shared settings
.env.local           # Local overrides (gitignore)
.env.production      # Production
.env.development     # Development

# Run in production
dotenvx run -f .env.production -- npm start

# Development + local overrides
dotenvx run -f .env.development -f .env.local -- npm run dev

キーのローテーション

秘密鍵が漏えいした疑いがある場合、または定期的なローテーションを行う場合の手順です。2026/04 時点では専用の dotenvx rotate コマンドはないため、復号してから新しい鍵で暗号化する手順を明示的に実行します。

順序が重要です：まず CI のシークレットを新しい鍵に更新し、その後、新しい暗号文をマージしてください。順序を逆にすると、古い鍵で新しい暗号文を復号しようとして、本番環境で障害が発生します。

# 1. Working branch + stash old key
git switch -c chore/rotate-prod-dotenv-key
set +o history
OLD_PRIV="$DOTENV_PRIVATE_KEY_PRODUCTION"

# 2. Decrypt with the old key (back to plaintext)
DOTENV_PRIVATE_KEY_PRODUCTION="$OLD_PRIV" dotenvx decrypt -f .env.production

# 3. Remove the existing PUBLIC_KEY, then re-encrypt (a new key pair is generated)
sed -i.bak '/^DOTENV_PUBLIC_KEY_PRODUCTION=/d' .env.production
dotenvx encrypt -f .env.production
NEW_PRIV=$(dotenvx get DOTENV_PRIVATE_KEY_PRODUCTION -f .env.keys)

# 4. Update CI secret to the new key (before the merge)
gh secret set DOTENV_PRIVATE_KEY_PRODUCTION --body "$NEW_PRIV" --env production

# 5. Commit + merge + deploy the new ciphertext
git add .env.production && git commit -m "chore: rotate production dotenv key"
git push && gh pr create --fill && gh pr merge --squash --auto

# 6. Cleanup
unset OLD_PRIV; set -o history
rm .env.production.bak

漏えい時の追加手順：

• Git の履歴に残っている古い暗号文は、過去の古い鍵で引き続き復号できます。鍵のローテーションだけでは不十分です
• 暗号化された値（DB のパスワード、API キーなど）も並行して再発行する必要があります
• 履歴から完全に削除する必要がある場合は、git filter-repo を使用します。ただし、強制プッシュの影響が大きいため注意してください

ダウンタイムの回避：DOTENV_PRIVATE_KEY_PRODUCTION と DOTENV_PRIVATE_KEY_PRODUCTION_NEW の両方を一時的に並行して保持し、デプロイが成功した後に古い方を削除するブルーグリーン方式も有効です。

GitHub Actions

curl でインストールします。完全な例については assets/gh_action_example.yaml を参照してください。

steps:
  - uses: actions/checkout@v7

  - name: Install dotenvx
    run: curl -sfS https://dotenvx.sh | sh

  - name: Run tests
    env:
      DOTENV_PRIVATE_KEY: ${{ secrets.DOTENV_PRIVATE_KEY }}
    run: dotenvx run -- npm test

参考資料

• https://github.com/dotenvx/dotenvx
• https://dotenvx.com/docs