Docker Login Buildkite Plugin [](https://buildkite.com/buildkite/plugins-docker-login)

A Buildkite plugin to login to docker registries.

Securing your password

To avoid leaking your docker password to buildkite.com or anyone with access to build logs, you need to avoid including it in pipeline.yml. This means it needs to be set specifically with an environment variable in an Agent hook, or made available from a previous plugin defined on the same step.

Securing your credentials between Buildkite Jobs

By default, this plugin creates a step-specific docker config folder that gets removed after it is finished. If you want to disable that behaviour (for example, if you are using the Elastic CI Stack for AWS that already creates a per-job DOCKER_CONFIG directory), you may also have to disable the plugin from logging out after it is finished or you may run into race conditions in multi-agent setups.

Example

# environment or pre-command hook
export MY_DOCKER_LOGIN_PASSWORD=mysecretpassword

steps:
  - command: ./run_build.sh
    plugins:
      - docker-login#v3.1.0:
          username: myuser
          password-env: MY_DOCKER_LOGIN_PASSWORD

Configurations

Required

There is a single option required to configure and use this plugin.

username

The username to send to the docker registry.

Optional

disable-logout (boolean, insecure)

Set to true if you don't want the plugin to execute a docker logout when the step is finished.

Note that doing so may be a security risk allowing interaction with a private repository to any script or person with access to the agent if the local docker daemon saves credentials in a local unencrypted store they have access to (as is the default behaviour). If isolate-config is set to true as well, this would leave temporary files with docker credentials around after the step is finished (and a warning will be printed).

isolate-config (boolean, insecure)

Set to false if you don't want the plugin to create a special docker configuration for the step.

Note that doing so may be a security risk unless you are doing something similar outside of this plugin due to the login credentials being a shared state among all agents and jobs run by them with access to the same docker daemon. This can cause jobs to fail intermmittently or even allow access to private repositories to jobs that shouldn't have such access.

On Linux Hosted Agents with Remote Docker Builders, leaving isolate-config enabled (the default) redirects DOCKER_CONFIG to an empty temporary directory and hides the remote builder which is registered under $HOME/.docker/buildx/ during Agent startup. The result is that docker buildx build and docker buildx bake silently fall back to the local docker driver, losing the performance benefit of the remote builder. To preserve remote builder routing, either set this value to false, or re-register the remote builder inside the redirected config after the plugin's environment hook runs. For example, run docker buildx use in-runner-builder before any docker buildx command in your step.

It is safe to disable if you are using the Elastic CI Stack for AWS 5.0.0 or later or Hosted Agents.

password-env

The environment variable that the password is stored in.

Defaults to DOCKER_LOGIN_PASSWORD.

retries

Retries a failed login N times. Defaults to 3. Set to 0 to fail on the first attempt.

Each retry waits a random number of seconds between zero and a ceiling that doubles per attempt (2s, 4s, 8s, ...) up to 30s. Registries rate limit by source IP, so parallel jobs sharing an egress address tend to fail at the same moment; randomising the wait stops them all retrying in lockstep and triggering the limit again. At the default of 3 retries this adds at most 14 seconds before a login is reported as failed.

server

The server to log in to, if blank or ommitted logs into Docker Hub.

Windows Issues

This plugin requires git-bash, not the Windows built-in bash.exe, so you'll need to set your system PATH to have git-bash bin directory first, normallly C:\Program Files\git\bin.

Compatibility

Elastic Stack	Agent Stack K8s	Hosted (Mac)	Hosted (Linux)	Notes
✅	⚠️	❌	⚠️	K8s stack requires docker in docker Docker does not come installed on Hosted Mac Hosted Linux with Remote Docker Builders requires isolate-config: false or a manual builder re-registration step (see isolate-config)

• ✅ Fully supported (all combinations of attributes have been tested to pass)
• ⚠️ Partially supported (some combinations cause errors/issues)
• ❌ Not supported

License

MIT (see LICENSE)