Skip to content

docs: Doppler Personal Config セットアップガイドとテンプレートを追加 #604

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
keito4 merged 2 commits into from
Mar 21, 2026
Merged

docs: Doppler Personal Config セットアップガイドとテンプレートを追加 #604

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8debd4
docs: Doppler Personal Config セットアップガイドとテンプレートを追加
github-actions[bot] Mar 21, 2026
9c37e1f
feat: /setup-doppler コマンドを追加
github-actions[bot] Mar 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,7 @@ config/
│ └── mcp.env.template
├── docs/ # ドキュメント
│ ├── README.md
│ ├── doppler-setup-guide.md # Doppler シークレット管理ガイド
│ ├── mcp-servers-guide.md
│ ├── sentry-setup-guide.md
│ ├── tool-catalog.md
Expand Down Expand Up @@ -272,6 +273,7 @@ config/
│ └── platform.sh
├── templates/ # プロジェクトテンプレート
│ ├── README.md
│ ├── doppler.yaml # Doppler プロジェクト設定テンプレート
│ ├── editorconfig
│ ├── github/ # GitHub テンプレート
│ │ ├── CODEOWNERS
Expand Down
202 changes: 202 additions & 0 deletions docs/doppler-setup-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
# Doppler セットアップガイド

Doppler を使ったシークレット管理の構成ガイド。
チーム共通の `dev` と個人用の `dev_personal` を使い分ける運用を推奨する。

## 構成概要

```
Doppler Project: my-app
├── dev # チーム共通の開発用シークレット
├── dev_personal # 各開発者の個人差分（Personal Config）
├── stg # ステージング（CI/CD token で取得）
└── prd # 本番（CI/CD token で取得）
```
Comment on lines +8 to +14

@coderabbitai coderabbitai Bot Mar 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix the fenced code block language identifier.

The fenced code block is missing a language identifier, which violates markdown linting rules.

📝 Proposed fix 
-```
+```text
 Doppler Project: my-app
 ├── dev              # チーム共通の開発用シークレット
 ├── dev_personal     # 各開発者の個人差分（Personal Config）
 ├── stg              # ステージング（CI/CD token で取得）
 └── prd              # 本番（Service Token で取得）

</details>

As per coding guidelines, "Fail on code formatting violations during code review" for `**/*.md` files.

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>

[warning] 8-8: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/doppler-setup-guide.md around lines 8 - 14, Add a language identifier
to the fenced code block that starts with "Doppler Project: my-app" by changing
the opening totext so the block is typed (e.g., ```text) and the
markdown linter stops flagging it; do not alter the block content otherwise.


</details>

<!-- fingerprinting:phantom:triton:puma -->

<!-- This is an auto-generated comment by CodeRabbit -->


### 各 config の役割

| Config | 用途 | アクセス |
| -------------- | ---------------------------------------------------- | ------------- |
| `dev` | チーム共通の開発用値（共通 DB URL、共通 API key 等） | 開発者全員 |
| `dev_personal` | 個人差分（個人 sandbox API key、個人 DB 名等） | 本人のみ |
| `stg` | ステージング環境 | Service Token |
| `prd` | 本番環境 | Service Token |

> `dev_personal` は Doppler の **Personal Config** 機能で自動作成される。
> `dev` の branch config として扱われ、`dev` の値を継承しつつ個人差分だけ override できる。

## セットアップ手順

### 1. Doppler CLI のインストール

DevContainer 環境では Dockerfile に組み込み済み。ローカルの場合：

```bash
# macOS
brew install dopplerhq/cli/doppler

# Linux
curl -sLf --retry 3 --tlsv1.2 --proto "=https" \
'https://packages.doppler.com/public/cli/gpg.DE2A7741A397C129.key' \
| sudo gpg --dearmor -o /usr/share/keyrings/doppler-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/doppler-archive-keyring.gpg] https://packages.doppler.com/public/cli/deb/debian any-version main" \
| sudo tee /etc/apt/sources.list.d/doppler-cli.list
sudo apt-get update && sudo apt-get install -y doppler
```

### 2. ログインとプロジェクト設定

```bash
# ログイン（ブラウザが開く）
doppler login

