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.