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, seeVariables reference andUSER reference in the Docker documentation.

FROM

The first instruction in theDockerfile must beFROM, which selects a Docker base image. For more information, see theFROM reference in 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, usenode:10 instead ofnode:latest.
• It's recommended to use Docker images based on theDebian operating 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, seeVariables reference and theWORKDIR reference in the Docker documentation.

ENTRYPOINT

If you defineentrypoint in an action's metadata file, it will override theENTRYPOINT defined in theDockerfile. For more information, seeMetadata syntax reference.

The DockerENTRYPOINT instruction has ashell form andexec form. The DockerENTRYPOINT documentation recommends using theexec form of theENTRYPOINT instruction. For more information aboutexec andshell form, see theENTRYPOINT reference in 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 theexec form 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 followingexec format 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 theshell form or execute a shell directly. For example, using the followingexec format, 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 theexec form in theENTRYPOINT, we recommend creating a shell script calledentrypoint.sh that you call from theENTRYPOINT instruction:

ExampleDockerfile

# Container image that runs your codeFROM debian:9.5-slim# Copies your code file from your action repository to the filesystem path `/` of the containerCOPY entrypoint.sh /entrypoint.sh# Executes `entrypoint.sh` when the Docker container starts upENTRYPOINT ["/entrypoint.sh"]

Exampleentrypoint.sh file

Using the example Dockerfile above, GitHub will send theargs configured in the action's metadata file as arguments toentrypoint.sh. Add the#!/bin/shshebang at 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, seeMetadata syntax reference.

If you useCMD in yourDockerfile, follow these guidelines:

1. Document required arguments in the action's README and omit them from theCMD instruction.
2. Use defaults that allow using the action without specifying anyargs.
3. 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, seeLinux kernel capabilities in the Docker documentation. To learn more about Linux capabilities, seeOverview of Linux capabilities in the Linux man-pages.