About Dockerfile instructions
ADockerfile
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.
Dockerfile instructions and overrides
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.
USER
Docker actions must be run by the default Docker user (root). Do not use theUSER
instruction in yourDockerfile
,because you won't be able to access theGITHUB_WORKSPACE
directory. For more information, see "Store information in variables"andUSER referencein the Docker documentation.
FROM
The first instruction in theDockerfile
must beFROM
,which selects a Docker base image. For more information, see theFROM referencein the Docker documentation.
These are some best practices when setting theFROM
argument:
- It's recommended to use official Docker images. For example,
Python
orruby
. - Use a version tag if it exists, preferably with a major version. For example, use
node:10
instead ofnode:latest
. - It's recommended to use Docker images based on theDebianoperating system.
WORKDIR
GitHub sets the working directory path in theGITHUB_WORKSPACE
environment variable. It's recommended to not use theWORKDIR
instruction in yourDockerfile
.Before the action executes, GitHub will mount theGITHUB_WORKSPACE
directory on top of anything that was at that location in the Docker image and setGITHUB_WORKSPACE
as the working directory. For more information, see "Store information in variables"and theWORKDIR referencein the Docker documentation.
ENTRYPOINT
If you defineentrypoint
in an action's metadata file, it will override theENTRYPOINT
defined in theDockerfile
.For more information, see "Metadata syntax for GitHub Actions."
The DockerENTRYPOINT
instruction has ashellform andexecform. The DockerENTRYPOINT
documentation recommends using theexecform of theENTRYPOINT
instruction. For more information aboutexecandshellform, see theENTRYPOINT referencein the Docker documentation.
You should not useWORKDIR
to specify your entrypoint in your Dockerfile. Instead, you should use an absolute path. For more information, seeWORKDIR.
If you configure your container to use theexecform of theENTRYPOINT
instruction, theargs
configured in the action's metadata file won't run in a command shell. If the action'sargs
contain an environment variable, the variable will not be substituted. For example, using the followingexecformat will not print the value stored in$GITHUB_SHA
,but will instead print"$GITHUB_SHA"
.
ENTRYPOINT["echo$GITHUB_SHA"]
If you want variable substitution, then either use theshellform or execute a shell directly. For example, using the followingexecformat, you can execute a shell to print the value stored in theGITHUB_SHA
environment variable.
ENTRYPOINT["sh","-c","echo$GITHUB_SHA"]
To supplyargs
defined in the action's metadata file to a Docker container that uses theexecform in theENTRYPOINT
,we recommend creating a shell script calledentrypoint.sh
that you call from theENTRYPOINT
instruction:
ExampleDockerfile
# Container image that runs your code
FROMdebian:9.5-slim
# Copies your code file from your action repository to the filesystem path `/` of the container
COPYentrypoint.sh /entrypoint.sh
# Executes `entrypoint.sh` when the Docker container starts up
ENTRYPOINT["/entrypoint.sh"]
Exampleentrypoint.shfile
Using the example Dockerfile above, GitHub will send theargs
configured in the action's metadata file as arguments toentrypoint.sh
.Add the#!/bin/sh
shebangat the top of theentrypoint.sh
file to explicitly use the system'sPOSIX-compliant shell.
#!/bin/sh
#`$#` expands to the number of arguments and `$@` expands to the supplied `args`
printf '%d args:' "$#"
printf "'%s'" "$@"
printf '\n'
Your code must be executable. Make sure theentrypoint.sh
file hasexecute
permissions before using it in a workflow. You can modify the permission from your terminal using this command:
chmod +x entrypoint.sh
When anENTRYPOINT
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
CMD
If you defineargs
in the action's metadata file,args
will override theCMD
instruction specified in theDockerfile
.For more information, see "Metadata syntax for GitHub Actions".
If you useCMD
in yourDockerfile
,follow these guidelines:
- Document required arguments in the action's README and omit them from the
CMD
instruction. - Use defaults that allow using the action without specifying any
args
. - If the action exposes a
--help
flag, or something similar, use that to make your action self-documenting.
Supported Linux capabilities
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 "Linux kernel capabilities"in the Docker documentation. To learn more about Linux capabilities, see"Overview of Linux capabilities"in the Linux man-pages.