Dockerfile support for GitHub Actions
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.
GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, and GitHub One. GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans. For more information, see "GitHub's products."
Dockerfile contains instructions and arguments that define the contents and startup behavior of a Docker container. For more information about the instructions Docker supports, see "Dockerfile reference" in the Docker documentation.
Some Docker instructions interact with GitHub Actions, and an action's metadata file can override some Docker instructions. Ensure that you are familiar with how your Dockerfile interacts with GitHub Actions to prevent any unexpected behavior.
Docker 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. For more information, see "Using environment variables" and USER reference in the Docker documentation.
The first instruction in the
Dockerfile must be
FROM, which selects a Docker base image. For more information, see the FROM reference in the Docker documentation.
These are some best practices when setting the
- It's recommended to use official Docker images. For example,
- Use a version tag if it exists, preferably with a major version. For example, use
- It's recommended to use Docker images based on the Debian operating system.
GitHub 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 "Using environment variables" and the WORKDIR reference in the Docker documentation.
If you define
entrypoint in an action's metadata file, it will override the
ENTRYPOINT defined in the
Dockerfile. For more information, see "Metadata syntax for GitHub Actions."
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 in the Docker documentation.
If 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
ENTRYPOINT ["echo $GITHUB_SHA"]
If 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.
ENTRYPOINT ["sh", "-c", "echo $GITHUB_SHA"]
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
# Container image that runs your code FROM debian:9.5-slim # Copies your code file from your action repository to the filesystem path `/` of the container COPY entrypoint.sh /entrypoint.sh # Executes `entrypoint.sh` when the Docker container starts up ENTRYPOINT ["/entrypoint.sh"]
Using 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 at the top of the
entrypoint.sh file to explicitly use the system's POSIX-compliant shell.
# `$*` expands the `args` supplied in an `array` individually # or splits `args` in a string separated by whitespace. sh -c "echo $*"
Your 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:
chmod +x entrypoint.sh
ENTRYPOINT shell script is not executable, you'll receive an error similar to this:
Error response from daemon: OCI runtime create failed: container_linux.go:348: starting container process caused "exec: \"/entrypoint.sh\": permission denied": unknown
If 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 for GitHub Actions".
If you use
CMD in your
Dockerfile, follow these guidelines:
- Document required arguments in the action's README and omit them from the
- Use defaults that allow using the action without specifying any
- If the action exposes a
--helpflag, or something similar, use that to make your action self-documenting.
GitHub 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 "Runtime privilege and Linux capabilities" in the Docker documentation. To learn more about Linux capabilities, see "Overview of Linux capabilities" in the Linux man-pages.