Skip to content

Migration: pkg/credentials → go/credentials

The credential storage-mode abstraction has been extracted out of go-tool-base into the standalone module gitlab.com/phpboyscout/go/credentials (v0.1.0). It is framework-free — the core's only dependencies are cockroachdb/errors and golang.org/x/term — so any project can adopt it without pulling in the framework.

What changed

  • The package gitlab.com/phpboyscout/go-tool-base/pkg/credentials (and its keychain and credtest subpackages) no longer exists. They now live at gitlab.com/phpboyscout/go/credentials, …/credentials/keychain, and …/credentials/test.
  • The API is unchanged except for one symbol. The package name is still credentials; Mode/ModeEnvVar/ModeKeychain/ModeLiteral, Backend, RegisterBackend, Store/Retrieve/Delete, Probe, KeychainAvailable, AvailableModes, IsCI, ValidateEnvVarName, RefuseLiteralUnderCI, KeychainOpTimeout, ClearKeysExcept, the ErrCredential* sentinels, and the keychain.Backend / MemoryBackend / Install helpers are all unchanged.
  • The test-helper subpackage is test, not credtest (module v0.2.0). The leaf dropped the module name it was repeating — the same rename that made config's mocks package mocks rather than configmock. Import it aliased, which is the toolkit convention for a generic leaf identifier:
-import "gitlab.com/phpboyscout/go-tool-base/pkg/credentials/credtest"
+import credtest "gitlab.com/phpboyscout/go/credentials/test"

The symbols are unchanged, so with the alias in place no call site moves. - StorageModeOptions was removed. It returned charm.land/huh/v2 options, which would have dragged a TUI dependency into the framework-free module. It is replaced by the UI-agnostic ModeChoices, which returns []ModeChoice (plain {Mode, Label} data) that any UI renders. The module also ships a Prompter seam with a stdlib DefaultPrompter for tools that want interactive capture out of the box. - There is no GTB adapter and no compatibility shim — a clean pre-1.0 import-path change (pkg/credentials had zero go-tool-base imports).

How to migrate

For everything except StorageModeOptions, a repository-wide substitution is sufficient (package name and symbols unchanged):

grep -rl 'go-tool-base/pkg/credentials' --include='*.go' . \
  | xargs sed -i 's#gitlab.com/phpboyscout/go-tool-base/pkg/credentials#gitlab.com/phpboyscout/go/credentials#g'
go get gitlab.com/phpboyscout/go/[email protected]
go mod tidy

If you called StorageModeOptions, switch to ModeChoices and convert the plain data to your UI's option type. For a huh form:

-options := credentials.StorageModeOptions(ci, keychainUsable, envLabel, keychainLabel, literalLabel)
+choices := credentials.ModeChoices(ci, keychainUsable, envLabel, keychainLabel, literalLabel)
+options := make([]huh.Option[credentials.Mode], len(choices))
+for i, c := range choices {
+   options[i] = huh.NewOption(c.Label, c.Mode)
+}

Or, for a tool with no TUI, use the stdlib prompter directly:

mode, err := credentials.DefaultPrompter().SelectMode(ctx, "Credential storage", choices)

Notes

  • go-tool-base itself now consumes go/credentials directly: its setup wizards (pkg/setup/ai, pkg/setup/forge) build their storage-mode selectors from ModeChoices and render them with GTB's own huh forms. The GTB-specific config-key schema, resolution cascades, doctor check, and config masker are unchanged — see the Credentials component.
  • Full documentation, the trust model, and the keychain opt-out live at credentials.go.phpboyscout.uk; the API reference is on pkg.go.dev.