{"meta":{"title":"Dockerfile support for GitHub Actions","intro":"When creating a Dockerfile for a Docker container action, you should be aware of how some Docker instructions interact with GitHub Actions and an action's metadata file.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/reference","title":"Reference"},{"href":"/en/actions/reference/workflows-and-actions","title":"Workflows and actions"},{"href":"/en/actions/reference/workflows-and-actions/dockerfile-support","title":"Dockerfile support"}],"documentType":"article"},"body":"# Dockerfile support for GitHub Actions\n\nWhen creating a Dockerfile for a Docker container action, you should be aware of how some Docker instructions interact with GitHub Actions and an action's metadata file.\n\n### USER\n\nDocker actions must be run by the default Docker user (root). Do not use the `USER` instruction in your `Dockerfile`, because you won't be able to access the `GITHUB_WORKSPACE` directory. For more information, see [Variables reference](/en/actions/reference/variables-reference#default-environment-variables) and [USER reference](https://docs.docker.com/engine/reference/builder/#user) in the Docker documentation.\n\n### FROM\n\nThe first instruction in the `Dockerfile` must be `FROM`, which selects a Docker base image. For more information, see the [FROM reference](https://docs.docker.com/engine/reference/builder/#from) in the Docker documentation.\n\nThese are some best practices when setting the `FROM` argument:\n\n* It's recommended to use official Docker images. For example, `python` or `ruby`.\n* Use a version tag if it exists, preferably with a major version. For example, use `node:10` instead of `node:latest`.\n* It's recommended to use Docker images based on the [Debian](https://www.debian.org/) operating system.\n\n### WORKDIR\n\nGitHub sets the working directory path in the `GITHUB_WORKSPACE` environment variable. It's recommended to not use the `WORKDIR` instruction in your `Dockerfile`. Before the action executes, GitHub will mount the `GITHUB_WORKSPACE` directory on top of anything that was at that location in the Docker image and set `GITHUB_WORKSPACE` as the working directory. For more information, see [Variables reference](/en/actions/reference/variables-reference#default-environment-variables) and the [WORKDIR reference](https://docs.docker.com/engine/reference/builder/#workdir) in the Docker documentation.\n\n### ENTRYPOINT\n\nIf you define `entrypoint` in an action's metadata file, it will override the `ENTRYPOINT` defined in the `Dockerfile`. For more information, see [Metadata syntax reference](/en/actions/creating-actions/metadata-syntax-for-github-actions#runsentrypoint).\n\nThe Docker `ENTRYPOINT` instruction has a *shell* form and *exec* form. The Docker `ENTRYPOINT` documentation recommends using the *exec* form of the `ENTRYPOINT` instruction. For more information about *exec* and *shell* form, see the [ENTRYPOINT reference](https://docs.docker.com/engine/reference/builder/#entrypoint) in the Docker documentation.\n\nYou should not use `WORKDIR` to specify your entrypoint in your Dockerfile. Instead, you should use an absolute path. For more information, see [WORKDIR](#workdir).\n\nIf you configure your container to use the *exec* form of the `ENTRYPOINT` instruction, the `args` configured in the action's metadata file won't run in a command shell. If the action's `args` contain an environment variable, the variable will not be substituted. For example, using the following *exec* format will not print the value stored in `$GITHUB_SHA`, but will instead print `\"$GITHUB_SHA\"`.\n\n```dockerfile\nENTRYPOINT [\"echo $GITHUB_SHA\"]\n```\n\nIf you want variable substitution, then either use the *shell* form or execute a shell directly. For example, using the following *exec* format, you can execute a shell to print the value stored in the `GITHUB_SHA` environment variable.\n\n```dockerfile\nENTRYPOINT [\"sh\", \"-c\", \"echo $GITHUB_SHA\"]\n```\n\nTo supply `args` defined in the action's metadata file to a Docker container that uses the *exec* form in the `ENTRYPOINT`, we recommend creating a shell script called `entrypoint.sh` that you call from the `ENTRYPOINT` instruction:\n\n#### Example *Dockerfile*\n\n```dockerfile\n# Container image that runs your code\nFROM debian:9.5-slim\n\n# Copies your code file from your action repository to the filesystem path `/` of the container\nCOPY entrypoint.sh /entrypoint.sh\n\n# Executes `entrypoint.sh` when the Docker container starts up\nENTRYPOINT [\"/entrypoint.sh\"]\n```\n\n#### Example *entrypoint.sh* file\n\nUsing the example Dockerfile above, GitHub will send the `args` configured in the action's metadata file as arguments to `entrypoint.sh`. Add the `#!/bin/sh` [shebang](https://en.wikipedia.org/wiki/Shebang_\\(Unix\\)) at the top of the `entrypoint.sh` file to explicitly use the system's [POSIX](https://en.wikipedia.org/wiki/POSIX)-compliant shell.\n\n```shell\n#!/bin/sh\n\n# `$#` expands to the number of arguments and `$@` expands to the supplied `args`\nprintf '%d args:' \"$#\"\nprintf \" '%s'\" \"$@\"\nprintf '\\n'\n```\n\nYour code must be executable. Make sure the `entrypoint.sh` file has `execute` permissions before using it in a workflow. You can modify the permission from your terminal using this command:\n\n```shell\nchmod +x entrypoint.sh\n```\n\nWhen an `ENTRYPOINT` shell script is not executable, you'll receive an error similar to this:\n\n```shell\nError response from daemon: OCI runtime create failed: container_linux.go:348: starting container process caused \"exec: \\\"/entrypoint.sh\\\": permission denied\": unknown\n```\n\n### CMD\n\nIf you define `args` in the action's metadata file, `args` will override the `CMD` instruction specified in the `Dockerfile`. For more information, see [Metadata syntax reference](/en/actions/creating-actions/metadata-syntax-for-github-actions#runsargs).\n\nIf you use `CMD` in your `Dockerfile`, follow these guidelines:\n\n1. Document required arguments in the action's README and omit them from the `CMD` instruction.\n2. Use defaults that allow using the action without specifying any `args`.\n3. If the action exposes a `--help` flag, or something similar, use that to make your action self-documenting.\n\n## Supported Linux capabilities\n\nGitHub Actions supports the default Linux capabilities that Docker supports. Capabilities can't be added or removed. For more information about the default Linux capabilities that Docker supports, see [Linux kernel capabilities](https://docs.docker.com/engine/security/#linux-kernel-capabilities) in the Docker documentation. To learn more about Linux capabilities, see [Overview of Linux capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) in the Linux man-pages."}