Gopass Provider

The Gopass provider integrates with gopass, a multi-user, multi-store abstraction layer on top of pass that keeps secrets GPG-encrypted and syncs them via git.

Version compatibility

The Gopass provider is an upcoming SecretSpec 0.15 feature and is not available in SecretSpec 0.14.

Prerequisites

Install the gopass CLI and initialize a password store:

# macOS
brew install gopass

# Debian/Ubuntu
sudo apt install gopass

# NixOS
nix-env -iA nixpkgs.gopass

Configuration

URI Format

gopass://[folder_prefix]

• folder_prefix: Optional path prefix supporting {project}, {profile}, and {key} placeholders. Defaults to secretspec/{project}/{profile}/{key}.

Examples

# Use default gopass storage
$ secretspec set DATABASE_URL --provider gopass

# Custom folder prefix (e.g., to share secrets across projects — see below)
$ secretspec set DATABASE_URL --provider "gopass://secretspec/shared/{profile}/{key}"

Secret References

By default each secret is stored under secretspec/{project}/{profile}/{key}. A secret’s ref field names an existing entry instead: item is the full entry path, including any mount-point prefix for multi-store setups (field is not supported). Reads and writes target that entry in place.

[profiles.production]
DATABASE_URL = { description = "Production DB", ref = { item = "work-store/infra/postgres" }, providers = ["gopass"] }

Usage

# Set a secret
$ secretspec set DATABASE_URL
Enter value for DATABASE_URL: postgresql://localhost/mydb
✓ Secret DATABASE_URL saved to gopass

# Get a secret
$ secretspec get DATABASE_URL
postgresql://localhost/mydb

# Run with secrets
$ secretspec run -- npm start

# Use with profiles
$ secretspec set API_KEY --profile production
$ secretspec run --profile production -- npm start

Shared Secrets

By default, secrets are stored under secretspec/{project}/{profile}/{key}, which isolates them per project. To share secrets across projects, use a custom folder prefix via the URI:

~/.config/secretspec/config.toml

[defaults.providers]
shared = "gopass://secretspec/shared/{profile}/{key}"

The URI supports {project}, {profile}, and {key} placeholders. By omitting {project}, multiple projects can read and write the same store entry:

# secretspec.toml (in project-A and project-B)
[profiles.default]
ARTIFACTORY_USER = { description = "Artifactory user", providers = ["shared"] }

Both projects will resolve ARTIFACTORY_USER from secretspec/shared/default/ARTIFACTORY_USER.

Limitations

Only the first line of an entry is read back — if an entry was written outside of secretspec and contains multiple lines, everything after the first line is discarded on get.