Dockerfile support for GitHub Actions

When creating aDockerfilefor a Docker container action, you should be aware of how some Docker instructions interact with GitHub Actions and an action's metadata file.

In this article

About Dockerfile instructions

ADockerfilecontains 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 theUSERinstruction in yourDockerfile,because you won't be able to access theGITHUB_WORKSPACEdirectory. For more information, see "Store information in variables"andUSER referencein the Docker documentation.

FROM

The first instruction in theDockerfilemust beFROM,which selects a Docker base image. For more information, see theFROM referencein the Docker documentation.

These are some best practices when setting theFROMargument:

  • It's recommended to use official Docker images. For example,Pythonorruby.
  • Use a version tag if it exists, preferably with a major version. For example, usenode:10instead ofnode:latest.
  • It's recommended to use Docker images based on theDebianoperating system.

WORKDIR

GitHub sets the working directory path in theGITHUB_WORKSPACEenvironment variable. It's recommended to not use theWORKDIRinstruction in yourDockerfile.Before the action executes, GitHub will mount theGITHUB_WORKSPACEdirectory on top of anything that was at that location in the Docker image and setGITHUB_WORKSPACEas the working directory. For more information, see "Store information in variables"and theWORKDIR referencein the Docker documentation.

ENTRYPOINT

If you defineentrypointin an action's metadata file, it will override theENTRYPOINTdefined in theDockerfile.For more information, see "Metadata syntax for GitHub Actions."

The DockerENTRYPOINTinstruction has ashellform andexecform. The DockerENTRYPOINTdocumentation recommends using theexecform of theENTRYPOINTinstruction. For more information aboutexecandshellform, see theENTRYPOINT referencein the Docker documentation.

You should not useWORKDIRto 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 theENTRYPOINTinstruction, theargsconfigured in the action's metadata file won't run in a command shell. If the action'sargscontain 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_SHAenvironment variable.

ENTRYPOINT["sh","-c","echo$GITHUB_SHA"]

To supplyargsdefined in the action's metadata file to a Docker container that uses theexecform in theENTRYPOINT,we recommend creating a shell script calledentrypoint.shthat you call from theENTRYPOINTinstruction:

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 theargsconfigured in the action's metadata file as arguments toentrypoint.sh.Add the#!/bin/shshebangat the top of theentrypoint.shfile 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.shfile hasexecutepermissions before using it in a workflow. You can modify the permission from your terminal using this command:

chmod +x entrypoint.sh

When anENTRYPOINTshell 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 defineargsin the action's metadata file,argswill override theCMDinstruction specified in theDockerfile.For more information, see "Metadata syntax for GitHub Actions".

If you useCMDin yourDockerfile,follow these guidelines:

  1. Document required arguments in the action's README and omit them from theCMDinstruction.
  2. Use defaults that allow using the action without specifying anyargs.
  3. If the action exposes a--helpflag, 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.