Sync your .env files with GitHub Repository Variables in both directions using a simple CLI tool.
This tool uses GitHub Repository Variables, NOT GitHub Secrets.
- Variables are NOT encrypted and their values can be retrieved via the GitHub API
- Repository collaborators may have access to variable values depending on permissions
- Do NOT store sensitive secrets like API keys, passwords, or tokens using this tool
- For sensitive data, use GitHub Secrets directly or a proper secrets management solution
See GitHub's documentation on configuration variables for more information about security implications.
ghss synchronizes environment variables between your local .env files and GitHub repository variables. You can push variables from your local environment to GitHub or pull variable names and values from GitHub to create a .env file.
You start working on a new repository and create a .env file with all your configuration. Later, you move to another PC, clone your repo, and notice the .env file is missing (because it's gitignored). With ghss, you can:
- Push variables to GitHub from your first PC:
uvx --refresh ghss set - Pull variables from GitHub on your second PC:
uvx --refresh ghss get - You're ready to work with your configuration restored
This leverages GitHub Repository Variables to store your environment configuration without committing data to your repository.
Note: This is suitable for non-sensitive configuration values. For sensitive data, use proper secrets management.
No installation required! Just run the tool directly using uvx:
uvx --refresh ghss [command]The --refresh flag ensures you're always running the latest version.
ghss requires the GitHub CLI (gh) to be installed and authenticated. This is typically already set up if you work with GitHub repositories.
To check if you're authenticated:
gh auth statusIf not authenticated, run:
gh auth loginTest your configuration by creating, reading, and deleting a test variable in your repository.
Usage:
uvx --refresh ghss testconfExample output:
Testing gh CLI authentication...
✓ gh CLI is authenticated
✓ Using repository: MiguelElGallo/ghs
Creating test variable: GHS_TEST_VARIABLE_abc12345...
✓ Test variable created
Verifying test variable exists...
Waiting 3 seconds before trying to get the variable...
✓ Test variable verified
✓ Test variable value verified
Deleting test variable...
✓ Test variable deleted
✓ All tests passed! Configuration is working correctly.
Options:
--help: Show help message
Get all variables from the repository and write them to a .env file with their values.
Note: Unlike GitHub Secrets, variable values CAN be retrieved from the API. The values will be written to your local .env file.
Usage:
uvx --refresh ghss get
uvx --refresh ghss get -f custom.envExample output:
Checking gh CLI authentication...
Getting variables from repository: MiguelElGallo/ghs
Found 3 variable(s)
Writing variables to .env...
✓ Variables written to .env
⚠️ WARNING: Variable values are retrievable via API and may be visible to repository collaborators!
See https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository for more info.
Options:
-f, --file TEXT: Output file path (default:.env)--help: Show help message
Generated file format:
API_KEY=your_api_key_value
DATABASE_URL=postgres://localhost/db
APP_ENV=developmentRead a .env file and set the variables in the repository.
Usage:
uvx --refresh ghss set
uvx --refresh ghss set -f custom.envExample output:
Checking gh CLI authentication...
Found 3 variable(s) to set in repository: MiguelElGallo/ghs
⚠️ WARNING: All values of your .env file will be set as variables of this repository.
Repository collaborators could have access to these values.
See https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository for more info.
Do you want to continue? [y/N]: y
Setting variables...
Setting variable: API_KEY...
Setting variable: DATABASE_URL...
Setting variable: APP_ENV...
✓ Successfully set 3 variable(s)
Options:
-f, --file TEXT: Input file path (default:.env)--help: Show help message
Input file format:
API_KEY=your_api_key_here
DATABASE_URL=postgres://user:pass@localhost/db
APP_ENV=development-
Initial setup on your main PC:
# Create your .env file with configuration echo "API_URL=https://api.example.com" >> .env echo "APP_ENV=development" >> .env # Test configuration uvx --refresh ghss testconf # Push variables to GitHub (you'll be prompted for confirmation) uvx --refresh ghss set
-
On a different PC:
# Clone your repository git clone https://github.com/yourusername/yourrepo.git cd yourrepo # Pull variables from GitHub (values included!) uvx --refresh ghss get # You're ready to work!
MIT