{"id":13839806,"url":"https://github.com/buildkite-plugins/docker-buildkite-plugin","last_synced_at":"2025-12-27T01:54:50.864Z","repository":{"id":21356302,"uuid":"92471151","full_name":"buildkite-plugins/docker-buildkite-plugin","owner":"buildkite-plugins","description":"🐳📦 Run any build step in a Docker container","archived":false,"fork":false,"pushed_at":"2024-11-06T17:24:02.000Z","size":517,"stargazers_count":112,"open_issues_count":5,"forks_count":107,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-06T18:28:52.914Z","etag":null,"topics":["buildkite","buildkite-plugin","docker"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/buildkite-plugins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-26T04:09:52.000Z","updated_at":"2024-10-24T07:05:38.000Z","dependencies_parsed_at":"2023-02-16T12:40:24.744Z","dependency_job_id":"ce0a67b2-2df7-4612-a29d-8ded289b5d53","html_url":"https://github.com/buildkite-plugins/docker-buildkite-plugin","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-buildkite-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-buildkite-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-buildkite-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-buildkite-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buildkite-plugins","download_url":"https://codeload.github.com/buildkite-plugins/docker-buildkite-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225700118,"owners_count":17510439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buildkite","buildkite-plugin","docker"],"created_at":"2024-08-04T17:00:35.652Z","updated_at":"2025-12-27T01:54:50.858Z","avatar_url":"https://github.com/buildkite-plugins.png","language":"Shell","funding_links":[],"categories":["Shell","Plugins"],"sub_categories":[],"readme":"# Docker Buildkite Plugin [![Build status](https://badge.buildkite.com/b813517b8bb70d455106a03fbfbb1986477deb7c68f9ffcf59.svg?branch=master)](https://buildkite.com/buildkite/plugins-docker)\n\nA [Buildkite plugin](https://buildkite.com/docs/agent/v3/plugins) for running pipeline steps in [Docker](https://www.docker.com/) containers.\n\nAlso see the [Docker Compose Buildkite Plugin](https://github.com/buildkite-plugins/docker-compose-buildkite-plugin) which supports building images, `docker-compose.yml`, multiple containers, and overriding many of Docker’s defaults.\n\n## Example\n\n### `run`\n\nThe following pipeline will build a binary in the dist directory using the [golang Docker image](https://hub.docker.com/_/golang/) and then uploaded as an artifact.\n\n```yml\nsteps:\n  - command: \"go build -o dist/my-app .\"\n    artifact_paths: \"./dist/my-app\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"golang:1.11\"\n```\n\nWindows images are also supported:\n\n```yaml\nsteps:\n  - command: \"dotnet publish -c Release -o published\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"microsoft/dotnet:latest\"\n          always-pull: true\n```\n\n:warning: Warning: you should be careful when using an array or multi-line string as the command at the step level with this plugin. You will need to ensure that each line finishes with `;`, execute a script in your repository or use the plugin's [`command` option](#command-optional-array) instead. You will also have to take into account the image's entrypoint and [`shell` option](#shell-optional-array-or-boolean).\n\nIf you want to control how your command is passed to the docker container, you can use the `command` parameter on the plugin directly:\n\n```yml\nsteps:\n  - plugins:\n      - docker#v5.13.0:\n          image: \"mesosphere/aws-cli\"\n          always-pull: true\n          command: [\"s3\", \"sync\", \"s3://my-bucket/dist/\", \"/app/dist\"]\n    artifact_paths: \"dist/**\"\n```\n\nYou can pass in additional environment variables and customize what is mounted into the container.\n\nNote: If you are utilizing Buildkite's [Elastic CI Stack S3 Secrets plugin](https://github.com/buildkite/elastic-ci-stack-s3-secrets-hooks), you must specify the environment variable key names as they appear in your S3 bucket's `environment` hook in order to access the secret from within your container.\n\n```yml\nsteps:\n  - command: \"yarn install; yarn run test\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"node:7\"\n          always-pull: true\n          environment:\n            - \"MY_SECRET_KEY\"\n            - \"MY_SPECIAL_BUT_PUBLIC_VALUE=kittens\"\n```\n\nEnvironment variables available in the step can also automatically be propagated to the container:\n\nNote: this will not automatically propagate [Elastic CI Stack S3 Secrets plugin](https://github.com/buildkite/elastic-ci-stack-s3-secrets-hooks) `environment` variables. Refer above for explicitly importing values from that plugin.\n\n```yml\nsteps:\n  - command: \"yarn install; yarn run test\"\n    env:\n      MY_SPECIAL_BUT_PUBLIC_VALUE: kittens\n    plugins:\n      - docker#v5.13.0:\n          image: \"node:7\"\n          always-pull: true\n          propagate-environment: true\n```\n\nAWS authentication tokens can be automatically propagated to the container, for example from an assume role plugin or ECS IAM role:\n\n```yml\nsteps:\n  - command: \"yarn install; yarn run test\"\n    env:\n      MY_SPECIAL_BUT_PUBLIC_VALUE: kittens\n    plugins:\n      - docker#v5.13.0:\n          image: \"node:7\"\n          always-pull: true\n          propagate-aws-auth-tokens: true\n```\n\nYou can pass in additional volumes to be mounted. This is useful for running Docker:\n\n```yml\nsteps:\n  - command: \"docker build . -t image:tag; docker push image:tag\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"docker:latest\"\n          always-pull: true\n          volumes:\n            - \"/var/run/docker.sock:/var/run/docker.sock\"\n```\n\nYou can disable the default behaviour of mounting in the checkout to `workdir`:\n\n```yml\nsteps:\n  - command: \"npm start\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"node:7\"\n          always-pull: true\n          mount-checkout: false\n```\n\nYou can enable custom logging drivers and logging options with the use of `log-driver` and `log-opt`:\n\n```yml\nsteps:\n  - command: \"npm run start\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"node:7\"\n          log-driver: \"awslogs\"\n          log-opt:\n            - \"awslogs-group=my-buildkite-logs\"\n            - \"awslogs-region=us-east-1\"\n            - \"awslogs-stream-prefix=buildkite\"\n            - \"awslogs-create-group=true\"\n```\n\nVariable interpolation can be tricky due to the 3 layers involved (Buildkite, agent VM, and docker). For example, if you want to use [ECR Buildkite plugin](https://github.com/buildkite-plugins/ecr-buildkite-plugin), you will need to use the following syntax. Note the `$$` prefix for variables that would otherwise resolve at pipeline upload time, not runtime:\n\n```yml\nsteps:\n  - command: \"yarn install; yarn run test\"\n    plugins:\n      - ecr#v2.7.0:\n          login: true\n          account_ids:\n          - \"d\"\n          - \"p\"\n          region: us-west-2\n          no-include-email: true\n      - docker#v5.13.0:\n          image: \"d.dkr.ecr.us-west-2.amazonaws.com/imagename\"\n          command: [\"./run-integration-tests.sh\"]\n          expand-volume-vars: true\n          volumes:\n            - \"/var/run/docker.sock:/var/run/docker.sock\"\n            - \"$$BUILDKITE_DOCKER_CONFIG_TEMP_DIRECTORY/config.json:/root/.docker/config.json\"\n          propagate-environment: true\n          environment:\n            - \"BUILDKITE_DOCKER_CONFIG_TEMP_DIRECTORY\"\n\n```\n\nYou can read more about runtime variable interpolation from the [docs](https://buildkite.com/docs/pipelines/environment-variables#runtime-variable-interpolation).\n\n\n### `load`\n\nIf the image that you want to run is not in a registry the `load` property can be used to load an image from a tar file.\n\nThis can be useful if a previous step builds an image and uploads it as an artifact. The below example shows how an artifact can be downloaded and then passed to the `load` property to load the image which can then be referred to in the `image` property to start a container and run a command as explained above.\n\n```yml\nsteps:\n  - command: \"npm start\"\n    plugins:\n      - artifacts#v1.9.0:\n          download: \"node-7-image.tar.gz\"\n      - docker#v5.13.0:\n          load: \"node-7-image.tar.gz\"\n          image: \"node:7\"\n```\n\n### :warning: Warning\n\nYou need to be careful when/if [running the Buildkite agent itself in docker](https://buildkite.com/docs/agent/v3/docker) that, itself, runs pipelines that use this plugin. Make sure to read all the documentation on the matter, specially the caveats and warnings listed.\n\n## Configuration\n\n### Required\n\n### `image` (required, string)\n\nThe name of the Docker image to use.\n\nExample: `node:7`\n\n### Optional\n\n### `add-host` (optional, array)\n\nAdditional lines can be added to `/etc/hosts` in the container, in an array of mappings. See https://docs.docker.com/engine/reference/run/#managing-etchosts for more details.\n\nExample: `buildkite.fake:123.0.0.7`\n\n### `additional-groups` (optional, array)\n\nAdditional groups to be added to the user in the container, in an array of group names (or ids). See https://docs.docker.com/engine/reference/run/#additional-groups for more details.\n\nExample: `docker`\n\n### `always-pull` (optional, boolean)\n\nWhether to always pull the latest image before running the command. Useful if the image has a `latest` tag.\n\nDefault: `false`\n\n### `command` (optional, array)\n\nSets the command for the Docker image, and defaults the `shell` option to `false`. Useful if the Docker image has an entrypoint, or doesn't contain a shell.\n\nThis option can't be used if your step already has a top-level, non-plugin `command` option present.\n\nExamples: `[ \"/bin/mycommand\", \"-c\", \"test\" ]`, `[\"arg1\", \"arg2\"]`\n\n### `debug` (optional, boolean)\n\nEnables debug mode, which outputs the full Docker commands that will be run on the agent machine.\n\nDefault: `false`\n\n### `device-read-bps` (optional, array)\n\nLimit read rate from a device (format: `\u003cdevice-path\u003e:\u003cnumber\u003e[\u003cunit\u003e]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`.\n\nExample: `[\"/dev/sda1:200mb\"]`\n\n### `device-read-iops` (optional, array)\n\nLimit read rate (IO per second) from a device (format: `\u003cdevice-path\u003e:\u003cnumber\u003e`). Number is a positive integer.\n\nExample: `[\"/dev/sda1:400\"]`\n\n### `device-write-bps` (optional, array)\n\nLimit write rate to a device (format: `\u003cdevice-path\u003e:\u003cnumber\u003e[\u003cunit\u003e]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`.\n\nExample: `[\"/dev/sda1:200mb\"]`\n\n### `device-write-iops` (optional, array)\n\nLimit write rate (IO per second) to a device (format: `\u003cdevice-path\u003e:\u003cnumber\u003e`). Number is a positive integer.\n\nExample: `[\"/dev/sda1:400\"]`\n\n### `entrypoint` (optional, string)\n\nOverride the image’s default entrypoint, and defaults the `shell` option to `false`. See the [docker run --entrypoint documentation](https://docs.docker.com/engine/reference/run/#entrypoint-default-command-to-execute-at-runtime) for more details. Set it to `\"\"` (empty string) to disable the default entrypoint for the image, but note that you may need to use this plugin's `command` option instead of the top-level `command` option or set a `shell` instead (depending on the command you want/need to run - see [Issue 138](https://github.com/buildkite-plugins/docker-buildkite-plugin/issues/138) for more information).\n\nExample: `/my/custom/entrypoint.sh`, `\"\"`\n\n### `environment` (optional, array)\n\nAn array of additional environment variables to pass into to the docker container. Items can be specified as either `KEY` or `KEY=value`. Each entry corresponds to a Docker CLI `--env` parameter. Values specified as variable names will be passed through from the outer environment.\n\nExample: `[ \"BUILDKITE_MESSAGE\", \"MY_SECRET_KEY\", \"MY_SPECIAL_BUT_PUBLIC_VALUE=kittens\" ]`\n\n### `env-file` (optional, array)\n\nAn array of additional files to pass into to the docker container as environment variables. Each entry corresponds to a Docker CLI `--env-file` parameter.\n\n### `env-propagation-list` (optional, string)\n\nIf you set this to `VALUE`, and `VALUE` is an environment variable containing a space-separated list of environment variables such as `A B C D`, then A, B, C, and D will all be propagated to the container. This is helpful when you've set up an `environment` hook to export secrets as environment variables, and you'd also like to programmatically ensure that secrets get propagated to containers, instead of listing them all out.\n\n### `expand-image-vars` (optional, boolean, unsafe)\n\nWhen set to true, it will activate interpolation of variables in the elements of the `image` configuration variable. When turned off (the default), attempting to use variables will fail as the literal `$VARIABLE_NAME` string will be passed as the image name.\n\nEnvironment variable interpolation rules apply here. `$VARIABLE_NAME` is resolved at pipeline upload time, whereas `$$VARIABLE_NAME` is at run time. All things being equal, you likely want `$$VARIABLE_NAME`.\n\n:warning: **Important:** this is considered an unsafe option as the most compatible way to achieve this is to run the strings through `eval` which could lead to arbitrary code execution or information leaking if you don't have complete control of the pipeline\n\n### `propagate-environment` (optional, boolean)\n\nWhether or not to automatically propagate all* pipeline environment variables into the docker container. Avoiding the need to be specified with `environment`.\n\nNote that only pipeline variables will automatically be propagated (what you see in the Buildkite UI). Variables set in proceeding hook scripts will not be propagated to the container.\n\n\\* Caveat: only environment variables listed in $BUILDKITE_ENV_FILE will be propagated. This does not include for example variables that you exported in an `environment` hook. If you wish for those to be propagated, try `env-propagation-list`.\n\n### `propagate-aws-auth-tokens` (optional, boolean)\n\nWhether or not to automatically propagate aws authentication environment variables into the docker container. Avoiding the need to be specified with `environment`. This is useful for example if you are using an assume role plugin or you want to pass the role of an agent running in ECS or EKS to the docker container.\n\nWill propagate `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, `AWS_DEFAULT_REGION`, `AWS_STS_REGIONAL_ENDPOINTS`, `AWS_WEB_IDENTITY_TOKEN_FILE`, `AWS_ROLE_ARN`, `AWS_CONTAINER_CREDENTIALS_FULL_URI`, `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`, and `AWS_CONTAINER_AUTHORIZATION_TOKEN`, only if they are set already.\n\nWhen the `AWS_WEB_IDENTITY_TOKEN_FILE` is specified, it will also mount it automatically for you and make it usable within the container.\n\n### `propagate-gcp-auth-tokens` (optional, boolean)\n\nWhether or not to automatically propagate gcp auth credentials into the docker container. Avoiding the need to be specified with `environment`. This is useful if you are using a workload identity federation to impersonate a service account and you want to pass it to the docker container. This is compatible with the `gcp-workload-identity-federation` plugin.\n\nWill propagate `GOOGLE_APPLICATION_CREDENTIALS`, `CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE` and `BUILDKITE_OIDC_TMPDIR` and also mount the dir specified by `BUILDKITE_OIDC_TMPDIR` into the container.\n\n### `propagate-uid-gid` (optional, boolean)\n\nWhether to match the user ID and group ID for the container user to the user ID and group ID for the host user. It is similar to specifying `user: 1000:1000`, except it avoids hardcoding a particular user/group ID.\n\nUsing this option ensures that any files created on shared mounts from within the container will be accessible to the host user. It is otherwise common to accidentally create root-owned files that the agent will be unable to remove, since a lot of images by default run as the root user. This can also be mitigated for the checkout directory by using the `chown` option of this plugin.\n\n### `privileged` (optional, boolean)\n\nWhether or not to run the container in [privileged mode](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)\n\n### `init` (optional, boolean)\n\nWhether or not to run an init process inside the container. This ensures that responsibilities like reaping zombie processes are performed inside the container.\n\nSee [Docker's documentation](https://docs.docker.com/reference/cli/docker/container/run/#init) for background and implementation details.\n\nDefault: `true` for Linux and macOS, `false` for Windows.\n\n### `leave-container` (optional, boolean)\n\nWhether or not to leave the container after the run, or immediately remove it with `--rm`.\n\nDefault: `false`\n\n### `log-driver` (optional, string)\n\nThe logging driver for the container. This allows you to configure how Docker handles logs for the container.\n\nCommon drivers include: `json-file`, `syslog`, `journald`, `gelf`, `fluentd`, `awslogs`, `splunk`, `etwlogs`, `gcplogs`, `logentries`, `none`.\n\n:information_source: As a default, Docker uses the [json-file logging driver](https://docs.docker.com/engine/logging/drivers/json-file/)\n\nSee [Docker's logging documentation](https://docs.docker.com/config/containers/logging/) for complete details.\n\n### `log-opt` (optional, array)\n\nOptions for the logging driver. These are key-value pairs that configure the behavior of the selected logging driver.\n\n### `load` (optional, string)\n\nSpecify a file to load a docker image from. If omitted no load will be done.\n\n### `mount-checkout` (optional, boolean)\n\nWhether to automatically mount the current working directory which contains your checked out codebase. Mounts onto `/workdir`, unless `workdir` is set, in which case that will be used.\n\nIf there's a git mirror path and `mount-checkout` is enabled, the [mirror path](https://buildkite.com/docs/pipelines/environment-variables#BUILDKITE_REPO_MIRROR) is mounted into the docker container as an added volume. Otherwise, the git mirror path will have to be explicitly added as an extra volume to mount into the container.\n\nDefault: `true`\n\n### `chown` (optional, boolean)\n\nWhether to `chown` the directory mounted with `mount-checkout` to the Buildkite agent user before exiting, to ensure that the agent can clean up any additional files created there. This will happen even if the command fails or is cancelled. This option has no effect on Windows or if `mount-checkout` is false.\n\nPrefer using `propagate-uid-gid` over this option, as the `chown`–which can take some time if your checkout is of considerable size—is likely not needed at all in that case.\n\nDefault: `false`\n\n### `chown-image` (optional, string)\n\nThe Docker image in which to run the `chown` command.\n\nDefault: `busybox`\n\n### `mount-buildkite-agent` (optional, boolean)\n\nWhether to automatically mount the `buildkite-agent` binary from the host agent machine into the container.\n\nSet to `true` if you want to enable and are sure that the binary running in the agent is compatible with the container's architecture and environment (for example, don't try to mount the OS X or Windows agent binary in a container running linux).\n\n**Important:** When using Windows agents, you must define the `BUILDKITE_AGENT_BINARY_PATH` environment variable with the full path to the agent executable (for example, `C:\\buildkite-agent.exe`).\n\nDefault: `false`\n\n**Important:** enabling this option will share the `BUILDKITE_AGENT_TOKEN` and `BUILDKITE_AGENT_JOB_API_TOKEN` environment variables (and other related ones) with the container if present.\n\n### `mount-ssh-agent` (optional, boolean or string)\n\nWhether to mount the ssh-agent socket (at `/ssh-agent`) from the host agent machine into the container or not. Instead of just `true` or `false`, you can specify absolute path in the container for the home directory of the user used to run on which the agent's `.ssh/known_hosts` will be mounted (by default, `/root`).\n\nDefault: `false`\n\n**Important**: note that for this to work you will need the agent itself to have access to an ssh agent that is: up and running, listening on the appropriate socket, with the appropriate credentials loaded (or to be loaded). Please refer to the [agent's documentation on using SSH agent](https://buildkite.com/docs/agent/v3/ssh-keys#using-multiple-keys-with-ssh-agent) for more information\n\n### `network` (optional, string)\n\nJoin the container to the docker network specified. The network will be created if it does not already exist. See https://docs.docker.com/engine/reference/run/#network-settings for more details.\n\nExample: `test-network`\n\n### `platform` (optional, string)\n\nPlatform defines the target platform containers for this service will run on, using the os[/arch[/variant]] syntax. The values of os, arch, and variant MUST conform to the convention used by the OCI Image Spec.\n\nExample: `linux/arm64`\n\n### `pid` (optional, string)\n\nPID namespace provides separation of processes. The PID Namespace removes the view of the system processes, and allows process ids to be reused including pid 1. See https://docs.docker.com/engine/reference/run/#pid-settings---pid for more details. By default, all containers have the PID namespace enabled.\n\nExample: `host`\n\n### `gpus` (optional, string)\n\nGPUs selector. Dependencies: nvidia-container-runtime\n\nExample: `all`\n\n### `pull-retries` (optional, int)\n\nA number of times to retry failed docker pull. Defaults to 3. Only applies when `always-pull` is enabled.\n\n### `runtime` (optional, string)\n\nSpecify an explicit docker runtime. See the [docker run options documentation](https://docs.docker.com/engine/reference/commandline/run/#options) for more details.\n\nExample: `nvidia`\n\n### `ipc` (optional, string)\n\nSpecify the IPC mode to use. See the [docker run options documentation](https://docs.docker.com/engine/reference/commandline/run/#options) for more details.\n\nExample: `host`\n\n### `run-labels` (optional, boolean)\n\nIf set to true, adds useful Docker labels to the container. See [Container Labels](#container-labels) for more info.\n\nThe default is `true`.\n\n### `shell` (optional, array or boolean)\n\nSet the shell to use for the command. Set it to `false` to pass the command directly to the `docker run` command. The default is `[\"/bin/sh\", \"-e\", \"-c\"]` unless you have provided an `entrypoint` or `command`.\n\nExample: `[ \"powershell\", \"-Command\" ]`\n\n### `shm-size` (optional, string)\n\nSet the size of the `/dev/shm` shared memory filesystem mount inside the docker container. If unset, uses the default for the platform (typically `64mb`). See [docker run's runtime constraints documentation](https://docs.docker.com/engine/reference/run/#runtime-constraints-on-resources) for information on allowed formats.\n\nExample: `2gb`\n\n### `skip-checkout` (optional, boolean)\n\nWhether to skip the repository checkout phase.\n\nDefault: `false`\n\n### `storage-opt` (optional, string)\n\nThis allows setting the container rootfs size at the creation time. This is only available for the `devicemapper`, `btrfs`, `overlay2`, `windowsfilter` and `zfs` graph drivers. See [docker documentation](https://docs.docker.com/engine/reference/commandline/run/#set-storage-driver-options-per-container) for more details.\n\nExample: `size=120G`\n\n### `tty` (optional, boolean)\n\nIf set to false, doesn't allocate a TTY. This is useful in some situations where TTY's aren't supported, for instance windows.\n\nDefault: `true` for Linux and macOS, and `false` for Windows.\n\n### `interactive` (optional, boolean)\n\nIf set to false, doesn't connect `stdin` to the process. Some scripts fall back to asking for user input in case of errors, if the process has `stdin` connected and this results in the process waiting for input indefinitely.\n\n### `user` (optional, string)\n\nAllows a user to be set, and override the USER entry in the Dockerfile. See https://docs.docker.com/engine/reference/run/#user for more details.\n\nExample: `root`\n\n### `userns` (optional, string)\n\nAllows to explicitly set the user namespace. This overrides the default docker daemon value. If you use the value `host`, you disable user namespaces for this run. See https://docs.docker.com/engine/security/userns-remap/ for more details. Due to limitations in this feature, a privileged container will override the user specified `userns` value to `host`\n\nExample: `mynamespace`\n\n### `volumes` (optional, array or boolean)\n\nExtra volume mounts to pass to the docker container, in an array. Items are specified as `SOURCE:TARGET`. Each entry corresponds to a Docker CLI `--volume` parameter. Relative local paths are converted to their full-path (for example `./code:/app`).\n\nExample: `[ \"/var/run/docker.sock:/var/run/docker.sock\" ]`\n\n### `expand-volume-vars` (optional, boolean, run only, unsafe)\n\nWhen set to true, it will activate interpolation of variables in the elements of the `volumes` configuration array as well as `workdir`. When turned off (the default), attempting to use variables will fail as the literal `$VARIABLE_NAME` string will be passed to the `-v` option.\n\nEnvironment variable interpolation rules apply here. `$VARIABLE_NAME` is resolved at pipeline upload time, whereas `$$VARIABLE_NAME` is at run time. All things being equal, you likely want `$$VARIABLE_NAME`.\n\n:warning: **Important:** this is considered an unsafe option as the most compatible way to achieve this is to run the strings through `eval` which could lead to arbitrary code execution or information leaking if you don't have complete control of the pipeline\n\n### `tmpfs` (optional, array)\n\nTmpfs mounts to pass to the docker container, in an array. Each entry corresponds to a Docker CLI `--tmpfs` parameter. See Docker's [tmpfs mounts](https://docs.docker.com/storage/tmpfs/) documentation for more information on this feature.\n\nExample: `[ \"/tmp\", \"/root/.cache\" ]`\n\n### `workdir` (optional, string)\n\nThe working directory to run the command in, inside the container. The default is `/workdir`. This path is also used by `mount-checkout` to determine where to mount the checkout in the container.\n\nExample: `/app`\n\n### `sysctls` (optional, array)\n\nSet namespaced kernel parameters in the container. More information can be found in https://docs.docker.com/engine/reference/commandline/run/.\n\nExample: `--sysctl net.ipv4.ip_forward=1`\n\n### `add-caps` (optional, array)\n\nAdd Linux capabilities to the container. Each entry corresponds to a Docker CLI `--cap-add` parameter.\n\n### `drop-caps` (optional, array)\n\nRemove Linux capabilities from the container. Each entry corresponds to a Docker CLI `--cap-drop` parameter.\n\n### `security-opts` (optional, array)\n\nAdd security options to the container. Each entry corresponds to a Docker CLI `--security-opt` parameter.\n\n### `ulimits` (optional, array)\n\nAdd ulimit options to the container. Each entry corresponds to a Docker CLI `--ulimit` parameter.\n\n### `devices` (optional, array)\n\nYou can give builds limited access to a specific device or devices by passing devices to the docker container, in an array. Items are specific as `SOURCE:TARGET` or just `TARGET`. Each entry corresponds to a Docker CLI `--device` parameter.\n\nExample: `[ \"/dev/bus/usb/001/001\" ]`\n\n### `publish` (optional, array)\n\nYou can allow the docker container to publish ports. More information can be found in https://docs.docker.com/config/containers/container-networking/. Each entry corresponds to a Docker CLI `--publish` or `-p` parameter.\n\nExample: `[ \"8080:80\" ]` (Map TCP port 80 in the container to port 8080 on the Docker host.)\n\n### `cpus` (optional, string)\n\nSet the CPU limit to apply when running the container. More information can be found in https://docs.docker.com/config/containers/resource_constraints/#cpu.\n\nExample: `0.5`\n\n### `memory` (optional, string)\n\nSet the memory limit to apply when running the container. More information can\nbe found in https://docs.docker.com/config/containers/resource_constraints/#limit-a-containers-access-to-memory.\n\nExample: `2g`\n\n### `memory-swap` (optional, string)\n\nSet the memory swap limit to apply when running the container. More information\ncan be found in https://docs.docker.com/config/containers/resource_constraints/#limit-a-containers-access-to-memory.\n\nExample: `2g`\n\n### `memory-swappiness` (optional, string)\n\nSet the swappiness level to apply when running the container. More information\ncan be found in https://docs.docker.com/config/containers/resource_constraints/#--memory-swappiness-details.\n\nExample: `0`\n\n## Troubleshooting\n\n### File and Directory Permissions with Volume Mounts\n\nWhen using volume mounts with Docker containers, file and directory permissions can become problematic due to user ID (UID) and group ID (GID) mismatches between the host and container environments.\n\n#### Common Permission Issues\n\n1. **Root-owned files**: Many Docker images run as root by default, creating files owned by root that the host user cannot modify or delete\n2. **Permission denied errors**: Host files may be inaccessible inside the container if UIDs/GIDs don't match\n3. **Build artifacts**: Generated files may have incorrect ownership, preventing cleanup by the Buildkite agent\n\n#### Solutions\n\n**Option 1: Use `propagate-uid-gid` (Recommended)**\n```yml\nsteps:\n  - command: \"make build\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"node:18\"\n          propagate-uid-gid: true\n```\nThis matches the container user's UID/GID to the host user, ensuring files created in volume mounts have correct ownership.\n\n**Option 2: Use `chown` for cleanup**\n```yml\nsteps:\n  - command: \"npm run build\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"node:18\"\n          chown: true\n```\nThis changes ownership of the checkout directory back to the agent user after the container exits.\n\n**Option 3: Specify explicit user**\n```yml\nsteps:\n  - command: \"python setup.py build\"\n    plugins:\n      - docker#v5.13.0:\n          image: \"python:3.9\"\n          user: \"1000:1000\"  # Match your host user's UID:GID\n```\n\n#### Troubleshooting Permission Issues\n\nIf you encounter permission errors:\n1. Check file ownership with `ls -la` on both host and container\n2. Verify UID/GID matching between host user and container user\n3. Consider using `propagate-uid-gid: true` to automatically handle ID mapping\n4. For persistent issues, use `chown: true` as a fallback solution\n\n## Container Labels\n\nWhen running a command, the plugin will automatically add the following Docker labels to the container:\n- `com.buildkite.pipeline_name=${BUILDKITE_PIPELINE_NAME}`\n- `com.buildkite.pipeline_slug=${BUILDKITE_PIPELINE_SLUG}`\n- `com.buildkite.build_number=${BUILDKITE_BUILD_NUMBER}`\n- `com.buildkite.job_id=${BUILDKITE_JOB_ID}`\n- `com.buildkite.job_label=${BUILDKITE_LABEL}`\n- `com.buildkite.step_key=${BUILDKITE_STEP_KEY}`\n- `com.buildkite.agent_name=${BUILDKITE_AGENT_NAME}`\n- `com.buildkite.agent_id=${BUILDKITE_AGENT_ID}`\n\nThese labels can make it easier to query containers on hosts using `docker ps` for example:\n\n```bash\ndocker ps --filter \"label=com.buildkite.job_label=Run tests\"\n```\n\nThis behaviour can be disabled with the `run-labels: false` option.\n\n## Developing\n\nTo run testing, shellchecks and plugin linting use `bk run` with the [Buildkite CLI](https://github.com/buildkite/cli).\n\n```bash\nbk run\n```\n\nOr if you want to run just the tests, you can use the docker [Plugin Tester](https://github.com/buildkite-plugins/buildkite-plugin-tester):\n\n```bash\ndocker run --rm -ti -v \"${PWD}\":/plugin buildkite/plugin-tester:latest\n```\n\n## License\n\nMIT (see [LICENSE](LICENSE))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildkite-plugins%2Fdocker-buildkite-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuildkite-plugins%2Fdocker-buildkite-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildkite-plugins%2Fdocker-buildkite-plugin/lists"}