Clone this repo:
  1. 83d38ea Merge pull request #289 from crazy-max/build-constraint by Sebastiaan van Stijn · 13 hours ago master
  2. 72391b3 pass: properly handle errors in tests by CrazyMax · 19 hours ago
  3. d066893 pass: exclude tests on windows by CrazyMax · 19 hours ago
  4. a51d46e ci: set gpg key trust level with import-gpg action by CrazyMax · 19 hours ago
  5. ea29253 ci: install pass on macOS for testing by CrazyMax · 19 hours ago

GitHub release PkgGoDev Build Status Codecov Go Report Card


docker-credential-helpers is a suite of programs to use native stores to keep Docker credentials safe.


Go to the Releases page and download the binary that works better for you. Put that binary in your $PATH, so Docker can find it.


You can build the credential helpers using Docker:

# install emulators
$ docker run --privileged --rm tonistiigi/binfmt --install all

# create builder
$ docker buildx create --use

# build credential helpers from remote repository and output to ./bin/build
$ docker buildx bake ""

# or from local source
$ git clone
$ cd docker-credential-helpers
$ docker buildx bake

Or if the toolchain is already installed on your machine:

1 - Download the source.

$ git clone
$ cd docker-credential-helpers

2 - Use make to build the program you want. That will leave an executable in the bin directory inside the repository.

$ make osxkeychain

3 - Put that binary in your $PATH, so Docker can find it.

$ cp bin/build/docker-credential-osxkeychain /usr/local/bin/


With the Docker Engine

Set the credsStore option in your ~/.docker/config.json file with the suffix of the program you want to use. For instance, set it to osxkeychain if you want to use docker-credential-osxkeychain.

  "credsStore": "osxkeychain"

With other command line applications

The sub-package client includes functions to call external programs from your own command line applications.

There are three things you need to know if you need to interact with a helper:

  1. The name of the program to execute, for instance docker-credential-osxkeychain.
  2. The server address to identify the credentials, for instance
  3. The username and secret to store, when you want to store credentials.

You can see examples of each function in the client documentation.

Available programs

  1. osxkeychain: Provides a helper to use the OS X keychain as credentials store.
  2. secretservice: Provides a helper to use the D-Bus secret service as credentials store.
  3. wincred: Provides a helper to use Windows credentials manager as store.
  4. pass: Provides a helper to use pass as credentials store.


pass needs to be configured for docker-credential-pass to work properly. It must be initialized with a gpg2 key ID. Make sure your GPG key exists is in gpg2 keyring as pass uses gpg2 instead of the regular gpg.


A credential helper can be any program that can read values from the standard input. We use the first argument in the command line to differentiate the kind of command to execute. There are four valid values:

  • store: Adds credentials to the keychain. The payload in the standard input is a JSON document with ServerURL, Username and Secret.
  • get: Retrieves credentials from the keychain. The payload in the standard input is the raw value for the ServerURL.
  • erase: Removes credentials from the keychain. The payload in the standard input is the raw value for the ServerURL.
  • list: Lists stored credentials. There is no standard input payload.

This repository also includes libraries to implement new credentials programs in Go. Adding a new helper program is pretty easy. You can see how the OS X keychain helper works in the osxkeychain directory.

  1. Implement the interface credentials.Helper in YOUR_PACKAGE/
  2. Create a main program in YOUR_PACKAGE/cmd/.
  3. Add make tasks to build your program and run tests.


MIT. See LICENSE for more information.