Creating a Docker container

New release: GitHub Actions is now available in a new limited public beta. This version offers a new workflow configuration and built-in continuous integration and continuous deployment capabilities. We strongly recommend you avoid using it for high-value workflows and content during this public beta period. To request to join the limited public beta, see the GitHub Actions page. For more information, see "About GitHub Actions" in the GitHub Help documentation.

GitHub Support will only provide support for the YAML syntax and no longer provides support for the HCL syntax.

If you participated in the limited public beta and created workflows with the HCL syntax GitHub Actions, you will need to upgrade to the new limited public beta that uses YAML syntax. When your repository is eligible to upgrade, you'll see an invitation in your repository. You must accept the invitation before you can use the new limited public beta.

Once you've upgraded, any workflows that you created with the HCL syntax will need to be updated to the new YAML syntax. To automatically convert your workflows, see "Migrating GitHub Actions from HCL syntax to YAML syntax" in the GitHub Help documentation.

GitHub Actions execute in Docker containers. An action can use an existing publicly available Docker image, or you can create your own Docker image by including a Dockerfile with your code. To learn more about Docker, see the Docker documentation.

A Dockerfile has a file format that contains instructions and arguments, which define the contents and startup behavior of the Docker container. See "Dockerfile reference" for a list of instructions that Docker supports.

The following sections describe how the instructions in a Dockerfile work with the actions declared in the main.workflow file and the visual workflow editor. See "Creating a workflow with GitHub Actions" in the GitHub Help documentation to learn more about the visual workflow editor.

Note: Docker container logs are limited to a maximum size 64 KB.


GitHub actions must be run by the default Docker user (root). Do not use the USER instruction in your Dockerfile, otherwise you won't be able to access the GITHUB_WORKSPACE.


The first instruction in the Dockerfile must be FROM, which selects a base image. These are some best practices when setting the FROM argument:

  • It's recommended to use official Docker images. For example, python: or ruby:.
  • Use a version tag, preferably with a major version, when it exists. For example, node:10.
  • When specifying a Docker image version, don't use latest. For example, don't use node:latest.
  • It's recommended to use Docker images based on the Debian operating system.


GitHub sets the working directory to /github/workspace. You can read the working directory path set by GitHub from the GITHUB_WORKSPACE environment variable. It's recommended to not use the WORKDIR instruction in your Dockerfile. Before the action executes, GitHub will mount /github on top of anything that was at that location in the Docker image and set /github/workspace as the working directory. See Docker's WORKDIR reference documentation for more information.


If an action does not use the runs configuration option, the commands in ENTRYPOINT will execute. The Docker ENTRYPOINT instruction has a shell form and exec form. The Docker ENTRYPOINT documentation recommends using the exec form of the ENTRYPOINT instruction.

When containers use the exec form of the ENTRYPOINT instruction, the args in main.workflow files won't run in a command shell. For example, if the action's args contain an environment variable, the variable will not be substituted. To run args from the main.workflow file directly in the ENTRYPOINT instruction using the exec method, you can use this format to execute a shell:

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

To supply args to a Docker container that uses the exec form in the ENTRYPOINT, we recommend creating a shell script called that you call from the ENTRYPOINT instruction:


Explicitly use the system's POSIX-compliant shell, by adding the #!/bin/sh shebang at the top of the file. The shell script can read the commands from a string:


sh -c "docker $*"

The $* parameter expands the args supplied in an array individually and splits args in a string separated by whitespace.

For example, both of these actions are functionally equivalent:

args passed in string format

