1[](https://github.com/docker/docker-credential-helpers/releases/latest)
2[](https://pkg.go.dev/github.com/docker/docker-credential-helpers)
3[](https://github.com/docker/docker-credential-helpers/actions?query=workflow%3Abuild)
4[](https://codecov.io/gh/docker/docker-credential-helpers)
5[](https://goreportcard.com/report/github.com/docker/docker-credential-helpers)
6
7## Introduction
8
9docker-credential-helpers is a suite of programs to use native stores to keep Docker credentials safe.
10
11## Installation
12
13Go to the [Releases](https://github.com/docker/docker-credential-helpers/releases) page and download the binary that works better for you. Put that binary in your `$PATH`, so Docker can find it.
14
15## Building
16
17You can build the credential helpers using Docker:
18
19```shell
20# install emulators
21$ docker run --privileged --rm tonistiigi/binfmt --install all
22
23# create builder
24$ docker buildx create --use
25
26# build credential helpers from remote repository and output to ./bin/build
27$ docker buildx bake "https://github.com/docker/docker-credential-helpers.git"
28
29# or from local source
30$ git clone https://github.com/docker/docker-credential-helpers.git
31$ cd docker-credential-helpers
32$ docker buildx bake
33```
34
35Or if the toolchain is already installed on your machine:
36
371 - Download the source.
38
39```shell
40$ git clone https://github.com/docker/docker-credential-helpers.git
41$ cd docker-credential-helpers
42```
43
442 - Use `make` to build the program you want. That will leave an executable in the `bin` directory inside the repository.
45
46```shell
47$ make osxkeychain
48```
49
503 - Put that binary in your `$PATH`, so Docker can find it.
51
52```shell
53$ cp bin/build/docker-credential-osxkeychain /usr/local/bin/
54```
55
56## Usage
57
58### With the Docker Engine
59
60Set 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`.
61
62```json
63{
64 "credsStore": "osxkeychain"
65}
66```
67
68### With other command line applications
69
70The sub-package [client](https://godoc.org/github.com/docker/docker-credential-helpers/client) includes
71functions to call external programs from your own command line applications.
72
73There are three things you need to know if you need to interact with a helper:
74
751. The name of the program to execute, for instance `docker-credential-osxkeychain`.
762. The server address to identify the credentials, for instance `https://example.com`.
773. The username and secret to store, when you want to store credentials.
78
79You can see examples of each function in the [client](https://godoc.org/github.com/docker/docker-credential-helpers/client) documentation.
80
81### Available programs
82
831. osxkeychain: Provides a helper to use the OS X keychain as credentials store.
842. secretservice: Provides a helper to use the D-Bus secret service as credentials store.
853. wincred: Provides a helper to use Windows credentials manager as store.
864. pass: Provides a helper to use `pass` as credentials store.
87
88#### Note
89
90`pass` needs to be configured for `docker-credential-pass` to work properly.
91It 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`.
92
93## Development
94
95A 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:
96
97- `store`: Adds credentials to the keychain. The payload in the standard input is a JSON document with `ServerURL`, `Username` and `Secret`.
98- `get`: Retrieves credentials from the keychain. The payload in the standard input is the raw value for the `ServerURL`.
99- `erase`: Removes credentials from the keychain. The payload in the standard input is the raw value for the `ServerURL`.
100- `list`: Lists stored credentials. There is no standard input payload.
101
102This 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](osxkeychain) directory.
103
1041. Implement the interface `credentials.Helper` in `YOUR_PACKAGE/`
1052. Create a main program in `YOUR_PACKAGE/cmd/`.
1063. Add make tasks to build your program and run tests.
107
108## License
109
110MIT. See [LICENSE](LICENSE) for more information.
View as plain text