ghvars

Sync .env files and manage GitHub Actions secrets/variables from your .env.example template.

Features

• Sync - Keep .env in sync with .env.example (add new vars, remove deprecated, preserve values)
• Push - Push secrets and variables to GitHub Actions
• Pull - Pull variables from GitHub to .env
• Interactive - Select which items to push with a nice TUI

Installation

# In a Bun workspace
bun add ghvars

# Or install globally
bun add -g ghvars

Quick Start

# Run interactive menu
ghvars

# Or use specific commands
ghvars sync          # Sync .env with .env.example
ghvars push          # Push all secrets & variables to GitHub
ghvars pull          # Pull variables from GitHub

Configuration

Annotating Sections

ghvars reads your .env.example to determine which variables are secrets vs variables. Use annotations on section headers:

# =============================================================================
# SETTINGS @variables
# =============================================================================

APP_NAME="My App"
LOG_LEVEL="info"

# =============================================================================
# CREDENTIALS @secrets
# =============================================================================

API_KEY=""
DATABASE_URL=""

| Annotation | GitHub Target | Visibility | | ------------ | ---------------- | --------------- | | @secrets | GitHub Secrets | Hidden in logs | | @variables | GitHub Variables | Visible in logs | | (none) | Skipped | Not pushed |

Section Header Formats

These are recognized as section headers:

# === SECTION NAME ===           # Decorated with ===
# SECTION NAME                   # ALL CAPS standalone
# SECTION NAME (description)     # With parenthetical note
# SECTION NAME @secrets          # With annotation

These are NOT sections (just sub-headers/comments):

# --- Database ---               # Sub-header with ---
# Some lowercase comment         # Regular comment

Commands

ghvars (no args)

Interactive menu with all options:

? What would you like to do?
  🔄 Sync .env with .env.example
  ⬆️  Push all secrets & variables to GitHub
  🎯 Push selected items (interactive)
  ⬇️  Pull variables from GitHub

ghvars sync

Syncs .env with .env.example:

• Adds new variables from template
• Removes deprecated variables not in template
• Preserves existing values
• Updates structure (comments, sections, annotations)

ghvars sync

# Output:
# 📋 .env.example has 33 variables
#    (10 secrets, 23 variables)
#
# ✓ Added 2 new variable(s):
#    + NEW_VAR_1
#    + NEW_VAR_2
#
# 📝 Updated .env
#    31 preserved, 2 added, 0 removed

ghvars push

Push secrets and variables to GitHub Actions.

ghvars push              # Push all
ghvars push -i           # Interactive selection
ghvars push -s           # Secrets only
ghvars push -v           # Variables only

Requires GitHub CLI (gh) to be installed and authenticated.

ghvars pull

Pull variables from GitHub to .env.

ghvars pull

Note: Secrets cannot be pulled (GitHub security restriction).

ghvars init

Create a template .env.example file:

ghvars init

Example .env.example

# =============================================================================
# My App Configuration
# =============================================================================
# Use annotations on section headers:
#   @secrets   → pushed as GitHub Secrets (hidden)
#   @variables → pushed as GitHub Variables (visible)

# =============================================================================
# GENERAL @variables
# =============================================================================

APP_NAME="My App"
APP_ENV="development"
LOG_LEVEL="info"

# =============================================================================
# CREDENTIALS @secrets
# =============================================================================

# --- Database ---
DATABASE_URL=""

# --- API Keys ---
API_KEY=""
API_SECRET=""

# =============================================================================
# DEBUG @variables
# =============================================================================

DEBUG="false"

Requirements

• Bun runtime
• GitHub CLI for push/pull commands

License

MIT