ghsecretman

ghsecretman

A tool for managing GitHub Actions secrets, Actions variables, and Dependabot secrets across an organization. Reads a YAML file describing the desired state at three scopes — organization-level, per-repo, and fan-out-to-all-repos — and reconciles it against GitHub via three subcommands: audit (read-only diff), apply (write managed values), and enforce (apply plus delete unlisted values, with --dry-run).

See the design and full requirements in PRD #1.

Install

Pre-built binaries for darwin and linux on amd64 and arm64 are attached to each release on the Releases page. Each release also publishes a *-checksums.txt file with SHA-512 sums of every artifact.

# Pick the asset that matches your platform, then:
tar xzf ghsecretman-<version>-<os>-<arch>.tar.gz
sudo install ghsecretman-<version>-<os>-<arch>/ghsecretman /usr/local/bin/

To build from source:

go install github.com/schmidtw/ghsecretman/cmd/ghsecretman@latest

ghsecretman version prints the version, commit, and build date stamped in at release time.

Quick Start

ghsecretman authenticates with a personal access token from GITHUB_TOKEN (preferred) or GH_TOKEN. The token needs the scopes required to read and write the secrets/variables you list in the YAML.

A minimal config (secrets.yml) for an audit against one repo:

github.com:
  example-org:
    per-repo:
      example-repo:
        managed:
          vars:
            APP_ENV:
              value: production

Run a read-only audit:

export GITHUB_TOKEN=ghp_...
ghsecretman audit --config secrets.yml --org example-org --repo example-repo

audit exits non-zero if any drift is found, so it is safe to run from CI as a drift detector. To write managed values, use apply; to also delete unlisted values, use enforce. Run enforce --dry-run first to review what would change before letting deletes fire.

Omit --repo to iterate every repo in the org concurrently; --concurrency bounds the worker pool.

Configuration

The full YAML schema (org, per-repo, all-repos, managed, ignored, value sources, precedence rules, org-level scope/repos) is documented in PRD #1. A complete annotated example lives in internal/schema/example.yml, and the same content is embedded in the binary — run ghsecretman example to print it, or ghsecretman example -o secrets.yml to write a starter config.

Top-level keys other than github.com: are ignored, so the same file can carry sections owned by other tools.

Personal accounts work like orgs — with one exception. Pass a personal (user) account name to --org and ghsecretman auto-detects that it is a user account and enumerates that user's repositories (including private ones) instead of using the organization endpoint. All repo-scoped behavior — per-repo, all-repos fan-out, audit/apply/enforce, and single---repo runs — works exactly as it does for an organization. The one thing that cannot work is the org: (org-level scope) block: GitHub has no org-level Actions secret, variable, or Dependabot API for user accounts. When an org: block is present for a user account, ghsecretman prints a clear SKIPPED notice and continues with the repo-level work. Move any org-level values into all-repos (to fan them out to every repo) or per-repo.

Repo iteration is opt-in. ghsecretman only enumerates an org's repositories when the YAML has either an all-repos: block or a per-repo: block for that repo. Without either, repo-level secrets/variables are invisible to the tool. If you only intend to manage org-level objects but also want existing repo-level cruft cleaned up, include an empty all-repos: block (empty managed maps and empty ignored lists). With nothing under managed, every existing repo-level entry is reported as extra by audit and deleted by enforce. Run ghsecretman enforce --dry-run first to confirm the list before letting deletes fire.

License

Apache-2.0. See LICENSE.