The Two-File Pattern
The .env convention separates configuration from code. The standard pattern is:
.env— your real local values. Never commit this. Add it to.gitignore[citation:1][citation:16]..env.example— a template with the same variable names but blank or placeholder values. Commit this. It documents what the project needs [citation:1].
New team members copy .env.example to .env and fill in their own credentials. GitHub Actions uses a third channel: GitHub Secrets, which are injected as environment variables at runtime.
How GitHub Secrets Actually Work
GitHub Secrets are already encrypted. They use Libsodium sealed boxes, meaning the value is encrypted on your machine before it reaches GitHub's servers [citation:4][citation:11]. GitHub decrypts them only inside the workflow runner. You do not need to "obfuscate" them before storing — GitHub handles that.
${{ secrets.NAME }}, (3) use it as an environment variable in your steps. The .env file is for local development only.
The gh secret set Command
GitHub CLI can bulk-upload secrets from a .env file with a single command [citation:2]:
gh secret set -f .env
Or set them one at a time:
gh secret set API_KEY --body "your-value" gh secret set DATABASE_URL --body "postgres://..."
This tool generates the exact commands for your variables, so you can copy-paste them.
Referencing Secrets in a Workflow
Inside GitHub Actions, secrets are available via the secrets context [citation:9][citation:17]:
steps:
- name: Deploy
env:
API_KEY: ${{ secrets.API_KEY }}
DATABASE_URL: ${{ secrets.DATABASE_URL }}
run: ./deploy.sh
The tool generates this YAML block for your specific variable names.
What This Tool Does Not Do
- It does not encrypt your secrets. GitHub already does that. The tool only generates configuration files.
- It does not upload anything. Your values stay in your browser. You run the
ghcommands yourself. - It does not replace
.gitignore. You must add.envto.gitignoremanually. This tool reminds you but cannot enforce it.
Frequently Asked Questions
Should I commit .env?
.env.example with blank values. Add .env to .gitignore. This is the standard twelve-factor pattern [citation:1][citation:16].Do I need to obfuscate secrets before storing them in GitHub?
What does gh secret set -f .env do?
.env file and creates a GitHub Secret for every KEY=value pair. It's the fastest way to bulk-upload secrets [citation:2].How do I reference a secret in a workflow?
${{ secrets.MY_SECRET }} in your YAML. Assign it to an env: variable or pass it as an input: to an action [citation:9][citation:17].Why can't I use secrets in if: conditions?
secrets references in if: expressions. Set the secret as a job-level environment variable first, then reference that variable [citation:9].Are secrets passed to forked repository workflows?
GITHUB_TOKEN, secrets are not passed to workflows triggered from forked repositories [citation:9][citation:17].Is my data uploaded to your server?
Can I use this for GitLab or Bitbucket?
.env and .env.example files are platform-agnostic. Only the gh secret set commands and YAML snippet are GitHub-specific.