# プロジェクトを選択（対話式）
doppler setup
```

`doppler setup` を実行すると、カレントディレクトリに `.doppler.yaml` が生成される。

### 3. Personal Config の有効化

Doppler Dashboard で以下を設定：

1. プロジェクトの **Settings** → **Personal Configs** を有効化
2. `dev` 環境で **Personal Config** が利用可能になる
3. 各開発者が初回アクセス時に `dev_personal` が自動作成される

### 4. 開発サーバーの起動

```bash
# dev_personal を使って起動（個人差分が dev を override）
doppler run --config dev_personal -- pnpm dev

# チーム共通の dev で起動
doppler run --config dev -- pnpm dev

# doppler.yaml で default config が設定されている場合
doppler run -- pnpm dev
```

## doppler.yaml テンプレート

プロジェクトルートに配置：

```yaml
setup:
project: my-app
config: dev_personal
```

> `config: dev_personal` をデフォルトにすることで、`doppler run` だけで個人設定が使われる。

## package.json の推奨 scripts

```json
{
"scripts": {
"dev": "next dev",
"dev:doppler": "doppler run -- pnpm dev",
"dev:doppler:shared": "doppler run --config dev -- pnpm dev"
}
}
```

## DevContainer での統合

### containerEnv で Doppler を使う

`.devcontainer/devcontainer.json`:

```json
{
"containerEnv": {
"DOPPLER_TOKEN": "${localEnv:DOPPLER_TOKEN}"
},
"postStartCommand": "doppler setup --no-interactive || true"
}
```

> `DOPPLER_TOKEN` はホストマシンの環境変数から注入。
> Service Token（`dp.st.*`）または Personal Token（`dp.pt.*`）を設定する。

Comment on lines +104 to +121

@coderabbitai coderabbitai Bot Mar 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Documentation describes unimplemented DevContainer integration.

The guide documents DOPPLER_TOKEN in containerEnv and postStartCommand, but the actual .devcontainer/devcontainer.json (lines 34-37) only contains CLAUDE_ENV_FILE and CLAUDE_CODE_DISABLE_1M_CONTEXT. The Doppler integration pattern shown here hasn't been applied to the repository's DevContainer configuration.

This creates a gap where developers following the guide will find that the described integration doesn't match the actual implementation.

Recommendation: Either:

  1. Apply the Doppler integration to the actual devcontainer.json, or
  2. Clarify that this section describes a pattern for projects adopting Doppler, not the current state of this repository
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/doppler-setup-guide.md` around lines 104 - 121, The docs claim a
DevContainer integration using containerEnv DOPPLER_TOKEN and a postStartCommand
"doppler setup --no-interactive || true" but the repository's
.devcontainer/devcontainer.json only defines CLAUDE_ENV_FILE and
CLAUDE_CODE_DISABLE_1M_CONTEXT; update the repo or the docs to match: either add
the containerEnv entry ("DOPPLER_TOKEN": "${localEnv:DOPPLER_TOKEN}") and the
postStartCommand to .devcontainer/devcontainer.json so the documented pattern is
implemented, or change the docs text to clearly state this is an example pattern
(not applied here) and remove or annotate the JSON snippet to avoid implying it
exists in this repository; reference DOPPLER_TOKEN, containerEnv,
postStartCommand and the command doppler setup to locate the relevant code and
docs to change.

### GitHub Actions での統合

```yaml
- name: Fetch secrets from Doppler
uses: dopplerhq/secrets-fetch-action@v2
with:
doppler-token: ${{ secrets.DOPPLER_TOKEN }}
doppler-project: my-app
doppler-config: stg
```

## 運用ルール

### 値の配置ルール

| 値の種類 | 配置先 | 例 |
| ---------------------------- | -------------- | ---------------------------- |
| チーム共通の接続先 | `dev` | `DATABASE_URL`, `REDIS_URL` |
| 共通 API キー | `dev` | `STRIPE_TEST_KEY` |
| 個人 sandbox の API key | `dev_personal` | `MY_SANDBOX_API_KEY` |
| 個人 DB 名 | `dev_personal` | `DATABASE_NAME=dev_alice` |
| 個人 ngrok URL | `dev_personal` | `WEBHOOK_URL` |
| ステージング・本番の認証情報 | `stg` / `prd` | `DATABASE_URL`, `SECRET_KEY` |

