gh-secrets-sync

gh-secrets-sync

Github CLI extension that syncs GitHub secrets across different repositories.

🎯 Motivation

I faced a few situations where I have common secrets that I want to deploy and keep in sync across multiple repositories. For example, GitHub Apps bot tokens, or tokens to interact with external services like NPM. When having a few repos that requires the same token, having to manually set it up in each repository is a pain, and it's easy to forget to update it when the token rotates.

That´s why I decided to build this tool, to simplify this process and have a centralized source of truth that can be easily updated and propagated to all repositories that need it.

🗃️ Features

• Secrets are stored in a local configuration file.
• Commands to add, edit, attach, list, and delete secrets from the configuration file.
• Sync command to propagate changes to all configured repositories.
• Interactive attach flow to add existing secrets to the current repository and sync them immediately.

🚀 Getting Started

Installation

You need the GitHub CLI installed first. Then install gh-secrets-sync:

gh extension install brpaz/gh-secrets-sync

Usage

After installing the extension, run gh secrets-sync to get started. A config file is created at ~/.config/gh-secrets-sync/secrets.yaml if it doesn't exist. This is where you will manage your secrets and their associated repositories.

[!WARNING] Secrets are stored in the config file as plain text. Keep this file secure (permissions are set to 0600 by default).

Configuration File

The config file has the following structure:

secrets:
  - name: "NPM_TOKEN"
    value: "secret_value"
    repositories:
      - "owner/repo1"
      - "owner/repo2"

Workflow: add secrets to the config file using gh secrets-sync add, then run gh secrets-sync sync to push them to GitHub.

If a secret has an empty repositories list, it stays in the config file but is skipped by gh secrets-sync sync until you add repositories later.

Commands

# Add a new secret
gh secrets-sync add --name NPM_TOKEN --value s3cr3t --repos myorg/api,myorg/web

# Add a new secret without sync targets yet
gh secrets-sync add --name SHARED_TOKEN --value s3cr3t

# List all configured secrets
gh secrets-sync list

# Edit an existing secret
gh secrets-sync edit --name NPM_TOKEN --value newvalue

# Attach existing secrets to the current repository and sync them immediately
gh secrets-sync attach

# Delete a secret
gh secrets-sync delete --name NPM_TOKEN

# Sync all secrets to their repositories
gh secrets-sync sync

# Open config file in editor
gh secrets-sync config

Common workflows

Add a secret now, choose repositories later

gh secrets-sync add --name NPM_TOKEN --value s3cr3t
gh secrets-sync list
gh secrets-sync edit --name NPM_TOKEN --repos myorg/api,myorg/web
gh secrets-sync sync

Attach existing secrets to the repo you are currently in

Run this from inside a GitHub repository checkout:

gh secrets-sync attach

This command:

1. Detects the current repository with gh
2. Lets you select one or more secrets from your config
3. Saves that repository into those secrets
4. Syncs the selected secrets immediately to that repository

Edit without exposing the current secret value

gh secrets-sync edit --name NPM_TOKEN

Options

All commands support these global options:

🤝 Contributing

All contributions are welcome. Please check CONTRIBUTING.md for details.

🫶 Support

If you find this project helpful and would like to support its development, there are a few ways you can contribute:

👱 Contributors

• Bruno Paz - Creator and maintainer

📃 License

Distributed under the MIT License. See LICENSE file for details.

📩 Contact

• 📧 Email: oss@brunopaz.dev
• 🐞 Issues: GitHub Issues
• 🖇️ Source: https://github.com/brpaz/gh-secrets-sync