GH Secrets CLI

A local CLI tool to easily manage GitHub Actions secrets without using the web interface.

Features

• ✅ Two Authentication Methods:
  • Personal Access Token (PAT) - Simple and quick
  • OAuth Device Flow - Browser-based with custom scopes
• ✅ Manage secrets for personal repositories
• ✅ Manage secrets for organization repositories
• ✅ List all secrets in a repository
• ✅ Add/Update individual secrets
• ✅ Batch upload secrets from .env files
• ✅ Delete secrets
• ✅ No database - completely local
• ✅ Secure password masking for sensitive input

Installation

For End Users

Option 1: Using npx (No installation needed)

npx gh-secrets-cli

Option 2: Global Installation

npm install -g gh-secrets-cli

Then run anywhere:

gh-secret-cli

For Development

# Clone the repository
git clone https://github.com/jbacule/gh-secrets-cli.git
cd gh-secrets-cli

# Install dependencies
pnpm install

# Run in development mode
pnpm start

# Build for production
pnpm build

Usage

# Start the CLI
pnpm start

Prerequisites

• Node.js 18+ installed
• Choose one authentication method:

Option 1: Personal Access Token (Easier)

Create a Personal Access Token with required scopes:

1. Go to GitHub Settings > Developer Settings > Personal Access Tokens
2. Click "Generate new token (classic)"
3. Select scopes:
   • repo (Full control of private repositories)
   • admin:org (Full control of orgs and teams) - if managing org repos
4. Copy the generated token

Option 2: OAuth Device Flow (Better UX)

✨ If you're publishing this CLI tool, you can set up your own OAuth App and hardcode the Client ID - it's safe to be public!

Why Client IDs are safe to publish:

• ✅ OAuth Client IDs are designed to be public (unlike Client Secrets)
• ✅ Device Flow doesn't use secrets - security comes from user authorization
• ✅ Users explicitly approve in their browser with GitHub's authentication
• ✅ Real examples: GitHub CLI, Heroku CLI, and many others ship with hardcoded Client IDs

Setup for publishing:

1. Go to GitHub Settings > Developer Settings > OAuth Apps
2. Click "New OAuth App"
3. Fill in the details:
   • Application name: GitHub Secret Manager (or your chosen name)
   • Homepage URL: http://localhost (or your project URL)
   • Authorization callback URL: http://localhost
4. After creating, click "Enable Device Flow" (important!)
5. Copy the Client ID
6. In cli.ts, replace DEFAULT_OAUTH_CLIENT_ID with your Client ID:

   const DEFAULT_OAUTH_CLIENT_ID = "Ov23liYourActualClientID";

7. Publish! Users won't need to create their own OAuth App

For end users (if a default OAuth App is configured):

• Just run the app and choose "OAuth Device Flow"
• No need to create your own OAuth App
• Optional: Use your own OAuth App if desired

Authentication Flow

When you start the app, you'll choose between:

1. Personal Access Token

• Paste your PAT directly
• Quick and simple
• Good for personal use

2. OAuth Device Flow

• Enter your OAuth App Client ID
• Browser opens automatically to GitHub
• Enter the displayed code
• Approve the requested permissions
• Handles 2FA automatically (through GitHub's web interface)
• Can customize scopes per session

Workflow

1. Login: Choose authentication method and authenticate
2. Choose scope: Select Personal or Organization repositories
3. Select repository: Choose which repository to manage
4. Manage secrets:
   • List all existing secrets
   • Add/Update a single secret manually
   • Upload multiple secrets from a .env file
   • Delete secrets

Example .env File

Create a .env file with your secrets:

# Database Configuration
DATABASE_URL=postgresql://user:pass@localhost:5432/db
DATABASE_PASSWORD=supersecret123

# API Keys
API_KEY=your_api_key_here
STRIPE_SECRET_KEY=sk_test_123456789

# AWS Credentials
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Then use the "Upload Secrets from .env File" option to batch upload all secrets to your repository.

Authentication Comparison

Feature	Personal Access Token	OAuth Device Flow
Setup Complexity	Simple	Requires OAuth App
2FA Support	Token creation only	Handled by GitHub
Scope Customization	During token creation	Per authentication session
Token Visibility	You see the token	Token hidden (managed by GitHub)
Revocation	Manual in settings	Automatic on app revoke
Best For	Personal use, scripts	Team use, better UX

Security Notes

• Never commit your .env files to version control
• Keep your GitHub token secure
• This tool runs locally and doesn't store any data
• All secrets are encrypted using libsodium before sending to GitHub
• OAuth tokens are used immediately and not stored

Troubleshooting

OAuth Device Flow Issues

1. "device_flow_disabled" error: Make sure you enabled Device Flow in your OAuth App settings
2. Browser doesn't open: Manually visit the URL shown in the terminal
3. Token expired: The device code expires after 15 minutes. Just restart the authentication.

Permission Issues

• For organization secrets, ensure your OAuth scopes include admin:org
• For private repositories, ensure repo scope is included

Limitations

• Secret names must only contain alphanumeric characters or underscores
• Secret names cannot start with GITHUB_
• Secret names cannot start with a number

License

MIT LICENSE