### NG パターン

- `.env` ファイルにシークレットを直接記述（Doppler に移行する）
- `DOPPLER_CONFIG` を direnv や `.zshrc` でハードコードする（`doppler.yaml` に任せる）
- Personal Token を CI/CD で使う（Service Token を使う）

## トラブルシューティング

### `dev_personal` ではなく `dev` が読まれる

```bash
# 設定の優先順位を確認
doppler configure debug

# シェルに DOPPLER_CONFIG が残っていないか確認
env | grep DOPPLER
```

`DOPPLER_CONFIG` や `--config` は `doppler.yaml` より優先される。

### Personal Config が表示されない

1. Doppler Dashboard でプロジェクトの **Personal Configs** が有効か確認
2. `dev` 環境への書き込み権限があるか確認
3. `doppler configs` で利用可能な config を一覧表示

### DevContainer でログインが必要になる

DevContainer 内では `DOPPLER_TOKEN` 環境変数で認証するのが推奨。
ブラウザ認証は使えないため、Personal Token または Service Token を使う：

```bash
# Personal Token を生成（Doppler Dashboard → Access → Personal Tokens）
export DOPPLER_TOKEN=dp.pt.xxxxx
```

## 既存の 1Password 管理からの移行

このリポジトリでは `script/setup-env.sh` + 1Password CLI でシークレットを管理しているが、
プロジェクトごとに Doppler に移行する場合の手順：

1. 1Password のシークレットを Doppler の `dev` config にインポート
2. 個人差分を `dev_personal` に移動
3. `doppler.yaml` をプロジェクトルートに配置
4. `package.json` に `dev:doppler` スクリプトを追加
5. CI/CD の `secrets` を Doppler の Service Token に置き換え

> 1Password と Doppler は併用可能。1Password は長期保管の認証情報、
> Doppler はアプリケーション実行時のシークレット注入という使い分けが有効。
Comment on lines +182 to +194

@coderabbitai coderabbitai Bot Mar 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Migration steps lack implementation support in the credential infrastructure.

The guide describes migrating from 1Password to Doppler (lines 184-191), but the current script/credentials.sh framework has no Doppler provider plugin implemented. The pluggable provider system (see script/credentials.sh:1-122) only supports 1Password via the op provider.

To actually enable the migration workflow described here, a Doppler provider plugin would need to be added to script/credentials/providers/doppler.sh implementing the credential_provider::inject interface.

Recommendation: Either:

  1. Implement a Doppler provider plugin for credentials.sh to support the migration workflow, or
  2. Clarify that migration is a manual process outside the existing credential management framework, or
  3. Document this as a future enhancement and note that the current repository still uses 1Password exclusively
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/doppler-setup-guide.md` around lines 182 - 194, The docs describe
migrating to Doppler but the credentials framework (script/credentials.sh) only
supports the `op` provider; either implement a Doppler provider or update the
docs to avoid implying integration. To implement: add a new provider script at
script/credentials/providers/doppler.sh that implements the
credential_provider::inject interface used by script/credentials.sh, register
the provider name so the pluggable loader recognizes `doppler`, and implement
the necessary operations referenced by the guide (import into `dev`, move
personal diffs, place doppler.yaml, and CI token handling). Alternatively,
update the migration section to explicitly state migration is manual or a future
enhancement if you don’t want to add the provider now.


## 参考リンク

- [Doppler CLI ドキュメント](https://docs.doppler.com/docs/install-cli)
- [Personal Configs](https://docs.doppler.com/docs/personal-configs)
- [Service Tokens](https://docs.doppler.com/docs/service-tokens)
- [GitHub Actions 統合](https://docs.doppler.com/docs/github-actions)
- [DevContainer 統合](https://docs.doppler.com/docs/docker)
13 changes: 13 additions & 0 deletions templates/doppler.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Doppler プロジェクト設定テンプレート
#
# 使い方:
# 1. このファイルをプロジェクトルートにコピー
# 2. project 名を実際のプロジェクト名に変更
# 3. doppler setup で初期化
#
# config の優先順位:
# --config フラグ > DOPPLER_CONFIG 環境変数 > doppler.yaml > doppler setup の選択
#
setup:
project: my-app
config: dev_personal
Loading