Python自動化ツールで.envと.env.exampleを分ける理由。

はじめに
.envとは何か
.env.exampleとは何か
なぜ.envだけでは駄目なのか
GitHubに上げてよいもの、上げてはいけないもの
1. GitHubに上げてよいもの
2. GitHubに上げてはいけないもの
dataやoutputsもGitHubに上げない理由
.gitignoreで除外する
git statusで必ず確認する
すでにGit管理対象に入った場合
.env.exampleには本物の値を書かない
Codexに作らせたツールでも秘密情報は人間が管理する
GitHubはprivateリポジトリでも油断しない
今回のプロジェクトで決めた方針
READMEにも設定方針を書く
実装して感じたこと
まとめ

はじめに

前回の記事では、WordPress REST APIでAI生成記事を下書き投稿する際に遭遇した、401、404、403エラーについて書いた。

筆者のブログ自動化ツールでは、Search Console API、OpenAI API、WordPress REST APIなど、複数の外部サービスを使っている。

それぞれの連携では、APIキーや認証情報が必要になる。

たとえば、以下のような情報である。

OpenAI APIキー
Google Search Console用のOAuth認証情報
Google OAuthトークン
WordPress Application Password
WordPressユーザー名
Search ConsoleのsiteUrl
WordPress REST APIの接続設定

これらをコードに直接書くのは危険である。

また、GitHubに保存する場合は、秘密情報を誤ってコミットしないように注意が必要である。

そこで筆者は、.env と .env.example を分け、さらに .gitignore で秘密情報や生成物を除外するようにした。

本記事では、Python自動化ツールで .env と .env.example を分ける理由と、GitHubに上げてはいけないファイルについて整理する。

.envとは何か

.env は、環境ごとの設定値を保存するファイルである。

今回のブログ自動化ツールでは、たとえば以下のような値を .env に書いている。

OPENAI_API_KEY=your_actual_openai_api_key
OPENAI_MODEL=gpt-5.2

SEARCH_CONSOLE_SITE_URL=https://syanaise3wariup.com/
GOOGLE_CLIENT_SECRET_FILE=secrets/google_client_secret.json
GOOGLE_TOKEN_FILE=secrets/google_token.json

WORDPRESS_BASE_URL=https://syanaise3wariup.com
WORDPRESS_USERNAME=your_wordpress_username
WORDPRESS_APPLICATION_PASSWORD="your_actual_application_password"

WORDPRESS_REST_API_MODE=rest_route
WORDPRESS_POST_BODY_MODE=form
WORDPRESS_WAF_SAFE_MODE=true

この中には、外部に漏れると危険な情報が含まれる。

特に危険なのは以下である。

OPENAI_API_KEY
WORDPRESS_APPLICATION_PASSWORD
Google OAuthクライアント情報
Google OAuthトークン

これらは、他人に見られてはいけない。

そのため、.env はローカルPCだけに置き、GitHubには上げない。

.env.exampleとは何か

一方、.env.example は、設定項目の見本である。

.env と違い、本物の秘密情報は書かない。

たとえば、以下のようにダミー値だけを書く。

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-5.2

SEARCH_CONSOLE_SITE_URL=https://example.com/
GOOGLE_CLIENT_SECRET_FILE=secrets/google_client_secret.json
GOOGLE_TOKEN_FILE=secrets/google_token.json

WORDPRESS_BASE_URL=https://example.com
WORDPRESS_USERNAME=your_wordpress_username
WORDPRESS_APPLICATION_PASSWORD=your_wordpress_application_password

WORDPRESS_REST_API_MODE=auto
WORDPRESS_POST_BODY_MODE=form
WORDPRESS_WAF_SAFE_MODE=false

.env.example の役割は、次の通りである。

必要な設定項目を一覧できる
新しい環境を作るときのテンプレートになる
Codexや他の開発者に必要な環境変数を伝えやすい
本物の秘密情報を含まないのでGitHubに上げられる

つまり、.env は本物の鍵束であり、.env.example は鍵穴の一覧である。

鍵束そのものを配ってはいけないが、どの鍵穴があるかは共有してよい。

なぜ.envだけでは駄目なのか

個人開発であれば、.env だけでも動く。

しかし、ツールをGitHubで管理したり、Codexに修正させたり、別PCで環境を作ったりする場合、.env.example がないと困る。

たとえば、数週間後に自分でプロジェクトを見返したとき、必要な環境変数を忘れている可能性がある。

OPENAI_MODEL って必要だったか
WORDPRESS_POST_BODY_MODE は何を指定するのか
Google OAuthのファイルパスはどこに置くのか
Search ConsoleのsiteUrlはどの形式だったか

.env.example があれば、必要な項目をすぐ確認できる。

