Go
The read-only Go SDK (cgo over the C ABI): install the module and the native library, or build from source, open a vault, get a secret, match errors by sentinel, load a project.
Project setup options
Section titled “Project setup options”- Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
- Option 2: Set up with an AI coding agent. Run
sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.
Install
Section titled “Install”Two parts: the Go module, from the module proxy, and the native library it links, from the release (or built from source).
The module
Section titled “The module”go get github.com/netizine/sourceorrery/bindings/go@v0.3.1The module on pkg.go.dev (opens in a new tab)
is served by the Go module proxy from the bindings/go/v0.3.1 tag, and
go checks it against the Go checksum database. It is a cgo binding over
the C ABI with the header vendored in the module, so a C toolchain is
required: gcc or clang, or MinGW-w64 gcc on Windows.
The native library, from the release
Section titled “The native library, from the release”The shared library comes from the sourceorrery-ffi-0.3.1-<target>
archive on the
v0.3.1 release (opens in a new tab).
Download the archive for your platform, unpack it, and tell the linker and
the loader where it is:
$release = "https://github.com/Netizine/sourceorrery/releases/download/v0.3.1"$dir = "$env:LOCALAPPDATA\sourceorrery-ffi"Invoke-WebRequest "$release/sourceorrery-ffi-0.3.1-x86_64-pc-windows-msvc.zip" -OutFile sourceorrery-ffi.zip # aarch64-pc-windows-msvc on ArmExpand-Archive sourceorrery-ffi.zip -DestinationPath $dir -Force
$env:CGO_LDFLAGS = "-L$dir"$env:Path = "$dir;$env:Path" # sourceorrery_ffi.dll must be on PATH at run timego build ./...On Windows the binding links sourceorrery_ffi.dll directly, because the
static archive next to it is built by MSVC and MinGW cannot consume it.
release=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-ffi-0.3.1-aarch64-apple-darwin # x86_64-apple-darwin on Intelcurl -LO "$release/$archive.tar.gz"sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1
export CGO_LDFLAGS="-L/opt/sourceorrery"export DYLD_LIBRARY_PATH=/opt/sourceorrerygo build ./...release=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-ffi-0.3.1-x86_64-unknown-linux-gnu # aarch64-unknown-linux-gnu on arm64curl -LO "$release/$archive.tar.gz"sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1
export CGO_LDFLAGS="-L/opt/sourceorrery"export LD_LIBRARY_PATH=/opt/sourceorrerygo build ./...Verify a download against the release’s SHA256SUMS before unpacking it.
Static linking against libsourceorrery_ffi.a from the same archive works
too on Linux and macOS (-lsourceorrery_ffi -lpthread -ldl -lm on Linux),
and then nothing has to be on the loader’s path at run time.
Get a secret
Section titled “Get a secret”import sourceorrery "github.com/netizine/sourceorrery/bindings/go"
reader, err := sourceorrery.Open("development", nil)if err != nil { return err}defer reader.Close()
secret, err := reader.Get("database-password")if err != nil { return err}defer secret.Close() // zeroises the valueconnect(secret.Value.Text())With the default options, SOURCEORRERY_HOME locates the vault;
this machine’s key in the OS credential store opens it, else the
recovery key: an explicit one, SOURCEORRERY_RECOVERY_KEY, then a file
or SOURCEORRERY_RECOVERY_KEY_FILE. &sourceorrery.OpenOptions{Home, RecoveryKey, RecoveryKeyFile, IgnoreEnvironment} overrides any of that
(wipe RecoveryKey after use). The SDK never prompts and never asks the
vault’s view check.
A secret the vault keeps at a provider (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) is read there through the vault’s connection, with the same calls: the connection signs in with the credentials it stores, or with the provider’s own sign-in on the machine. No provider is contacted until a secret it keeps is read.
| Call | Returns |
|---|---|
reader.Get(name) |
*Secret for the newest accessible version |
reader.GetVersion(name, version) |
*Secret for exactly that version |
reader.Properties(name, version) ("" for the newest) |
SecretProperties (policy not applied) |
reader.Resolve("sourceorrery://development/database-password") |
*Secret |
reader.Descriptor() |
VaultDescriptor (no values) |
Secret.Properties (Vault, Name, Version, Enabled, ContentType,
Tags, NotBefore, ExpiresOn, CreatedOn, UpdatedOn as time.Time,
RecoveryLevel, Reference()) and Secret.Value, a *SecretValue:
value.Bytes() // []byte (a copy)value.Text() // stringvalue.Len()value.Close() // zeroise; Bytes() returns nil afterwardsvalue.String() // "[REDACTED]"; encoding/json writes "[REDACTED]" tooErrors
Section titled “Errors”Every failure is a *sourceorrery.Error with Code, Message and Hint
(Error() is the message followed by the hint). errors.Is matches the
sentinels by code:
secret, err := reader.Get("database-password")switch {case errors.Is(err, sourceorrery.ErrLocked): var e *sourceorrery.Error errors.As(err, &e) log.Println(e.Hint) // which recovery-key sources were triedcase errors.Is(err, sourceorrery.ErrNotFound): log.Println(err) // "secret ... was not found. Store it with ..."case errors.Is(err, sourceorrery.ErrPolicy): // disabled, not yet valid or expired log.Println(err)case err != nil: return err}Sentinels: ErrNotFound, ErrVersionNotFound, ErrDeleted,
ErrDisabled, ErrNotYetValid, ErrExpired, ErrPolicy,
ErrInvalidName, ErrInvalidArgument, ErrPermissionDenied,
ErrLocked, ErrVaultNotFound, ErrMigrationRequired,
ErrVaultMismatch, ErrManifest, ErrCrypto, ErrStorage,
ErrUnsupported, ErrUnauthenticated (the provider that stores the secret has no
credentials for this process), ErrProviderUnavailable (it could not be
reached). (*Error).Transient() is true for not_yet_valid and
provider_unavailable. See the SDK overview.
Load a project
Section titled “Load a project”project, err := sourceorrery.LoadProject("sourceorrery.toml", nil) // "" discovers itif err != nil { return err}defer project.Close()for _, secret := range project.Secrets { os.Setenv(secret.Env, secret.Value.Text())}LoadProject resolves every [secrets.*] entry the way sourceorrery run
does and returns the first required secret’s error if one cannot be read.
Goroutines
Section titled “Goroutines”A *Reader may be used from several goroutines at once. Each call pins
its OS thread while it reads the C ABI’s per-thread error state.
Building from source
Section titled “Building from source”You need Git, Rust 1.91.1 or newer installed with rustup, and a C compiler
(on Linux also pkg-config and libdbus-1-dev);
Building from source has the commands for
each platform. For this SDK, also Go 1.24 or newer, with cgo’s C compiler
on PATH (MinGW-w64 gcc on Windows).
The Go code needs no build of its own; what you build is the native library it links:
git clone https://github.com/Netizine/sourceorrerycd sourceorrerygit checkout v0.3.1 # or stay on main for the newest changescargo build --release -p sourceorrery-ffiThe library lands in target/release; use that directory wherever the
install steps above use the unpacked archive (CGO_LDFLAGS, and the
loader path at run time). To build your module against this checkout’s Go
code instead of the published module, point go.mod at it:
go mod edit -replace github.com/netizine/sourceorrery/bindings/go=/path/to/sourceorrery/bindings/goTo run the tests, the example and the conformance harness, build the CLI too, which creates the test vault, and run the rest in Bash (Git Bash on Windows) from the repository root:
cargo build --release -p sourceorrery-cli -p sourceorrery-ffieval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIRcd bindings/goexport CGO_LDFLAGS="-L$SOURCEORRERY_NATIVE_DIR"export LD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR" DYLD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR"# Git Bash on Windows: the DLL must be on PATH instead# export PATH="$(cygpath -u "$SOURCEORRERY_NATIVE_DIR"):$PATH"go test ./...go run ./examples/get-secret "$SOURCEORRERY_TEST_VAULT" database-passwordgo build -o conformance-go ./conformance # conformance-go.exe on Windowspython ../../tests/conformance/sdk/harness.py --runner goWhat the fixture script creates: The SDK test vault.
Source: bindings/go (opens in a new tab).