SOPS: Secrets OPerationS

The SOPS provider integrates with SOPS to enable reading and writing of secrets encrypted at rest in local files.

Prerequisites

The SOPS CLI available within the environment:
- Manually download a release binary
- Use the SOPS Nix package
- Install with a package manager:
  Terminal window
```
  # Homebrew
  $ brew install sops

  # Arch
  $ sudo pacman -S sops
```

Configuration

URI Format

sops://path/to/secret[?key=value[&key=value]...]

path/to/secret — required path to the encrypted file (absolute or relative)
- Secrets in multiple files?
  In order to represent more than one file the path must be templated. i.e. separate SOPS-encrypted files per profile, or a hierarchical directory structure.
  A templated path must include both {project} and {profile} placeholders. Examples:
  - sops://secrets-dir/{project}.{profile}.enc.json
  - sops://secrets-dir/{project}/{profile}.enc.yaml
?key=value — optional query parameter, refer to the Query Parameters section for available parameters.
&key=value — additional parameters

Query Parameters

Excepting the SecretSpec-specific format parameter, refer to the SOPS documentation for the purpose and usage of each parameter.

SecretSpec

Provider URL Query Parameter Name	Purpose
format	Overrides the extension-based file format detection. Valid values: `dotenv` `env` `ini` `json` `yaml`

SOPS

Provider URL Query Parameter Name	Corresponding Environment Variable
sops_config	SOPS_CONFIG
sops_decryption_order	SOPS_DECRYPTION_ORDER
sops_editor	SOPS_EDITOR
sops_enable_local_keyservice	SOPS_ENABLE_LOCAL_KEYSERVICE
sops_keyservice	SOPS_KEYSERVICE

Age

Provider URL Query Parameter Name	Corresponding Environment Variable
age_key_cmd	SOPS_AGE_KEY_CMD
age_key_file	SOPS_AGE_KEY_FILE
age_recipients	SOPS_AGE_RECIPIENTS
age_ssh_private_key_cmd	SOPS_AGE_SSH_PRIVATE_KEY_CMD
age_ssh_private_key_file	SOPS_AGE_SSH_PRIVATE_KEY_FILE

AWS

Provider URL Query Parameter Name	Corresponding Environment Variable
aws_access_key_id	AWS_ACCESS_KEY_ID
aws_profile	AWS_PROFILE
aws_region	AWS_REGION
kms_arn	SOPS_KMS_ARN

GCP

Provider URL Query Parameter Name	Corresponding Environment Variable
gcp_kms_client_type	SOPS_GCP_KMS_CLIENT_TYPE
gcp_kms_endpoint	SOPS_GCP_KMS_ENDPOINT
gcp_kms_ids	SOPS_GCP_KMS_IDS
gcp_kms_universe_domain	SOPS_GCP_KMS_UNIVERSE_DOMAIN

Azure

Provider URL Query Parameter Name	Corresponding Environment Variable
azure_client_id	AZURE_CLIENT_ID
azure_keyvault_urls	SOPS_AZURE_KEYVAULT_URLS
azure_tenant_id	AZURE_TENANT_ID

PGP

Provider URL Query Parameter Name	Corresponding Environment Variable
pgp_fp	SOPS_PGP_FP

GPG

Provider URL Query Parameter Name	Corresponding Environment Variable
gpg_exec	SOPS_GPG_EXEC

Hashicorp Vault/OpenBao

Provider URL Query Parameter Name	Corresponding Environment Variable
hc_vault_addr	VAULT_ADDR
hc_vault_allowlist	SOPS_HC_VAULT_ALLOWLIST

Huawei Cloud

Provider URL Query Parameter Name	Corresponding Environment Variable
huawei_kms_ids	SOPS_HUAWEICLOUD_KMS_IDS
huawei_sdk_project_id	HUAWEICLOUD_SDK_PROJECT_ID

Provider credentials

Secret values used to authenticate SOPS belong in a provider alias’s credentials map, not in the SOPS URI.

Credential	Environment fallback	Available since
`age_key`	`SOPS_AGE_KEY`	0.17+
`aws_secret_access_key`	`AWS_SECRET_ACCESS_KEY`	0.17+
`azure_client_secret`	`AZURE_CLIENT_SECRET`	0.17+
`hc_vault_token`	`VAULT_TOKEN`	0.17+
`huawei_sdk_ak`	`HUAWEICLOUD_SDK_AK`	0.17+
`huawei_sdk_sk`	`HUAWEICLOUD_SDK_SK`	0.17+
`google_oauth_access_token`	`GOOGLE_OAUTH_ACCESS_TOKEN`	0.17+

See the complete provider credential reference for all supported providers and environment fallbacks.

For example, this alias loads an age identity from the system keyring and passes it only to the SOPS child process:

[providers.sops_age]
uri = "sops://secrets.enc.yaml?age_recipients=age1example"

[providers.sops_age.credentials]
age_key = "keyring"

[profiles.production.defaults]
providers = ["sops_age"]

When a credential is not declared on the alias, SOPS can still use its normal environment variable.

Format handling

SecretSpec asks SOPS to emit JSON when decrypting, then uses one lookup path for YAML, JSON, dotenv, and INI files. When ?format= is present, SecretSpec also passes the corresponding SOPS input type so filenames such as .env.production.enc?format=dotenv work correctly.

SOPS does not support --input-type ini, so ?format=ini is accepted only when the filename itself ends in .ini. Without ?format=, the filename must end in .yaml, .yml, .json, .env, .dotenv, or .ini; an unrecognized extension is reported as a configuration error.

YAML and JSON single-file layouts can nest values by project and profile. INI uses profile sections, while dotenv is always flat; in a single dotenv file, the same key therefore cannot hold different values for different profiles. Use a templated path such as secrets/{project}/.env.{profile}.enc?format=dotenv when profiles need separate dotenv values.

Usage

Set a secret with age

$ secretspec set DATABASE_URL --provider 'sops://secrets.enc.json?age_key_file=key.txt&age_recipients=age1jpa8rf5qmrg6pw444fcgpkaxg8x4neueszrexzagdjpunjlgeyzq304w34'

Or, if keys.txt exists in a place discoverable by SOPS and .sops.yaml exists next to the project’s secretspec.toml, configure a creation rule:

creation_rules:
  - path_regex: secrets\.enc\.json$
    age: "age1jpa8rf5qmrg6pw444fcgpkaxg8x4neueszrexzagdjpunjlgeyzq304w34"

then:

$ secretspec set DATABASE_URL --provider sops://secrets.enc.json