また、Codexに機能追加を依頼するときも、.env.example に設定項目が整理されていれば、どの環境変数を使うべきか伝わりやすい。

自動化ツールは、作った直後より、後から直すときの方が迷いやすい。
.env.example は、未来の自分への置き手紙でもある。

GitHubに上げてよいもの、上げてはいけないもの

今回のプロジェクトでは、GitHubに上げるものと上げないものを明確に分けた。

GitHubに上げてよいもの

基本的に、ソースコードや設定の見本は上げてよい。

src/
scripts/
config/
tests/
README.md
docs/
requirements.txt
pyproject.toml
.env.example
.gitignore

config/ は少し注意が必要である。

設定ファイルの中にAPIキーやパスワードが入っていなければ、GitHubに上げてもよい。
ただし、個別の認証情報や非公開URLを入れる場合は注意する必要がある。

GitHubに上げてはいけないもの

一方で、以下はGitHubに上げない方針にした。

.env
.venv/
secrets/*.json
secrets/*.key
secrets/*.pem
logs/
data/
outputs/
__pycache__/
*.pyc

特に注意すべきなのは、secrets/、data/、outputs/ である。

secrets/ にはGoogle OAuthの認証情報が入る。
data/ にはSearch Consoleから取得した検索データが入る。
outputs/ には未公開の記事下書きやレビュー結果が入る。

これらは外部に公開する必要がない。
むしろ、上げない方が安全である。

dataやoutputsもGitHubに上げない理由

.env や secrets をGitHubに上げないのは分かりやすい。

一方で、data/ や outputs/ は迷うところである。

筆者は、これらもGitHubには上げない方針にした。

理由は以下である。

Search Consoleデータにはサイト運営情報が含まれる
未公開の記事下書きが含まれる
WordPress投稿結果や内部URLが含まれる
ログにエラー内容やパスが含まれる
生成物は再作成できる

GitHubに保存したいのは、ツール本体である。
取得データや生成結果ではない。

特に、未公開の記事下書きは、公開前のコンテンツである。
これをGitHubに上げる必要はない。

自動化ツールでは、入力データと生成物が増えがちである。
だからこそ、最初に除外ルールを決めておく必要がある。

.gitignoreで除外する

GitHubに上げないファイルは、.gitignore に書く。

今回のプロジェクトでは、以下のような除外ルールを入れる方針にした。

# Python
__pycache__/
*.py[cod]
*.pyo
*.pyd
.pytest_cache/
.mypy_cache/
.ruff_cache/

# Virtual environment
.venv/
venv/
env/

# Environment / secrets
.env
.env.*
!.env.example
secrets/*
!secrets/.gitkeep

# Logs
logs/
*.log

# Runtime data
data/
outputs/

# OS / editor
.DS_Store
Thumbs.db
.vscode/
.idea/

ポイントは、.env.example は除外しないことである。

.env
.env.*
!.env.example

この書き方により、.env や .env.local は除外しつつ、.env.example はGitHubに含められる。

また、secrets/ は基本的に除外しつつ、空フォルダを維持したい場合は .gitkeep だけ残す。

secrets/*
!secrets/.gitkeep

こうしておくと、GitHub上にも secrets/ の置き場所だけは残せる。

git statusで必ず確認する

.gitignore を書いても、それだけで安心してはいけない。

コミット前には必ず git status を確認する。

git status

または、短く表示するなら以下である。

git status --short

ここで、次のようなファイルが出ていたら止まるべきである。

.env
secrets/google_client_secret.json
secrets/google_token.json
.venv/
outputs/article_drafts/
data/search_console_queries_api.csv
logs/

特に、secrets/ が出ていた場合は中身を確認する必要がある。

secrets/.gitkeep

だけであれば問題ない。

しかし、以下のようなファイルが出ていたら危険である。

secrets/google_client_secret.json
secrets/google_token.json

これはコミットしてはいけない。

秘密の鍵をGitHubに置くのは、玄関に印鑑と通帳を並べるようなものである。

すでにGit管理対象に入った場合

.gitignore は、まだGit管理されていないファイルを無視するためのものである。

すでにGit管理対象に入ってしまったファイルは、.gitignore に書いても自動では外れない。

その場合は、Gitの管理対象から外す必要がある。

たとえば、.env を誤って追加してしまった場合は、以下を実行する。

git rm --cached .env

Google OAuthの認証情報を外す場合は以下である。

git rm --cached secrets/google_client_secret.json
git rm --cached secrets/google_token.json

これはファイルを削除するのではなく、Gitの管理対象から外す操作である。
ローカルファイルは残る。

ただし、もし一度でもGitHubへpushしてしまった場合は、その認証情報は漏れたものとして扱った方がよい。

その場合は、APIキーやApplication Passwordを再発行するべきである。

.env.exampleには本物の値を書かない

.env.example はGitHubに上げてよい。

しかし、本物の値を書いてはいけない。

たとえば、以下は駄目である。

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
WORDPRESS_APPLICATION_PASSWORD="abcd efgh ijkl mnop qrst uvwx"

.env.example に書くのは、あくまでダミー値である。

OPENAI_API_KEY=your_openai_api_key_here
WORDPRESS_APPLICATION_PASSWORD=your_wordpress_application_password

.env.example は説明書であり、秘密メモではない。

この違いを混同すると危険である。

Codexに作らせたツールでも秘密情報は人間が管理する

今回のブログ自動化ツールは、Codexと一緒に作った。

Codexは、スクリプトや設定ファイルの整備には非常に役立つ。

たとえば、以下のような作業を任せられる。

.env.example に必要な項目を追加する
.gitignore を整備する
READMEに設定手順を書く
秘密情報をログに出さないようにする
dry-runを追加する
エラーメッセージを分かりやすくする

しかし、本物のAPIキーやApplication PasswordをCodexに貼り付けるべきではない。

秘密情報は、人間がローカルの .env に設定する。

Codexに渡すのは、必要な環境変数名やダミー値だけでよい。

AIと一緒に開発する場合でも、秘密情報の管理責任は人間側にある。

GitHubはprivateリポジトリでも油断しない

今回のプロジェクトは、GitHubに保存するならprivateリポジトリが望ましい。

しかし、privateだから何でも上げてよいわけではない。

privateリポジトリでも、以下のようなリスクはある。

設定ミスで公開範囲を変えてしまう
他の端末にcloneする
将来誰かと共有する
Git履歴に秘密情報が残る
トークンやパスワードが漏えいした場合に悪用される

そのため、privateリポジトリでも .env や secrets は上げない方がよい。

秘密情報をGitに入れない。
これが基本である。

GitHubの公開範囲に頼るのではなく、そもそも秘密情報をリポジトリに入れない設計にする。

今回のプロジェクトで決めた方針

今回のブログ自動化ツールでは、以下の方針にした。

.env はGitHubに上げない
.env.example はGitHubに上げる
secrets/ は基本的に上げない
secrets/.gitkeep だけ残してよい
data/ は上げない
outputs/ は上げない
logs/ は上げない
.venv/ は上げない
READMEとdocsに設定手順を書く

この方針にしておくと、GitHubにはツール本体だけを残せる。

環境固有の情報、秘密情報、生成物はローカルに置く。

これにより、GitHubを安全に使いやすくなる。

READMEにも設定方針を書く

.env.example や .gitignore を整備するだけでなく、READMEにも設定方針を書いておくとよい。

たとえば、以下のような項目である。

初期設定
.envの作り方
.env.exampleの見方
Google Search Console設定
OpenAI API設定
WordPress Application Password設定
GitHubに上げてはいけないファイル
トラブルシューティング

READMEは、未来の自分のための運用メモである。

特に、今回のようにSearch Console、OpenAI API、WordPress REST API、GitHubが絡むツールでは、数週間後に設定手順を忘れる可能性が高い。

READMEに残しておけば、思い出す時間を減らせる。

実装して感じたこと

今回の自動化ツールを作って感じたのは、便利なツールほど秘密情報が増えるということである。

Search Consoleを使えばGoogle認証が必要になる。
OpenAI APIを使えばAPIキーが必要になる。
WordPress REST APIを使えばApplication Passwordが必要になる。
GitHubに保存するなら、何を上げないかを決める必要がある。

つまり、自動化が進むほど、設定管理と秘密情報管理が重要になる。

コードを書くことだけが開発ではない。
安全に動かすための棚作りも開発の一部である。

.env、.env.example、.gitignore は地味である。
しかし、この地味な部分を整えることで、後から安心して改善できる。

まとめ

Python自動化ツールでAPIキーや認証情報を扱う場合、.env と .env.example は分けるべきである。

.env には本物の秘密情報を書く。
.env.example にはダミー値だけを書く。

GitHubに上げるのは、ソースコード、設定の見本、README、docsなどである。
.env、secrets、data、outputs、logs、.venv は上げない方がよい。

また、.gitignore を整備し、コミット前には必ず git status を確認する。

Codexと一緒に開発する場合でも、本物のAPIキーやパスワードはAIに渡さず、ローカルの .env で管理する。

自動化ツールは、動けばよいだけではない。
安全に運用できることも重要である。

筆者は今回、ブログ自動化ツールを作る中で、.env、.env.example、.gitignore の重要性をあらためて感じた。

リンク