Skip to content

Ruby SDK

The Ruby SDK (secretspec) is a thin client over the libsecretspec C ABI, linked into a native C extension at build time. Resolution happens in the Rust core, so the SDK inherits every provider with no Ruby-side logic.

require "secretspec"

resolved = Secretspec::SecretSpec.builder
                                 .with_provider("keyring://")
                                 .with_profile("production")
                                 .with_reason("boot web app")
                                 .load

puts resolved.provider, resolved.profile
db = resolved.secrets["DATABASE_URL"]
puts db.get             # the value, or the file path for as_path secrets
resolved.set_as_env!    # export everything into ENV

A missing required secret raises Secretspec::MissingRequiredError; any other failure raises Secretspec::Error (with a stable #kind).

builder = Secretspec::SecretSpec.builder.with_caller(
Secretspec::CallerContext.new(
name: "git",
version: "2.51.0",
operation: "credential_get",
resource: "github.com"
)
)

Caller context identifies the invoking integration in audit records but never satisfies require_reason. Do not put credentials or secret values in it.

Use .with_inline_spec(spec, base_dir) to resolve a strict inline-spec v2 hash (SecretSpec 0.21+) at its logical provider-path base directory. The extension links the separate native call symbol, so an older archive cannot fall back to a manifest search.

Use .with_scope("api") to resolve only a named [scopes.api] subset. The selected name is available as resolved.scope and report.scope:

resolved = Secretspec::SecretSpec.builder.with_scope("api").load

Generate typed classes with secretspec schema plus quicktype, then build them from resolved.fields:

Terminal window
$ secretspec schema | quicktype -s schema --top-level SecretSpec --lang ruby -o secrets_gen.rb
typed = SecretSpec.from_dynamic!(resolved.fields) # typed, generated
puts typed.database_url

Keep the result alive while consuming its paths, and call the SDK’s cleanup method afterward. Temporary files remain until explicit cleanup.

The published platform gems bundle the libsecretspec archive and statically link it into the mkmf extension at install time.

Install one library type with cargo-c:

Terminal window
# Use "static" (the default) or "shared"; use separate prefixes for both.
$ bash libsecretspec/scripts/cinstall.sh "$PREFIX" static

Then use the same extension flag for either type:

Terminal window
$ PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig" gem install secretspec -- --enable-pkg-config

A shared install in a non-system prefix also requires PREFIX/lib in the platform’s runtime library search path.