action "Tag Docker Image" {
  needs = ["build"]
  uses = "actions/docker/cli@master"
  args = "tag hello octocat/hello:$GITHUB_SHA"

args passed in array format

action "Tag Docker Image" {
  needs = ["build"]
  uses = "actions/docker/cli@master"
  args = ["tag", "hello", "octocat/hello:$GITHUB_SHA"]

Your code must be executable. Make sure the file has execute permissions before using it in a workflow. You can modify the permission from your terminal using this command:

chmod +x

When an 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: \"/\": permission denied": unknown


If the main.workflow file defines args for an action, the args will be used in place of the CMD instruction.

If you use CMD in your Dockerfile, use these guidelines ordered by preference:

  1. Document required arguments and omit them from the CMD instruction.
  2. Use defaults that allow using the action without specifying any args.
  3. If the action exposes a --help flag, or something similar, use that as the default to make your action self-documenting.


You can use the LABEL instruction to show your action in the visual workflow editor.

LABEL key Description The name of the action.
com.github.actions.description A short description of the action.
com.github.actions.icon The name of the Feather icon to use. See "Supported feature icons" for the list of supported icons.
com.github.actions.color The background color used in the visual workflow editor for the action. Can be one of: white, yellow, blue, green, orange, red, purple, or gray-dark.

It's recommended to also include these labels that describe the action:

LABEL key Description
repository The URL of the action's repository.
homepage The URL of the action's home web page.
maintainer The name of the person who maintains the action. You can optionally include an email address. For example, LABEL "maintainer"="Mona the octocat <>".

Supported feather icons

These are the Feather icons supported by the LABEL instruction.

activity airplay alert-circle alert-octagon
alert-triangle align-center align-justify align-left
align-right anchor aperture archive
arrow-down-circle arrow-down-left arrow-down-right arrow-down
arrow-left-circle arrow-left arrow-right-circle arrow-right
arrow-up-circle arrow-up-left arrow-up-right arrow-up
at-sign award bar-chart-2 bar-chart
battery-charging battery bell-off bell
bluetooth bold book-open book
bookmark box briefcase calendar
camera-off camera cast check-circle
check-square check chevron-down chevron-left
chevron-right chevron-up chevrons-down chevrons-left
chevrons-right chevrons-up circle clipboard
clock cloud-drizzle cloud-lightning cloud-off
cloud-rain cloud-snow cloud code
command compass copy corner-down-left
corner-down-right corner-left-down corner-left-up corner-right-down
corner-right-up corner-up-left corner-up-right cpu
credit-card crop crosshair database
delete disc dollar-sign download-cloud
download droplet edit-2 edit-3
edit external-link eye-off eye
facebook fast-forward feather file-minus
file-plus file-text file film
filter flag folder-minus folder-plus
folder gift git-branch git-commit
git-merge git-pull-request globe grid
hard-drive hash headphones heart
help-circle home image inbox
info italic layers layout
life-buoy link-2 link list
loader lock log-in log-out
mail map-pin map maximize-2
maximize menu message-circle message-square
mic-off mic minimize-2 minimize
minus-circle minus-square minus monitor
moon more-horizontal more-vertical move
music navigation-2 navigation octagon
package paperclip pause-circle pause
percent phone-call phone-forwarded phone-incoming
phone-missed phone-off phone-outgoing phone
pie-chart play-circle play plus-circle
plus-square plus pocket power
printer radio refresh-ccw refresh-cw
repeat rewind rotate-ccw rotate-cw
rss save scissors search
send server settings share-2
share shield-off shield shopping-bag
shopping-cart shuffle sidebar skip-back
skip-forward slash sliders smartphone
speaker square star stop-circle
sun sunrise sunset tablet
tag target terminal thermometer
thumbs-down thumbs-up toggle-left toggle-right
trash-2 trash trending-down trending-up
triangle truck tv type
umbrella underline unlock upload-cloud
upload user-check user-minus user-plus
user-x user users video-off
video voicemail volume-1 volume-2
volume-x volume watch wifi-off
wifi wind x-circle x-square
x zap-off zap zoom-in

Supported Linux capabilities

GitHub Actions support the Linux capabilities that Docker supports. See "Runtime privilege and Linux capabilities" in the Docker docs for details about Linux capability support in Docker. To learn more about Linux capabilities, see "Overview of Linux capabilities" in the Linux man pages.

Capabilities can't be added and removed. GitHub Actions supports this list of capabilities, which are allowed in Docker by default:

Capability Key Capability Description
SETPCAP Modify process capabilities.
MKNOD Create special files using mknod(2).
AUDIT_WRITE Write records to kernel auditing log.
CHOWN Make arbitrary changes to file UIDs and GIDs (see chown(2)).
NET_RAW Use RAW and PACKET sockets.
DAC_OVERRIDE Bypass file read, write, and execute permission checks.
FOWNER Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file.
FSETID Don’t clear set-user-ID and set-group-ID permission bits when a file is modified.
KILL Bypass permission checks for sending signals.
SETGID Make arbitrary manipulations of process GIDs and supplementary GID list.
SETUID Make arbitrary manipulations of process UIDs.
NET_BIND_SERVICE Bind a socket to internet domain privileged ports (port numbers less than 1024).
SYS_CHROOT Use chroot(2), change root directory.
SETFCAP Set file capabilities.